diff options
Diffstat (limited to 'en/devices/tech/debug/index.html')
| -rw-r--r-- | en/devices/tech/debug/index.html | 272 |
1 files changed, 145 insertions, 127 deletions
diff --git a/en/devices/tech/debug/index.html b/en/devices/tech/debug/index.html index 49881821..b2f4c140 100644 --- a/en/devices/tech/debug/index.html +++ b/en/devices/tech/debug/index.html @@ -23,102 +23,167 @@ -<p>This page contains a summary of useful tools and related commands for -debugging, tracing, and profiling native Android platform code. The pages -within this section contain detailed information on other debugging tools for -use during development of platform-level features.</p> - -<p>For example, you may learn how to explore system services with <a -href="dumpsys.html">Dumpsys</a> and evaluate <a -href="netstats.html">network</a> and <a href="procstats.html">RAM</a> use. See -the subpages for tools and methods not described below.</p> - -<h2 id=debuggerd>debuggerd</h2> - -<p>The <code>debuggerd</code> process dumps registers and unwinds the -stack. When a dynamically-linked executable starts, several signal handlers are -registered that connect to <code>debuggerd</code> (or <code>debuggerd64)</code> in the event that signal -is sent to the process.</p> +<p>This section summarizes useful tools and related commands for debugging, +tracing, and profiling native Android platform code when developing +platform-level features. This page covers use of <code>debuggerd</code>, a +daemon process for collecting error information after applications crash, and +the GNU Project debugger (GDB).</p> + +<p>Other pages in this section explore system services with +<a href="/devices/tech/debug/dumpsys.html">Dumpsys</a>, viewing +<a href="/devices/tech/debug/native-memory.html">native memory</a>, +<a href="/devices/tech/debug/netstats.html">network</a>, and +<a href="/devices/tech/debug/procstats.html">RAM</a> usage, using +<a href="/devices/tech/debug/asan.html">AddressSanitizer</a> to detect memory +bugs in native code, evaluating +<a href="/devices/tech/debug/eval_perf.html"> performance issues</a> (includes +<a href="/devices/tech/debug/systrace">systrace</a>), and several other +debugging tools.</p> + +<h2 id=debuggerd>Using debuggerd</h2> + +<p>The <code>debuggerd</code> process dumps registers and unwinds the stack. +When a dynamically linked executable starts, several signal handlers are +registered that connect to <code>debuggerd</code> (or <code>debuggerd64)</code> +in the event that signals (such as SIGSEGV or SIGABRT) are sent to the process.</p> <p>It's possible for <code>debuggerd</code> to attach only if nothing else is -already attached. This means that using tools like <code>strace</code> or -<code>gdb</code> will prevent <code>debuggerd</code> from working. Also, if -you call <code>prctl(PR_SET_DUMPABLE, 0)</code> you can prevent -<code>debuggerd</code> from attaching. This can be useful if you wish to -explicitly opt out of crash reporting.</p> +already attached, which means using tools such as <code>strace</code> or +<code>gdb</code> will prevent <code>debuggerd</code> from working. You can also +explicitly prevent <code>debuggerd</code> from attaching by calling +<code>prctl(PR_SET_DUMPABLE, 0)</code>, which can be useful when you need to +opt out of crash reporting.</p> -<p>Here is example output (with timestamps and extraneous information removed):</p> +<p>Example <code>debuggerd</code> output (with timestamps and extraneous +information removed):</p> <pre class="no-pretty-print"> *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** -Build fingerprint: 'Android/aosp_flounder/flounder:5.1.51/AOSP/enh08201009:eng/test-keys' +Build fingerprint: 'Android/aosp_angler/angler:7.1.1/NYC/enh12211018:eng/test-keys' Revision: '0' ABI: 'arm' -pid: 1656, tid: 1656, name: crasher >>> crasher <<< -signal 6 (SIGABRT), code -6 (SI_TKILL), fault addr -------- -Abort message: 'some_file.c:123: some_function: assertion "false" failed' - r0 00000000 r1 00000678 r2 00000006 r3 f70b6dc8 - r4 f70b6dd0 r5 f70b6d80 r6 00000002 r7 0000010c - r8 ffffffed r9 00000000 sl 00000000 fp ff96ae1c - ip 00000006 sp ff96ad18 lr f700ced5 pc f700dc98 cpsr 400b0010 +pid: 17946, tid: 17949, name: crasher >>> crasher <<< +signal 11 (SIGSEGV), code 1 (SEGV_MAPERR), fault addr 0xc + r0 0000000c r1 00000000 r2 00000000 r3 00000000 + r4 00000000 r5 0000000c r6 eccdd920 r7 00000078 + r8 0000461a r9 ffc78c19 sl ab209441 fp fffff924 + ip ed01b834 sp eccdd800 lr ecfa9a1f pc ecfd693e cpsr 600e0030 + backtrace: - #00 pc 00042c98 /system/lib/libc.so (tgkill+12) - #01 pc 00041ed1 /system/lib/libc.so (pthread_kill+32) - #02 pc 0001bb87 /system/lib/libc.so (raise+10) - #03 pc 00018cad /system/lib/libc.so (__libc_android_abort+34) - #04 pc 000168e8 /system/lib/libc.so (abort+4) - #05 pc 0001a78f /system/lib/libc.so (__libc_fatal+16) - #06 pc 00018d35 /system/lib/libc.so (__assert2+20) - #07 pc 00000f21 /system/xbin/crasher - #08 pc 00016795 /system/lib/libc.so (__libc_init+44) - #09 pc 00000abc /system/xbin/crasher + #00 pc 0004793e /system/lib/libc.so (pthread_mutex_lock+1) + #01 pc 0001aa1b /system/lib/libc.so (readdir+10) + #02 pc 00001b91 /system/xbin/crasher (readdir_null+20) + #03 pc 0000184b /system/xbin/crasher (do_action+978) + #04 pc 00001459 /system/xbin/crasher (thread_callback+24) + #05 pc 00047317 /system/lib/libc.so (_ZL15__pthread_startPv+22) + #06 pc 0001a7e5 /system/lib/libc.so (__start_thread+34) Tombstone written to: /data/tombstones/tombstone_06 </pre> -<p>This can be pasted into <code>development/scripts/stack</code> to get a more detailed unwind -with line number information (assuming the unstripped binaries can be found).</p> - -<p>Some libraries on the system are built with <code>LOCAL_STRIP_MODULE := -keep_symbols</code> to provide usable backtraces directly from <code>debuggerd</code>. This makes -your library or executable slightly larger, but not nearly as large as an -unstripped version.</p> +<p>The last line of <code>debuggerd</code> output dumps a summary to the log and +writes a full <em>tombstone</em> to disk. The tombstone is simply a file with +extra data about the crashed process; it contains information that can be +helpful in debugging a crash, in particular the stack traces for all threads in +the crashing process (not just the thread that caught the signal) and a full +memory map.</p> + +<p>Assuming the unstripped binaries can be found, you can get a more detailed +unwind with line number information by pasting the above example into +<code>development/scripts/stack</code>:</p> + +<p class="key-point"><strong>Tip:</strong> For convenience, if you've lunched +<code>stack</code> will be on your $PATH already so you don't need to give the +full path.</p> + +<pre> +$ development/tools/stack +Reading native crash info from stdin +03-02 23:53:49.477 17951 17951 F DEBUG : *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** +03-02 23:53:49.477 17951 17951 F DEBUG : Build fingerprint: 'Android/aosp_angler/angler:7.1.1/NYC/enh12211018:eng/test-keys' +03-02 23:53:49.477 17951 17951 F DEBUG : Revision: '0' +03-02 23:53:49.477 17951 17951 F DEBUG : ABI: 'arm' +03-02 23:53:49.478 17951 17951 F DEBUG : pid: 17946, tid: 17949, name: crasher >>> crasher <<< +03-02 23:53:49.478 17951 17951 F DEBUG : signal 11 (SIGSEGV), code 1 (SEGV_MAPERR), fault addr 0xc +03-02 23:53:49.478 17951 17951 F DEBUG : r0 0000000c r1 00000000 r2 00000000 r3 00000000 +03-02 23:53:49.478 17951 17951 F DEBUG : r4 00000000 r5 0000000c r6 eccdd920 r7 00000078 +03-02 23:53:49.478 17951 17951 F DEBUG : r8 0000461a r9 ffc78c19 sl ab209441 fp fffff924 +03-02 23:53:49.478 17951 17951 F DEBUG : ip ed01b834 sp eccdd800 lr ecfa9a1f pc ecfd693e cpsr 600e0030 +03-02 23:53:49.491 17951 17951 F DEBUG : +03-02 23:53:49.491 17951 17951 F DEBUG : backtrace: +03-02 23:53:49.492 17951 17951 F DEBUG : #00 pc 0004793e /system/lib/libc.so (pthread_mutex_lock+1) +03-02 23:53:49.492 17951 17951 F DEBUG : #01 pc 0001aa1b /system/lib/libc.so (readdir+10) +03-02 23:53:49.492 17951 17951 F DEBUG : #02 pc 00001b91 /system/xbin/crasher (readdir_null+20) +03-02 23:53:49.492 17951 17951 F DEBUG : #03 pc 0000184b /system/xbin/crasher (do_action+978) +03-02 23:53:49.492 17951 17951 F DEBUG : #04 pc 00001459 /system/xbin/crasher (thread_callback+24) +03-02 23:53:49.492 17951 17951 F DEBUG : #05 pc 00047317 /system/lib/libc.so (_ZL15__pthread_startPv+22) +03-02 23:53:49.492 17951 17951 F DEBUG : #06 pc 0001a7e5 /system/lib/libc.so (__start_thread+34) +03-02 23:53:49.492 17951 17951 F DEBUG : Tombstone written to: /data/tombstones/tombstone_06 +Reading symbols from /huge-ssd/aosp-arm64/out/target/product/angler/symbols +Revision: '0' +pid: 17946, tid: 17949, name: crasher >>> crasher <<< +signal 11 (SIGSEGV), code 1 (SEGV_MAPERR), fault addr 0xc + r0 0000000c r1 00000000 r2 00000000 r3 00000000 + r4 00000000 r5 0000000c r6 eccdd920 r7 00000078 + r8 0000461a r9 ffc78c19 sl ab209441 fp fffff924 + ip ed01b834 sp eccdd800 lr ecfa9a1f pc ecfd693e cpsr 600e0030 +Using arm toolchain from: /huge-ssd/aosp-arm64/prebuilts/gcc/linux-x86/arm/arm-linux-androideabi-4.9/bin/ + +Stack Trace: + RELADDR FUNCTION FILE:LINE + 0004793e pthread_mutex_lock+2 bionic/libc/bionic/pthread_mutex.cpp:515 + v------> ScopedPthreadMutexLocker bionic/libc/private/ScopedPthreadMutexLocker.h:27 + 0001aa1b readdir+10 bionic/libc/bionic/dirent.cpp:120 + 00001b91 readdir_null+20 system/core/debuggerd/crasher.cpp:131 + 0000184b do_action+978 system/core/debuggerd/crasher.cpp:228 + 00001459 thread_callback+24 system/core/debuggerd/crasher.cpp:90 + 00047317 __pthread_start(void*)+22 bionic/libc/bionic/pthread_create.cpp:202 (discriminator 1) + 0001a7e5 __start_thread+34 bionic/libc/bionic/clone.cpp:46 (discriminator 1) +</pre> -<p>Note also the last line of <code>debuggerd</code> output --- in addition to dumping a -summary to the log, <code>debuggerd</code> writes a full “tombstone” to disk. This contains -a lot of extra information that can be helpful in debugging a crash, in -particular the stack traces for all the threads in the crashing process (not -just the thread that caught the signal) and a full memory map.</p> +<p class="note"><strong>Note:</strong> Some system libraries are built with +<code>LOCAL_STRIP_MODULE := keep_symbols</code> to provide usable backtraces +directly from <code>debuggerd</code> without taking up anywhere near as much +space as an unstripped version.</p> -<p>For more information about diagnosing native crashes and tombstones, see -<a href="/devices/tech/debug/native-crash.html">Diagnosing Native Crashes</a></p> +<p>You can also <code>stack</code> an entire tombstone. Example:</p> +<pre> +$ stack < FS/data/tombstones/tombstone_05 +</pre> +<p>This is useful if you've just unzipped a bugreport in the current directory. +For more information about diagnosing native crashes and tombstones, see +<a href="/devices/tech/debug/native-crash.html">Diagnosing Native Crashes</a>. +</p> <h3>Getting a stack trace/tombstone from a running process</h3> -<p>You can also ask <code>debuggerd</code> to operate on a running process by invoking it from -the command line. Given a PID it will dump a full tombstone to stdout, or you can use -<code>-b</code> (short for <code>--backtrace</code>) to just get the stack for every thread in the -given process. +<p>You can also use <code>debuggerd</code> on a running process. From the +command line, invoke <code>debuggerd</code> using a process ID (PID) to dump the +full tombstone to <code>stdout</code>. To get just the stack for every thread in +the process, include the <code>-b</code> or <code>--backtrace</code> flag. + +<h2 id=native>Using GDB</h2> -<h2 id=native>Native Debugging with GDB</h2> +<p>The GNU Project debugger (GDB) is a commonly used Unix debugger.</p> <h3 id=running>Debugging a running app</h3> -<p>To connect to an already-running app or native daemon, use <code>gdbclient</code>.</p> +<p>To connect to an already-running app or native daemon, use +<code>gdbclient</code> with a PID. For example, to debug the process with PID +1234, run:</p> -<p>Current versions of gdbclient just require the process ID (PID). So to debug a process with -PID 1234, simply run:</p> <pre class="no-pretty-print"> $ gdbclient 1234 </pre> -<p>The script will set up port forwarding, start the appropriate -<code>gdbserver</code> on the device, start the appropriate <code>gdb</code> on -the host, configure <code>gdb</code> to find symbols, and connect + +<p>The script sets up port forwarding, starts the appropriate +<code>gdbserver</code> on the device, starts the appropriate <code>gdb</code> on +the host, configures <code>gdb</code> to find symbols, and connects <code>gdb</code> to the remote <code>gdbserver</code>.</p> <h3 id=starts>Debugging a native process as it starts</h3> -<p>If you want to debug a process as it starts, you’ll need to use <code>gdbserver</code> -or <code>gdbserver64</code> manually, but that’s easy too:</p> +<p>To debug a process as it starts, use <code>gdbserver</code> or +<code>gdbserver64</code> (for 64-bit processes). For example:</p> <pre class="no-pretty-print"> $ adb shell gdbserver :5039 /system/bin/<em>my_test_app</em> @@ -126,18 +191,18 @@ Process my_test_app created; pid = 3460 Listening on port 5039 </pre> -<p>Identify the app’s PID from the <code>gdbserver</code> output, and then in -another window:</p> +<p>Next, identify the application PID from the <code>gdbserver</code> output and +use it in another terminal window:</p> <pre class="no-pretty-print"> $ gdbclient <em><app pid></em> </pre> -<p>Then enter <strong>continue</strong> at the <code>gdb</code> prompt.</p> +<p>Finally, enter <strong>continue</strong> at the <code>gdb</code> prompt.</p> -<p>Note that to debug a 64-bit process, you'll need to use <code>gdbserver64</code>. -The error messages from <code>gdb</code> if you made the wrong choice are unhelpful -(along the lines of <code>Reply contains invalid hex digit 59</code>).</p> +<p class="note"><strong>Note:</strong> If you use the wrong +<code>gdbserver</code>, you'll get an unhelpful error message (such as +"<code>Reply contains invalid hex digit 59</code>").</p> <h3 id=crash>Debugging processes that crash</h3> @@ -152,69 +217,22 @@ $ adb shell setprop debug.debuggerd.wait_for_gdb true $ adb shell setprop debug.db.uid 999999 </pre> -<p>At the end of the usual crash output, <code>debuggerd</code> will give you -instructions on how to connect <code>gdb</code> using the typical command: +<p>At the end of the usual crash output, <code>debuggerd</code> provides +instructions on how to connect <code>gdb</code> using the command: <pre class="no-pretty-print"> $ gdbclient <pid> </pre> <h3 id=symbols>Debugging without symbols</h3> -<p>If you don’t have symbols, sometimes <code>gdb</code> will get confused about the -instruction set it is disassembling (ARM or Thumb). The instruction set that is -chosen as the default when symbol information is missing can be switched -between ARM or Thumb like so:</p> +<p>For 32-bit ARM, if you don’t have symbols, <code>gdb</code> can get confused +about the instruction set it is disassembling (ARM or Thumb). To specify the +instruction set chosen as the default when symbol information is missing, set +the following property:</p> <pre class="no-pretty-print"> -$ set arm fallback-mode arm # or 'thumb' -</pre> - -<h2 id=symbols>Other tools</h2> - -<h3 id=valgrind>Valgrind</h3> - -<p>The following steps show you how to use <a -href="http://valgrind.org/">Valgrind</a> on Android. This tool suite contains a -number of tools including Memcheck for detecting memory-related errors in C and -C++.</p> - -<p>Android platform developers usually use -<a href="/devices/tech/debug/asan.html">AddressSanitizer (ASan)</a> rather than valgrind.</p> - -<ol> - <li>To build Valgrind, run: -<pre class="no-pretty-print"> -$ mmma -j6 external/valgrind -</pre> - <li>Set up the temporary directory: -<pre class="no-pretty-print"> -$ adb shell mkdir /data/local/tmp -$ adb shell chmod 777 /data/local/tmp -</pre> - <li>Run the system server with Valgrind: -<pre class="no-pretty-print"> -$ adb shell setprop wrap.system_server "logwrapper valgrind" -$ adb shell stop && adb shell start -</pre> - <li>For debug symbols, push unstripped libraries to <code>/data/local/symbols</code>: -<pre class="no-pretty-print"> -$ adb shell mkdir /data/local/symbols -$ adb push $OUT/symbols /data/local/symbols +$ set arm fallback-mode arm # or thumb </pre> - <li>To use Valgrind during boot up, edit <code>out/target/product/XXXX/root/init.rc</code> and -change:<br> -<code>service example /system/bin/foo --arg1 --arg2</code><br> -to:<br> -<code>service example /system/bin/logwrapper /system/bin/valgrind /system/bin/foo --arg1 --arg2</code><br> -To see the effects, you need to create a <code>boot.img</code> and reflash the device. -</ol> - -<h3 id=systrace>Systrace</h3> - -<p>See <a -href="https://developer.android.com/tools/help/systrace.html">Systrace on -developer.android.com</a> for deriving execution times of applications and -other Android system processes.</p> </body> </html> |