This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

GDB stub


The gdbstub feature provides an implementation of the GDB Remote Serial Protocol (RSP) that allows you to remotely debug Zephyr using GDB.

The protocol supports different connection types: serial, UDP/IP and TCP/IP. Zephyr currently supports only serial device communication.

The GDB program acts as the client while Zephyr acts as the server. When this feature is enabled, Zephyr stops its execution after gdb_init() starts gdbstub service and waits for a GDB connection. Once a connection is established it is possible to synchronously interact with Zephyr. Note that currently it is not possible to asynchronously send commands to the target.


The following features are supported:

  • Add and remove breakpoints

  • Continue and step the target

  • Print backtrace

  • Read or write general registers

  • Read or write the memory

Enabling GDB Stub

GDB stub can be enabled with the CONFIG_GDBSTUB option.

Using Serial Backend

The serial backend for GDB stub can be enabled with the CONFIG_GDBSTUB_SERIAL_BACKEND option.

Since serial backend utilizes UART devices to send and receive GDB commands,

  • If there are spare UART devices on the board, set CONFIG_GDBSTUB_SERIAL_BACKEND_NAME to the spare UART device so that printk() and log messages are not being printed to the same UART device used for GDB.

  • For boards with only one UART device, printk() and logging must be disabled if they are also using the same UART device for output. GDB related messages may interleave with log messages which may have unintended consequences. Usually this can be done by disabling CONFIG_PRINTK and CONFIG_LOG.


Using Serial Backend

  1. Build with GDB stub and serial backend enabled.

  2. Flash built image onto board and reset the board.

    • Execution should now be paused at gdb_init().

  3. Execute GDB on development machine and connect to the GDB stub.

    target remote <serial device>

    For example,

    target remote /dev/ttyUSB1
  4. GDB commands can be used to start debugging.