1 page.title=Debugging Native Android Platform Code 2 @jd:body 3 4 <!-- 5 Copyright 2015 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 <div id="qv-wrapper"> 20 <div id="qv"> 21 <h2>In this document</h2> 22 <ol id="auto-toc"></ol> 23 </div> 24 </div> 25 26 <p>This page contains a summary of useful tools and related commands for 27 debugging, tracing, and profiling native Android platform code. The pages 28 within this section contain detailed information on other debugging tools for 29 use during development of platform-level features.</p> 30 31 <p>For example, you may learn how to explore system services with <a 32 href="dumpsys.html">Dumpsys</a> and evaluate <a 33 href="netstats.html">network</a> and <a href="procstats.html">RAM</a> use. See 34 the subpages for tools and methods not described below.</p> 35 36 <h2 id=debuggerd>debuggerd</h2> 37 38 <p>When a dynamically-linked executable starts, several signal handlers are 39 registered that connect to <code>debuggerd</code> (or <code>debuggerd64)</code> in the event that signal 40 is sent to the process. The <code>debuggerd</code> process dumps registers and unwinds the 41 stack. Here is example output (with timestamps and extraneous information removed): </p> 42 43 <pre> 44 *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 45 Build fingerprint: 'Android/aosp_flounder/flounder:5.1.51/AOSP/enh08201009:eng/test-keys' 46 Revision: '0' 47 ABI: 'arm' 48 pid: 1656, tid: 1656, name: crasher >>> crasher <<< 49 signal 6 (SIGABRT), code -6 (SI_TKILL), fault addr -------- 50 Abort message: 'some_file.c:123: some_function: assertion "false" failed' 51 r0 00000000 r1 00000678 r2 00000006 r3 f70b6dc8 52 r4 f70b6dd0 r5 f70b6d80 r6 00000002 r7 0000010c 53 r8 ffffffed r9 00000000 sl 00000000 fp ff96ae1c 54 ip 00000006 sp ff96ad18 lr f700ced5 pc f700dc98 cpsr 400b0010 55 backtrace: 56 #00 pc 00042c98 /system/lib/libc.so (tgkill+12) 57 #01 pc 00041ed1 /system/lib/libc.so (pthread_kill+32) 58 #02 pc 0001bb87 /system/lib/libc.so (raise+10) 59 #03 pc 00018cad /system/lib/libc.so (__libc_android_abort+34) 60 #04 pc 000168e8 /system/lib/libc.so (abort+4) 61 #05 pc 0001a78f /system/lib/libc.so (__libc_fatal+16) 62 #06 pc 00018d35 /system/lib/libc.so (__assert2+20) 63 #07 pc 00000f21 /system/xbin/crasher 64 #08 pc 00016795 /system/lib/libc.so (__libc_init+44) 65 #09 pc 00000abc /system/xbin/crasher 66 Tombstone written to: /data/tombstones/tombstone_06 67 </pre> 68 69 <p>This can be pasted into <code>development/scripts/stack</code> to get a more detailed unwind 70 with line number information (assuming the unstripped binaries can be found).</p> 71 72 <p>Some libraries on the system are built with <code>LOCAL_STRIP_MODULE := 73 keep_symbols</code> to provide usable backtraces directly from debuggerd. This makes 74 your library or executable slightly larger, but not nearly as large as an 75 unstripped version.</p> 76 77 <p>Note also the last line of <code>debuggerd</code> output --- in addition to dumping a 78 summary to the log, <code>debuggerd</code> writes a full tombstone to disk. This contains 79 a lot of extra information that can be helpful in debugging a crash, in 80 particular the stack traces for all the threads in the crashing process (not 81 just the thread that caught the signal) and a full memory map.</p> 82 83 <h2 id=native>Native Debugging with GDB</h2> 84 85 <h3 id=running>Debugging a running app</h3> 86 87 <p>To connect to an already-running app or native daemon, use <code>gdbclient</code>.</p> 88 89 <p>Current versions of gdbclient just require the process ID (PID). So to debug a process with 90 PID 1234, simply run:</p> 91 <pre> 92 $ gdbclient 1234 93 </pre> 94 <p>The script will set up port forwarding, start the appropriate 95 <code>gdbserver</code> on the device, start the appropriate <code>gdb</code> on 96 the host, configure <code>gdb</code> to find symbols, and connect 97 <code>gdb</code> to the remote <code>gdbserver</code>.</p> 98 99 <h3 id=starts>Debugging a native process as it starts</h3> 100 101 <p>If you want to debug a process as it starts, youll need to use <code>gdbserver</code> 102 manually, but thats easy too:</p> 103 104 <pre> 105 $ adb shell gdbserver :5039 /system/bin/<em>my_test_app</em> 106 Process my_test_app created; pid = 3460 107 Listening on port 5039 108 </pre> 109 110 <p>Identify the apps PID from the <code>gdbserver</code> output, and then in 111 another window:</p> 112 113 <pre> 114 $ gdbclient <em><app pid></em> 115 </pre> 116 117 <p>Then enter <strong>continue</strong> at the <code>gdb</code> prompt.</p> 118 119 <h3 id=crash>Debugging processes that crash</h3> 120 121 <p>If you want <code>debuggerd</code> to suspend crashed processes so you can 122 attach <code>gdb</code>, set the appropriate property:</p> 123 124 <pre> 125 $ adb shell setprop debug.db.uid 999999 # <= M 126 $ adb shell setprop debug.debuggerd.wait_for_gdb true # > M 127 </pre> 128 129 <p>At the end of the usual crash output, <code>debuggerd</code> will give you 130 instructions on how to connect <code>gdb</code> using the typical command: 131 <pre> 132 $ gdbclient <pid> 133 </pre> 134 135 <h3 id=symbols>Debugging without symbols</h3> 136 137 <p>If you dont have symbols, sometimes <code>gdb</code> will get confused about the 138 instruction set it is disassembling (ARM or Thumb). The instruction set that is 139 chosen as the default when symbol information is missing can be switched 140 between ARM or Thumb like so:</p> 141 142 <pre> 143 $ set arm fallback-mode arm # or 'thumb' 144 </pre> 145 146 <h2 id=symbols>Other tools</h2> 147 148 <h3 id=valgrind>Valgrind</h3> 149 150 <p>The following steps show you how to use <a 151 href="http://valgrind.org/">Valgrind</a> on Android. This tool suite contains a 152 number of tools including Memcheck for detecting memory-related errors in C and 153 C++.</p> 154 155 <ol> 156 <li>To install Valgrind, run: 157 <pre> 158 $ mmm -j6 external/valgrind 159 </pre> 160 <li>Push Valgrind to the device: 161 <br> 162 <pre> 163 $ adb remount 164 $ adb sync 165 </pre> 166 <li>Set up the temporary directory: 167 <pre> 168 $ adb shell mkdir /data/local/tmp 169 $ adb shell chmod 777 /data/local/tmp 170 </pre> 171 <li>Run the system server with Valgrind: 172 <pre> 173 $ adb root 174 $ adb shell setprop wrap.system_server "logwrapper valgrind" 175 $ adb shell stop && adb shell start 176 </pre> 177 <li>For debug symbols, push unstripped libraries to <code>/data/local/symbols</code>: 178 <pre> 179 $ adb shell mkdir /data/local/symbols 180 $ adb push $OUT/symbols /data/local/symbols 181 </pre> 182 <li>To use Valgrind during boot up, edit <code>out/target/product/XXXX/root/init.rc</code> and 183 change:<br> 184 <code>service example /system/bin/foo --arg1 --arg2</code><br> 185 to:<br> 186 <code>service example /system/bin/logwrapper /system/bin/valgrind /system/bin/foo --arg1 --arg2</code><br> 187 To see the effects, you need to create a <code>boot.img</code> and reflash the device. 188 </ol> 189 190 <h3 id=systrace>Systrace</h3> 191 192 <p>See <a 193 href="https://developer.android.com/tools/help/systrace.html">Systrace on 194 developer.android.com</a> for deriving execution times of applications and 195 other Android system processes.</p> 196
