1 files changed, 141 insertions, 0 deletions
diff --git a/en/devices/tech/debug/gdb.html b/en/devices/tech/debug/gdb.html
new file mode 100644
index 00000000..27c99328
--- /dev/null
+++ b/en/devices/tech/debug/gdb.html
@@ -0,0 +1,141 @@
+<html devsite>
+  <head>
+    <title>Using GDB</title>
+    <meta name="project_path" value="/_project.yaml" />
+    <meta name="book_path" value="/_book.yaml" />
+  </head>
+  <body>
+  <!--
+      Copyright 2017 The Android Open Source Project
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
+  -->
+
+
+<p>The GNU Project debugger (GDB) is a commonly used Unix debugger. This page
+details using <code>gdb</code> to debug Android apps and processes.</p>
+
+<h2 id=running>Debugging running apps or processes</h2>
+
+<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>
+
+<pre class="devsite-terminal devsite-click-to-copy">
+gdbclient 1234
+</pre>
+
+<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>
+
+<h2 id=starts>Debugging native process startup</h2>
+
+<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="devsite-terminal devsite-click-to-copy">
+adb shell gdbserver :5039 /system/bin/<var>MY_TEST_APP</var>
+</pre>
+
+<p>Example output:</p>
+<pre class="devsite-click-to-copy">
+Process <var>MY_TEST_APP</var> created; pid = 3460
+Listening on port 5039
+</pre>
+
+<p>Next, identify the application PID from the <code>gdbserver</code> output and
+use it in another terminal window:</p>
+
+<pre class="devsite-terminal devsite-click-to-copy">
+gdbclient <var>APP_PID</var>
+</pre>
+
+<p>Finally, enter <strong>continue</strong> at the <code>gdb</code> prompt.</p>
+
+<p class="note"><strong>Note:</strong> If you specify the wrong
+<code>gdbserver</code>, you'll get an unhelpful error message (such as
+"<code>Reply contains invalid hex digit 59</code>").</p>
+
+<h2 id="app-startup">Debugging app startup</h2>
+
+<p>Sometimes you want to debug an app as it starts, such as when there's a crash
+and you want to step through code to see what happens <em>before</em> the crash.
+<a href="#running">Attaching</a> works in some cases, but in other cases is
+impossible because the app crashes before you can attach. The
+<code>logwrapper</code> approach (used for <code>strace</code> and
+<code>valgrind</code>) does not always work because the app might not have
+permissions to open a port, and <code>gdbserver</code> inherits that
+restriction.</p>
+
+<p>To debug app startup, use the developer options in Settings to instruct
+the app to wait for a Java debugger to attach:</p>
+
+<ol>
+<li>Go to <em>Settings > Developer options > Select debug app</em> and choose
+your app from the list, then press <strong>Wait for debugger</strong>.</li>
+
+<li>Start the app, either from the launcher or by using the command line to run:
+<pre class="devsite-terminal devsite-click-to-copy">
+am start -a android.intent.action.MAIN -n <var>APP_NAME</var>/.<var>APP_ACTIVITY</var>
+</pre></li>
+
+<li>Wait for the app to load and a dialog to appear telling you the app is
+waiting for a debugger.</li>
+
+<li>Attach <code>gdbserver</code>/<code>gdbclient</code> normally, set
+breakpoints, then continue the process.</li></ol>
+
+<p>To let the app actually run, attach a Java Debug Wire Protocol (JDWP)
+debugger such as Java Debugger (jdb):</p>
+<pre class="devsite-click-to-copy">
+<code class="devsite-terminal">adb forward tcp:12345 jdwp:<var>XXX</var>  # (Where XXX is the pid of the debugged process.)</code>
+<code class="devsite-terminal">jdb -attach localhost:12345</code>
+</pre>
+
+<h2 id=crash>Debugging apps or processes that crash</h2>
+
+<p>If you want <code>debuggerd</code> to suspend crashed processes so you can
+attach <code>gdb</code>, set the appropriate property:</p>
+
+<pre class="devsite-click-to-copy">
+# Android 7.0 Nougat and later.
+<code class="devsite-terminal">adb shell setprop debug.debuggerd.wait_for_gdb true</code>
+</pre>
+
+<pre class="devsite-click-to-copy">
+# Android 6.0 Marshmallow and earlier.
+<code class="devsite-terminal">adb shell setprop debug.db.uid 999999</code>
+</pre>
+
+<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="devsite-terminal devsite-click-to-copy">
+gdbclient <var>PID</var>
+</pre>
+
+
+<h2 id=symbols>Debugging without symbols</h2>
+
+<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="devsite-terminal devsite-click-to-copy">
+set arm fallback-mode arm  # or thumb
+</pre>
+
+  </body>
+</html>