GDB for Android

draft r0


The upstream version of GDB has no support for debugging native or NDK activities on Android. Multiple out-of-tree patches exist that add different features and have different levels of support. None are being pushed upstream.

This card covers adding Android support to GDB for use cross debugging. Once finished, all of the typical GDB features such as breakpoints, stepping, backtracing, thread debugging, and shared library support will be usable when debugging NDK extensions, NDK activities, and native applications.

Support will be added upstream as a new target or a variant of the GLIBC target.

Native debugging is excluded due to being an uncommon use case. Native debugging may come as a side effect of this work but will not be tested.

The goal is to help end developers use the latest features and fixes in upstream GDB when cross debugging. A stretch goal is to make sure that upstream GDB and gdbserver are a drop-in replacement to NDK's versions when used via Android development tools such as ADB, ndk-gdb and the ADT plugin for Eclipse.


The main difference is in the choice of C library. Android uses Bionic where generic Linux typically uses GLIBC. This brings many implementation differences including how threads and shared libraries are implemented.

Android ships a GDB version with custom patches which adapt it to small differences in Android's ABI (e.g., jmp_buf layout and signal frames), bugs in other parts of the Android system (e.g., the compiler and the kernel) and allow multithread debugging with its statically linked libthread_db.

The GDB version included in the NDK lags behind the latest GDB release and sometimes skips releases. Features or bugfixes which have been recently added to upstream GDB are unavailable.


Contact Google to see whether they are open to upstreaming of their patches, and whether they are willing to accept the patches mentioned in the dependencies section below.

Modify Bionic to provide a dynamically loaded libthread_db. TODO: I still need to investigate what this involves.

Provide support both for a legacy, statically linked, version locked libthread_db and the new dynamically linked version.

Modify the linker to add an ELF section identifying a program as using the Android ABI. This allows selecting the right target support inside GDB.

For each patch shipped in AOSP (Android Open Source Project), contact the author to ensure understanding of the problem/feature it addresses and preferably write a testcase.

Adapt (or rewrite) the patches so that they are suitable for upstream submission.

Follow the submission/review/rework cycle until all patches are committed upstream.

Some of the changes, such as changing libthread_db to a shared library, require platform changes. These will initially be done in the Linaro Android LEB and then posted upstream.


Google needs to accept signing the copyright of their patches to FSF so that they can be accepted upstream.

Google needs to accept patches to make libthread_db a dinamically loaded library (like in other platforms) instead of a statically linked library. Without this, it's not possible to have a single GDB version which can debug multiple threads in different versions of Android.

Google needs to accept patches to make it possible ot discover at runtime whether GDB is debugging a program running on Android. NDK's GDB is hardcoded to assume that it is always debugging Android programs. This is not acceptable for upstream submission. A comment in one of their own patches acknowledges this problem and suggests adding an ELF note to the executable.

TODO: I still need to investigate if there is a testsuite or test plan available for this, or if we will have to manually try some use cases (for instance, following tutorials and examples from the documentation).

Acceptance criteria

  • All patches upstream
  • Can build upstream GDB for the Android target
  • GDB runs on the host
  • gdbserver runs on the target
  • Can debug native Android programs
  • Can debug NDK activities
  • Matches or exceeds the feature set of the GDB shipped with the NDK
  • Testsuite has no extra regressions over the NDK GDB

TODO: check whether DejaGnu works with Android.

ThiagoBauermann/Sandbox/GDBforAndroid (last modified 2012-03-09 01:21:24)