1page.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
27debugging, tracing, and profiling native Android platform code. The pages
28within this section contain detailed information on other debugging tools for
29use during development of platform-level features.</p>
30
31<p>For example, you may learn how to explore system services with <a
32href="dumpsys.html">Dumpsys</a> and evaluate <a
33href="netstats.html">network</a> and <a href="procstats.html">RAM</a> use. See
34the subpages for tools and methods not described below.</p>
35
36<h2 id=debuggerd>debuggerd</h2>
37
38<p>The <code>debuggerd</code> process dumps registers and unwinds the
39stack. When a dynamically-linked executable starts, several signal handlers are
40registered that connect to <code>debuggerd</code> (or <code>debuggerd64)</code> in the event that signal
41is sent to the process.</p>
42
43<p>It's possible for <code>debuggerd</code> to attach only if nothing else is
44already attached. This means that using tools like <code>strace</code> or
45<code>gdb</code> will prevent <code>debuggerd</code> from working. Also, if
46you call <code>prctl(PR_SET_DUMPABLE, 0)</code> you can prevent
47<code>debuggerd</code> from attaching. This can be useful if you wish to
48explicitly opt out of crash reporting.</p>
49
50<p>Here is example output (with timestamps and extraneous information removed):</p>
51
52<pre class="no-pretty-print">
53*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
54Build fingerprint: 'Android/aosp_flounder/flounder:5.1.51/AOSP/enh08201009:eng/test-keys'
55Revision: '0'
56ABI: 'arm'
57pid: 1656, tid: 1656, name: crasher  &gt;&gt;&gt; crasher &lt;&lt;&lt;
58signal 6 (SIGABRT), code -6 (SI_TKILL), fault addr --------
59Abort message: 'some_file.c:123: some_function: assertion "false" failed'
60    r0 00000000  r1 00000678  r2 00000006  r3 f70b6dc8
61    r4 f70b6dd0  r5 f70b6d80  r6 00000002  r7 0000010c
62    r8 ffffffed  r9 00000000  sl 00000000  fp ff96ae1c
63    ip 00000006  sp ff96ad18  lr f700ced5  pc f700dc98  cpsr 400b0010
64backtrace:
65    #00 pc 00042c98  /system/lib/libc.so (tgkill+12)
66    #01 pc 00041ed1  /system/lib/libc.so (pthread_kill+32)
67    #02 pc 0001bb87  /system/lib/libc.so (raise+10)
68    #03 pc 00018cad  /system/lib/libc.so (__libc_android_abort+34)
69    #04 pc 000168e8  /system/lib/libc.so (abort+4)
70    #05 pc 0001a78f  /system/lib/libc.so (__libc_fatal+16)
71    #06 pc 00018d35  /system/lib/libc.so (__assert2+20)
72    #07 pc 00000f21  /system/xbin/crasher
73    #08 pc 00016795  /system/lib/libc.so (__libc_init+44)
74    #09 pc 00000abc  /system/xbin/crasher
75Tombstone written to: /data/tombstones/tombstone_06
76</pre>
77
78<p>This can be pasted into <code>development/scripts/stack</code> to get a more detailed unwind
79with line number information (assuming the unstripped binaries can be found).</p>
80
81<p>Some libraries on the system are built with <code>LOCAL_STRIP_MODULE :=
82keep_symbols</code> to provide usable backtraces directly from <code>debuggerd</code>. This makes
83your library or executable slightly larger, but not nearly as large as an
84unstripped version.</p>
85
86<p>Note also the last line of <code>debuggerd</code> output --- in addition to dumping a
87summary to the log, <code>debuggerd</code> writes a full “tombstone” to disk. This contains
88a lot of extra information that can be helpful in debugging a crash, in
89particular the stack traces for all the threads in the crashing process (not
90just the thread that caught the signal) and a full memory map.</p>
91
92<p>For more information about diagnosing native crashes and tombstones, see
93<a href="{@docRoot}devices/tech/debug/native-crash.html">Diagnosing Native Crashes</a></p>
94
95<h2 id=native>Native Debugging with GDB</h2>
96
97<h3 id=running>Debugging a running app</h3>
98
99<p>To connect to an already-running app or native daemon, use <code>gdbclient</code>.</p>
100
101<p>Current versions of gdbclient just require the process ID (PID). So to debug a process with
102PID 1234, simply run:</p>
103<pre class="no-pretty-print">
104$ gdbclient 1234
105</pre>
106<p>The script will set up port forwarding, start the appropriate
107<code>gdbserver</code> on the device, start the appropriate <code>gdb</code> on
108the host, configure <code>gdb</code> to find symbols, and connect
109<code>gdb</code> to the remote <code>gdbserver</code>.</p>
110
111<h3 id=starts>Debugging a native process as it starts</h3>
112
113<p>If you want to debug a process as it starts, you’ll need to use <code>gdbserver</code>
114or <code>gdbserver64</code> manually, but that’s easy too:</p>
115
116<pre class="no-pretty-print">
117$ adb shell gdbserver :5039 /system/bin/<em>my_test_app</em>
118Process my_test_app created; pid = 3460
119Listening on port 5039
120</pre>
121
122<p>Identify the app’s PID from the <code>gdbserver</code> output, and then in
123another window:</p>
124
125<pre class="no-pretty-print">
126$ gdbclient <em>&lt;app pid&gt;</em>
127</pre>
128
129<p>Then enter <strong>continue</strong> at the <code>gdb</code> prompt.</p>
130
131<p>Note that to debug a 64-bit process, you'll need to use <code>gdbserver64</code>.
132The error messages from <code>gdb</code> if you made the wrong choice are unhelpful
133(along the lines of <code>Reply contains invalid hex digit 59</code>).</p>
134
135<h3 id=crash>Debugging processes that crash</h3>
136
137<p>If you want <code>debuggerd</code> to suspend crashed processes so you can
138attach <code>gdb</code>, set the appropriate property:</p>
139
140<pre class="no-pretty-print">
141$ adb shell setprop debug.db.uid 999999                 # &lt;= M
142$ adb shell setprop debug.debuggerd.wait_for_gdb true   # &gt; M
143</pre>
144
145<p>At the end of the usual crash output, <code>debuggerd</code> will give you
146instructions on how to connect <code>gdb</code> using the typical command:
147<pre class="no-pretty-print">
148$ gdbclient &lt;pid&gt;
149</pre>
150
151<h3 id=symbols>Debugging without symbols</h3>
152
153<p>If you don’t have symbols, sometimes <code>gdb</code> will get confused about the
154instruction set it is disassembling (ARM or Thumb). The instruction set that is
155chosen as the default when symbol information is missing can be switched
156between ARM or Thumb like so:</p>
157
158<pre class="no-pretty-print">
159$ set arm fallback-mode arm   # or 'thumb'
160</pre>
161
162<h2 id=symbols>Other tools</h2>
163
164<h3 id=valgrind>Valgrind</h3>
165
166<p>The following steps show you how to use <a
167href="http://valgrind.org/">Valgrind</a> on Android. This tool suite contains a
168number of tools including Memcheck for detecting memory-related errors in C and
169C++.</p>
170
171<p>Android platform developers usually use
172<a href="{@docRoot}devices/tech/debug/asan.html">AddressSanitizer (ASan)</a> rather than valgrind.</p>
173
174<ol>
175  <li>To build Valgrind, run:
176<pre class="no-pretty-print">
177$ mmma -j6 external/valgrind
178</pre>
179  <li>Set up the temporary directory:
180<pre class="no-pretty-print">
181$ adb shell mkdir /data/local/tmp
182$ adb shell chmod 777 /data/local/tmp
183</pre>
184  <li>Run the system server with Valgrind:
185<pre class="no-pretty-print">
186$ adb shell setprop wrap.system_server "logwrapper valgrind"
187$ adb shell stop && adb shell start
188</pre>
189  <li>For debug symbols, push unstripped libraries to <code>/data/local/symbols</code>:
190<pre class="no-pretty-print">
191$ adb shell mkdir /data/local/symbols
192$ adb push $OUT/symbols /data/local/symbols
193</pre>
194  <li>To use Valgrind during boot up, edit <code>out/target/product/XXXX/root/init.rc</code> and
195change:<br>
196<code>service example /system/bin/foo --arg1 --arg2</code><br>
197to:<br>
198<code>service example /system/bin/logwrapper /system/bin/valgrind /system/bin/foo --arg1 --arg2</code><br>
199To see the effects, you need to create a <code>boot.img</code> and reflash the device.
200</ol>
201
202<h3 id=systrace>Systrace</h3>
203
204<p>See <a
205href="https://developer.android.com/tools/help/systrace.html">Systrace on
206developer.android.com</a> for deriving execution times of applications and
207other Android system processes.</p>
208