docs/profiling_content_shell_on_android.md

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