Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:GDB Remote Serial Protocol

From ReverseEngineering.wiki
Format
On this wiki Facts · Code · Notes · Topics

The text protocol GDB and LLDB speak to debug stubs (gdbserver, QEMU, emulators, JTAG probes, kernels): packets framed as $data#checksum, hex-encoded registers and memory, stop replies, and optional features negotiated with qSupported and described by XML documents.

Framing

  • A packet is $ packet-data # two hex digits of checksum. The checksum is the sum modulo 256 of the bytes between $ and # (GDB manual, Overview). Example from the LLDB documentation: $QStartNoAckMode#b0.
  • The receiver answers each packet with + (good) or - (retransmit) until QStartNoAckMode is negotiated; after that no acknowledgments are sent. A single byte 0x03 outside a packet is the interrupt request (Ctrl-C); mGBA's stub switches on it next to +, - and $ (see Format:GDB Remote Serial Protocol/Emulator stubs).
  • Inside packet-data #, $ and } (0x7d) are never sent raw in binary payloads (X packet, qXfer): the escape is } followed by the byte XOR 0x20 (so 0x7d is sent as 7d 5d). Replies must also escape * (0x2a).
  • Run-length encoding in replies: a character, *, then a count byte n+29 (so a space means 3 more repeats: 0* is 0000). The count byte must not be # or $ or above 126, so " (n=5) is used for runs of six and seven.
  • Fields are separated by , ; or :; numbers are hex without leading zeros unless stated otherwise. An unsupported command gets the empty reply $#00. Errors are Exx (hex number) or E.text. Multi-byte register and memory values are hex of the bytes in target byte order, two digits per byte.

Minimum and common packets

The GDB manual says a stub must at least support ? (why halted), g/G (all registers), m/M (memory); everything else is optional.

Packet Meaning
? Reply with the last stop reason (stop reply)
g / G XX.. Read / write all registers, concatenated in register-number order
p n / P n=XX.. Read / write register number n (hex)
m addr,len / M addr,len:XX.. Read / write memory as hex
X addr,len:bin Write memory, binary payload with } escaping
c [addr], s [addr] Continue, single-step; C sig / S sig with a signal
vCont? / vCont;c;s;C sig;S sig;...[:thread] Resumption actions per thread; vCont? lists the supported actions (QEMU answers vCont;c;C;s;S)
Z0/z0 addr,kind Software breakpoint insert/remove
Z1/z1 Hardware breakpoint
Z2/Z3/Z4 Write / read / access watchpoint
H op thread Select thread for subsequent operations (g for registers, c for execution; -1 all, 0 any)
qC, qfThreadInfo / qsThreadInfo Current thread; list threads (m1, then l for end)
qAttached, k, D, vAttach;pid Attached or spawned; kill; detach; attach
qSupported:feat+;... Feature negotiation (below)
qXfer:object:read:annex:offset,length Read a document in chunks (below)
QStartNoAckMode Disable +/- acks

The software-breakpoint kind is target specific: usually the breakpoint instruction size in bytes (the manual gives ARM and MIPS as 2 or 4), 0 otherwise.

Stop replies

Sxx = stopped with signal xx (hex, GDB numbering; 05 = SIGTRAP). Txx n:r;n:r;... adds pairs: a hex register number with its value in target byte order, thread:id, core:n, or a stop reason: watch/rwatch/awatch (data address), swbreak, hwbreak, syscall_entry/syscall_return, library. Wxx = process exited with status, Xxx = terminated by signal, OXX.. = console output. In the manual's sense, a stub that does not send T with swbreak/hwbreak gets plain traps; emulators often send S05 (mGBA does for write watchpoints on purpose).

qSupported and qXfer

qSupported carries GDB's features (multiprocess+, swbreak+, hwbreak+, qRelocInsn+, fork-events+, vContSupported+, xmlRegisters=i386...) and the stub replies with its own, for example QEMU: PacketSize=<hex>;qXfer:features:read+;qXfer:auxv:read+;qXfer:siginfo:read+;qXfer:exec-file:read+;QCatchSyscalls+;vContSupported+;multiprocess+ (user mode adds the auxv/siginfo/exec-file ones, reverse debugging adds ReverseStep+;ReverseContinue+). PacketSize is the largest packet the stub accepts, in hex.

