1 page.title=Debugging with GDB 2 pdk.version=1.0 3 doc.type=porting 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 <a name="toc"/> 10 <ul> 11 <li><a href="#gdb">Debugging</a></li> 12 <li><a href="#justInTime">Just-In-Time Debug Feature</a></li> 13 </ul> 14 </div> 15 </div> 16 17 <p>The current version of <code>envsetup.sh</code> has a <code>gdbclient</code> command that handles much of the setup. For example, to attach the 18 already-running <code>globaltime</code> application, execute the following, making sure that: 1) you do this from the same window used to build the software on the device you are debugging and 2) verify that the symbols in the object files in the build tree match up with what is installed on the device or emulator.</p> 19 <pre class="prettify"> 20 gdbclient app_process :5039 globaltime 21 </pre> 22 <a name="gdb"></a><h3>Debugging</h3> 23 <a name="gdbShort"></a> 24 <h4>Short Instructions</h4> 25 <p>Android runs <code>gdbserver</code> on the device and an ARM aware <code>gdb</code>, named <code>arm-eabi-gdb</code>, on the desktop machine.</p> 26 <ol> 27 <li>First you need to 28 run <code>gdbserver</code> on the device:<BR> 29 <pre class="prettify"> 30 gdbserver :5039 /system/bin/<i>executable</i> 31 </pre> 32 <BR> 33 The <code>:5039</code> tells gdbserver to listen on port 5039 on the localhost, which adb bridges from the host to the device. <code>executable</code> represents the command to debug, a common one being runtime -s which starts the entire system all running in a single process. <br> 34 <br> 35 </li> 36 <li>Launch <code>gdb</code> on the desktop. 37 This can be 38 done easily with the following command in the shell from which you built: 39 <pre class="prettify"> 40 gdbclient <i>executable</i> 41 </pre> 42 </li> 43 </ol> 44 <p>At this point <code>gdb</code> will connect with your device 45 and you should be 46 able to enter <code>c</code> to have the device start executing inside of the 47 desktop <code>gdb</code> session.</p> 48 <a name="gdbDetailed"></a> 49 <h4>Detailed Instructions</h4> 50 <p>If the short instructions don't work, these detailed instructions should: 51 <ol> 52 <li>On the device, launch a new command: 53 <pre class="prettify">gdbserver :5039 /system/bin/<i>executable</i></pre> 54 or attach to an existing process: 55 <pre class="prettify">gdbserver :5039 --attach <i>pid</i></pre> 56 </li> 57 <li>On your workstation, forward port 5039 to the device with adb: 58 <pre class="prettify">adb forward tcp:5039 tcp:5039</pre> 59 </li> 60 <li>Start a special version of <code>gdb</code> that lives in the "prebuilt" area of the source tree: <br> 61 <code>prebuilt/Linux/toolchain-eabi-4.2.1/bin/arm-eabi-gdb</code> (for Linux) <br> 62 <code>prebuilt/darwin-x86/toolchain-eabi-4.2.1/bin/arm-eabi-gdb</code> (for Darwin) </li> 63 <li>If you can't find either special version of <code>gdb</code>, run <code>find prebuilt -name arm-eabi-gdb</code> in your source tree to find and run the latest version: 64 <pre class="prettify"> 65 prebuilt/Linux/toolchain-eabi-4.2.1/bin/arm-eabi-gdb out/target/product/<i>product-name</i>/symbols/system/bin/<i>executable</i> 66 </pre> 67 <BR> 68 Where <i>product-name</i> is the name of the device product that you're building (for example, <code>sooner</code>), 69 and <i>executable</i> is the program to debug (usually <code>app_process</code> for an application).<br> 70 <br> 71 Make sure to use the copy of the executable in the symbols directory, not the 72 primary android directory, because the one in the primary directory has 73 been stripped of its debugging information.</li> 74 <li>In <code>gdb</code>, Tell <code>gdb</code> where to find the shared libraries that will get loaded: 75 <pre class="prettify"> 76 set solib-absolute-prefix /<i>absolute-source-path</i>/out/target/product/<i>product-name</i>/symbols 77 set solib-search-path /<i>absolute-source-path</i>/out/target/product/<i>product-name</i>/symbols/system/lib 78 </pre> 79 <BR> 80 <i>absolute-source-path</i> is the path to your source tree; for example, <code>/work/device</code> or <code>/Users/hoser/android/device</code>.<BR> 81 <i>product-name</i> is the same as above; for example, <code>sooner</code>. <BR> 82 <BR> 83 Make sure you specify the correct directories—<code>gdb</code> may not tell you if you make a mistake.</li> 84 <li>Connect to the device by issuing the <code>gdb</code> command:<BR> 85 <pre class="prettify"> 86 target remote :5039 87 </pre> 88 <BR> 89 <BR> 90 The <code>:5039</code> tells <code>gdb</code> to connect to the localhost port 5039, which is bridged to the device by <code>adb</code>.<BR> 91 <BR> 92 You may need to inspire gdb to load some symbols by typing: 93 <pre class="prettify">shared</pre> 94 </li> 95 </ol> 96 <p>You should be connected and able to debug as you normally would. You can ignore the error about not 97 finding the location for the thread creation breakpoint. It will be found when 98 the linker loads <code>libc</code> into your process before hitting <code>main()</code>. Also note that 99 the <code>gdb</code> remote protocol doesn't have a way for the device to 100 tell the host about 101 newly created threads so you will not always see notifications about newly 102 created threads. Info about other threads will be queried from the 103 device when a 104 breakpoint is hit or you ask for it by running info thread. <a name="justInTime"></a> 105 <h3>Just-In-Time Debug Feature</h3> 106 If you see the red LED flashing it means a process is in that new 107 state (crashed and waiting for GDB connection). If this happens to the 108 system process, most likely your device will be frozen at this point. <strong>Do not press the home key</strong>. Bring the device to someone who can 109 debug native crashes and ask for advice. 110 If you're in the field and just want your device to continue as it 111 would have without this feature (like cylonning), press home (a 112 tombstone will be recorded as usual). 113 114 To enable a process to be debugged this way, you need to set a property: 115 <pre class="prettify"> 116 adb shell setprop debug.db.uid 10000 117 </pre> 118 and all processes with a <code>uid <= 10000</code> will be trapped in this 119 manner. When one of them crashes, the tombstone is processed as usual, an explicit message is printed into the log, and the red LED starts 120 flashing waiting for the Home key to be depressed (in which case it 121 continues execution as usual). 122 <pre class="prettify"> 123 I/DEBUG ( 27): ******************************************************** 124 I/DEBUG ( 27): * process 82 crashed. debuggerd waiting for gdbserver 125 I/DEBUG ( 27): * 126 I/DEBUG ( 27): * adb shell gdbserver :port --attach 82 & 127 I/DEBUG ( 27): * 128 I/DEBUG ( 27): * and press the HOME key. 129 I/DEBUG ( 27): ******************************************************** 130 </pre> 131 <p>When you see the entry above, make sure <code>adb</code> is forwarding port 5039 (you only need to do this once, 132 unless the ADB server dies) and execute:</p> 133 <pre class="prettify">% adb forward tcp:5039 tcp:5039</pre> 134 Execute the line shown in the debug output, substituting 5039 for the proper <code>port</code>: 135 <pre class="prettify"> 136 % adb shell gdbserver :5039 --attach 82 & 137 </pre> 138 <p>If the crashing process is based off zygote (that is, system_server and all 139 applications), the default values for the <code>gdbclient</code> command, <code>app_process</code> binary and port <code>5039</code>, are correct, so you can execute:</p> 140 <pre class="prettify"> 141 % cd <top of device source tree> 142 % gdbclient 143 </pre> 144 <p>Otherwise you need to determine the path of the crashing binary and follow the 145 steps as mentioned above (for example, <code>gdbclient hoser :5039</code> if 146 the <code>hoser</code> command has failed).</p> 147
