From 644352f611d0a09018e762b10e07d0e153430116 Mon Sep 17 00:00:00 2001 From: Alexander Monakov Date: Fri, 5 Apr 2013 21:53:49 +0400 Subject: [PATCH] Improve Android tracing instructions MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 --- Android.markdown | 71 ++++++++++++++++++++++++++++++++++++++++++++++++ README.markdown | 65 ++------------------------------------------ 2 files changed, 74 insertions(+), 62 deletions(-) create mode 100644 Android.markdown diff --git a/Android.markdown b/Android.markdown new file mode 100644 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 5fa3ab9..eeaaee7 100644 --- a/README.markdown +++ b/README.markdown @@ -151,68 +151,9 @@ To trace the application inside gdb, invoke gdb as: ### 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 - - 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 ### -- 2.43.0