qXfer:<object>:read:<annex>:<offset>,<length> returns m + data (more follows) or l + data (last chunk). Objects seen in the sources: features (annex target.xml, the target description, see Format:GDB Remote Serial Protocol/Registers and target description), memory-map (annex empty, XML <memory-map><memory type="ram|rom|flash" start length/>), auxv (the raw auxiliary vector of a Linux process), siginfo, exec-file, libraries/libraries-svr4 (loaded modules). An empty annex is written ::, as in mGBA's qXfer:memory-map:read::.

Multi-process and threads

With multiprocess+, thread ids become pPID.TID (hex, -1 all); qC replies QC<id>. Single-threaded stubs and emulators answer qfThreadInfo with m1 and qsThreadInfo with l and accept Hg0/Hc0/Hg1/Hc1/Hg-1, as Dolphin does.

Related

Topics

  • Registers and target description — How register numbers work in the GDB remote protocol: the order of the g packet, the target description XML (qXfer:features:read:target.xml) with its optional…
  • LLDB extensions — The packets LLDB adds to or uses beside the GDB remote protocol (QStartNoAckMode, qHostInfo, qProcessInfo, qRegisterInfo, qMemoryRegionInfo, jThreadsInfo…
  • Emulator stubs — How QEMU, Dolphin and mGBA expose a GDB stub: how to enable each, what they answer to qSupported, which packets and registers they implement, and quirks a…

Code & repositories

  • https://github.com/llvm/llvm-project @ bd280427b25ff4262dd9ad56d0ed0ef6a2b7ecb0 · license: Apache-2.0 WITH LLVM-exception (declared by the contributor for the files used; GitHub reports MIT (read from LICENSE.TXT; GitHub's detector did not classify it) for the repository)
    lldb/docs/resources/lldbgdbremote.md documents LLDB's GDB remote extensions
    Tested on: source read, not run: read only, main branch · checked 2026-10-18; last activity 2026-10-18; Note: the latest release ships binaries; the wiki links only the source, never the binaries
  • https://github.com/mgba-emu/mgba @ 9660a668f2093cb4aba5983f52bebf8878dc5b8b · license: MPL-2.0
    src/debugger/gdb-stub.c: mGBA's GDB stub for the GBA ARM7TDMI
    Tested on: source read, not run: read only, master · checked 2026-10-18; last activity 2026-10-17; Note: the latest release ships binaries; the wiki links only the source, never the binaries
  • https://github.com/qemu/qemu @ a19f59a72d96056d9a8f48cf6c77f5787491e414 · license: GPL-2.0-only (declared by the contributor; GitHub's detector did not recognize COPYING)
    gdbstub/gdbstub.c: QEMU's GDB stub (qSupported, vCont, qemu.* extensions)
    Tested on: source read, not run: read only, master · checked 2026-10-18; last activity 2026-10-17
  • https://github.com/dolphin-emu/dolphin @ 41460454e9600f909950fddf0abd13a138430162 · license: GPL-2.0-or-later (declared by the contributor; GitHub's detector did not recognize COPYING)
    Source/Core/Core/PowerPC/GDBStub.cpp: Dolphin's GDB stub
    Tested on: source read, not run: read only, master · checked 2026-10-18; last activity 2026-10-18

Evidence & references

GDB manual, appendix Remote Serial Protocol (gdb/doc/gdb.texinfo of bminor/binutils-gdb, GFDL; sections Overview, Packets, Stop Reply Packets, General Query Packets, Standard Replies); qemu/qemu gdbstub/gdbstub.c; llvm/llvm-project lldb/docs/resources/lldbgdbremote.md. Unverified: the Z2/Z3/Z4 type numbers and the }-escape of X were not re-read line by line while writing this page; check the manual's Z packet entries before relying on them.