Improve Android tracing instructions

Tracing of Java applications on Android is quite different from tracing native
executables, so move it to a separate file.

Add instructions on using wrapping support that appeared in Android 4.0, which
simplifies usage of apitrace on Android.

Add a reference to adjust-child-env tool that allows to inject tracing library
on Android without rebuilding and reflashing recovery image.

Signed-off-by: José Fonseca <jose.r.fonseca@gmail.com>

diff --git a/Android.markdown b/Android.markdown
new file mode 100644 (file)
index 0000000..0cbf4de
--- /dev/null
+++ b/Android.markdown
@@ -0,0 +1,71 @@
+Tracing Dalvik VM (Java) applications on Android
+================================================
+
+Android's Java machine, DalvikVM, runs as a system service (started at bootup
+by `init`) and Java applications are run by forks of the initial resident
+process.  Thus, injecting apitrace's tracing library is different from other
+operating systems.
+
+The following discussion assumes that tracing library is copied to '/data':
+
+        adb push /path/to/apitrace/build/wrappers/egltrace.so /data
+
+Tracing on Android 4.0 and newer
+--------------------------------
+
+Starting from Android 4.0 (Ice Cream Sandwich) release, Dalvik supports
+running designated processes with wrappers, in which case a new Java VM is
+started with 'system()' library call for that process.
+
+Obtain the process name of the application to be traced (the one reported in
+`ps` output, such as `com.android.settings`), and set two system properties:
+
+        PROCNAME=com.android.settings
+        adb shell setprop wrap.$PROCNAME LD_PRELOAD=/data/egltrace.so
+        adb shell setprop debug.apitrace.procname $PROCNAME
+
+(the former is read by Dalvik and specifies wrapping prefix, the latter is
+read by apitrace itself and used in case apitrace is preloaded into Java VM
+globally to specify which process should be traced).
+
+Make sure the process is not loaded before starting to trace it, for example
+use `-S` flag to `am start`:
+
+        adb shell am start -S $PROCNAME
+
+Use `adb logcat \*:S apitrace` to examine apitrace debug output.  Trace files
+are saved into '/data/' directory by default:
+
+        adb pull /data/$PROCNAME.trace
+        adb shell rm /data/$PROCNAME.trace
+
+(you need to `chmod 0777 /data` beforehand).
+
+
+Injecting tracing library globally
+----------------------------------
+
+If `LD_PRELOAD` is supported (Android 2.3 "Gingerbread" and newer), it is
+possible to inject `egltrace.so` into the resident Java VM, in which case
+`debug.apitrace.procname` system propery is used to control for which process
+tracing will be active.
+
+Restarting 'zygote' (Java VM) service is not straightforward, since '/init.rc'
+is read only once at system bootup, and restored from the recovery image on
+reboots.   Thus, you either need to augment '/init.rc' in the recovery image
+with `setenv LD_PRELOAD /data/egltrace.so` in `service zygote` section, or you
+can use a tool such as
+[adjust-child-env](https://github.com/amonakov/adjust-child-env) to restart
+the service with modified environment.
+
+Put `adjust-child-env` and a script with the following contents into `/data`:
+
+        stop zygote
+        /data/adjust-child-env 1 /system/bin/app_process LD_PRELOAD=/data/egltrace.so &
+        sleep 1
+        start zygote
+
+The scripts restarts the Java VM ('zygote') with modified environment.
+
+Invoke the script with `adb shell` to prepare for tracing, and then follow the
+Android 4.0 directions.

diff --git a/README.markdown b/README.markdown
index 5fa3ab96089b002e13a11e0cb07a35a2c8a9eea0..eeaaee7806e6b2fb16218a0d64df01d2d43b2e2e 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -151,68 +151,9 @@ To trace the application inside gdb, invoke gdb as:
 
 ### Android ###
 
 
 ### Android ###
 

-The following instructions should work at least for Android Ice Scream
-Sandwitch.
-
-To trace applications started from within the Android VM process
-(`app_process` aka zygote) you'll have to wrap this process and enable
-tracing dynamically for the application to be traced.
-
-- Wrapping the android main VM process:
-
-  In the Android root /init.rc add the `LD_PRELOAD` setting to zygote's
-  environment in the 'service zygote' section:
-
-        service zygote ...
-           setenv LD_PRELOAD /data/egltrace.so
-           ...
-
-  Note that ICS will overwrite the /init.rc during each boot with the
-  version in the recovery image. So you'll have to change the file in
-  your ICS source tree, rebuild and reflash the device.
-  Rebuilding/reflashing only the recovery image should be sufficient.
-
-- Copy egltrace.so to /data
-
-  On the host:
-
-        adb push /path/to/apitrace/build/wrappers/egltrace.so /data
-
-- Adjust file permissions to store the trace file:
-
-  By default egltrace.so will store the trace in
-  `/data/app_process.trace`. For this to work for applications running
-  with a uid other than 0, you have to allow writes to the `/data`
-  directory on the device:
-
-        chmod 0777 /data
-
-- Enable tracing for a specific process name:
-
-  To trace for example the Settings application:
-
-        setprop debug.apitrace.procname com.android.settings
-
-  In general this name will match what `ps` reports.
-
-- Start the application:
-
-  If the application was already running, for example due to ICS's way
-  of pre-starting the apps, you might have to kill the application
-  first:
-
-        kill <pid of app>
-
-  Launch the application for example from the application menu.
-
-To trace standalone applications do:
-
-    adb push /path/to/apitrace/build/wrappers/egltrace.so /data
-    adb shell
-    # cd /data/local/tmp
-    # LD_PRELOAD=/data/egltrace.so test-opengl-gl2_basic
-    adb pull /data/local/tmp/test-opengl-gl2_basic.trace
-    apitrace replay test-opengl-gl2_basic.trace
+To trace standalone native OpenGL ES applications, use
+`LD_PRELOAD=/path/to/egltrace.so /path/to/application` like described in the
+previous section.  To trace Java applications, refer to Android.markdown.

 
 ### Mac OS X ###
 
 
 ### Mac OS X ###