docs/profiling_content_shell_on_android.md

   1 # Profiling Content Shell on Android
   2
   3 Below are the instructions for setting up profiling for Content Shell on
   4 Android. This will let you generate profiles for ContentShell. This will require
   5 linux, building an userdebug Android build, and wiping the device.
   6
   7 [TOC]
   8
   9 ## Prepare your device.
  10
  11 You need an Android 4.2+ device (Galaxy Nexus, Nexus 4, 7, 10, etc.) which you
  12 don’t mind erasing all data, rooting, and installing a userdebug build on.
  13
  14 ## Get and build `content_shell_apk` for Android
  15
  16 (These instructions have been carefully distilled from the
  17 [Android Build Instructions](android_build_instructions.md).)
  18
  19 1.  Get the code! You’ll want a second checkout as this will be
  20     android-specific. You know the drill:
  21     http://dev.chromium.org/developers/how-tos/get-the-code
  22 1.  Append this to your `.gclient` file: `target_os = ['android']`
  23 1.  Create `chromium.gyp_env` next to your `.gclient` file:
  24     `echo "{ 'GYP_DEFINES': 'OS=android', }" > chromium.gyp_env`
  25 1.  (Note: All these scripts assume you’re using "bash" (default) as your
  26     shell.)
  27 1.  Sync and runhooks (be careful not to run hooks on the first sync):
  28
  29     ```
  30     gclient sync --nohooks
  31     . build/android/envsetup.sh
  32     gclient runhooks
  33     ```
  34
  35 1.  No need to install any API Keys.
  36 1.  Install Oracle’s Java: http://goo.gl/uPRSq. Grab the appropriate x64 .bin
  37     file, `chmod +x`, and then execute to extract. You then move that extracted
  38     tree into /usr/lib/jvm/, rename it java-6-sun and set:
  39
  40     ```
  41     export JAVA_HOME=/usr/lib/jvm/java-6-sun
  42     export ANDROID_JAVA_HOME=/usr/lib/jvm/java-6-sun
  43     ```
  44
  45 1.  Type ‘`java -version`’ and make sure it says java version `1.6.0_35` without
  46     any mention of openjdk before proceeding.
  47 1.  `sudo build/install-build-deps-android.sh`
  48 1.  Time to build!
  49
  50     ```
  51     ninja -C out/Release content_shell_apk
  52     ```
  53
  54 ## Setup the physical device
  55
  56 Plug in your device. Make sure you can talk to your device, try "`adb shell ls`"
  57
  58 ## Root your device and install a userdebug build
  59
  60 1.  This may require building your own version of Android:
  61     http://source.android.com/source/building-devices.html
  62 1.  A build that works is: `manta / android-4.2.2_r1` or
  63     `master / full_manta-userdebug`.
  64
  65 ## Root your device
  66
  67 1.  Run `adb root`. Every time you connect your device you’ll want to run this.
  68 1.  If adb is not available, make sure to run `. build/android/envsetup.sh`
  69
  70 If you get the error `error: device offline`, you may need to become a developer
  71 on your device before Linux will see it. On Jellybean 4.2.1 and above this
  72 requires going to “about phone” or “about tablet” and clicking the build number
  73 7 times:
  74 http://androidmuscle.com/how-to-enable-usb-debugging-developer-options-on-nexus-4-and-android-4-2-devices/
  75
  76 ## Run a Telemetry perf profiler
  77
  78 You can run any Telemetry benchmark with `--profiler=perf`, and it will:
  79
  80 1.  Download `perf` and `perfhost`
  81 1.  Install on your device
  82 1.  Run the test
  83 1.  Setup symlinks to work with the `--symfs` parameter
  84
  85 You can also run "manual" tests with Telemetry, more information here:
  86 http://www.chromium.org/developers/telemetry/profiling#TOC-Manual-Profiling---Android
  87
  88 The following steps describe building `perf`, which is no longer necessary if
  89 you use Telemetry.
  90
  91 ## Install `/system/bin/perf` on your device (not needed for Telemetry)
  92
  93     # From inside the android source tree (not inside Chromium)
  94     mmm external/linux-tools-perf/
  95     adb remount # (allows you to write to the system image)
  96     adb sync
  97     adb shell perf top # check that perf can get samples (don’t expect symbols)
  98
  99 ## Enable profiling
 100
 101 Rebuild `content_shell_apk` with profiling enabled
 102
 103     export GYP_DEFINES="$GYP_DEFINES profiling=1"
 104     build/gyp_chromium
 105     ninja -C out/Release content_shell_apk
 106
 107 ## Install ContentShell
 108
 109 Install with the following:
 110
 111     build/android/adb_install_apk.py \
 112         --apk out/Release/apks/ContentShell.apk \
 113         --apk_package org.chromium.content_shell
 114
 115 ## Run ContentShell
 116
 117 Run with the following:
 118
 119     ./build/android/adb_run_content_shell
 120
 121 If `content_shell` “stopped unexpectedly” use `adb logcat` to debug. If you see
 122 ResourceExtractor exceptions, a clean build is your solution.
 123 https://crbug.com/164220
 124
 125 ## Setup a `symbols` directory with symbols from your build (not needed for Telemetry)
 126
 127 1.  Figure out exactly what path `content_shell_apk` (or chrome, etc) installs
 128     to.
 129     *   On the device, navigate ContentShell to about:crash
 130
 131
 132     adb logcat | grep libcontent_shell_content_view.so
 133
 134 You should find a path that’s something like
 135 `/data/app-lib/org.chromium.content_shell-1/libcontent_shell_content_view.so`
 136
 137 1.  Make a symbols directory
 138     ```
 139     mkdir symbols (this guide assumes you put this next to src/)
 140     ```
 141 1.  Make a symlink from your symbols directory to your un-stripped
 142     `content_shell`.
 143
 144     ```
 145     # Use whatever path in app-lib you got above
 146     mkdir -p symbols/data/app-lib/org.chromium.content_shell-1
 147     ln -s `pwd`/src/out/Release/lib/libcontent_shell_content_view.so \
 148         `pwd`/symbols/data/app-lib/org.chromium.content_shell-1
 149     ```
 150
 151 ## Install `perfhost_linux` locally (not needed for Telemetry)
 152
 153 Note: modern versions of perf may also be able to process the perf.data files
 154 from the device.
 155
 156 1.  `perfhost_linux` can be built from:
 157     https://android.googlesource.com/platform/external/linux-tools-perf/.
 158 1.  Place `perfhost_linux` next to symbols, src, etc.
 159
 160     chmod a+x perfhost_linux
 161
 162 ## Actually record a profile on the device!
 163
 164 Run the following:
 165
 166     adb shell ps | grep content (look for the pid of the sandboxed_process)
 167     adb shell perf record -g -p 12345 sleep 5
 168     adb pull /data/perf.data
 169
 170
 171 ## Create the report
 172
 173 1.  Run the following:
 174
 175     ```
 176     ./perfhost_linux report -g -i perf.data --symfs symbols/
 177     ```
 178
 179 1.  If you don’t see chromium/webkit symbols, make sure that you built/pushed
 180     Release, and that the symlink you created to the .so is valid!
 181 1.  If you have symbols, but your callstacks are nonsense, make sure you ran
 182     `build/gyp_chromium` after setting `profiling=1`, and rebuilt.
 183
 184 ## Add symbols for the kernel
 185
 186 1.  By default, /proc/kallsyms returns 0 for all symbols, to fix this, set
 187     `/proc/sys/kernel/kptr_restrict` to `0`:
 188
 189     ```
 190     adb shell echo “0” > /proc/sys/kernel/kptr_restrict
 191     ```
 192
 193 1.  See http://lwn.net/Articles/420403/ for explanation of what this does.
 194
 195     ```
 196     adb pull /proc/kallsyms symbols/kallsyms
 197     ```
 198
 199 1.  Now add --kallsyms to your perfhost\_linux command:
 200     ```
 201     ./perfhost_linux report -g -i perf.data --symfs symbols/ \
 202         --kallsyms=symbols/kallsyms
 203     ```