Format:GDB Remote Serial Protocol
| 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) untilQStartNoAckModeis 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 (Xpacket, qXfer): the escape is}followed by the byte XOR 0x20 (so 0x7d is sent as7d 5d). Replies must also escape*(0x2a). - Run-length encoding in replies: a character,
*, then a count byten+29(so a space means 3 more repeats:0*is0000). 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 areExx(hex number) orE.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
- Format:GDB Remote Serial Protocol/Registers and target description - register numbering and the target XML
- Format:GDB Remote Serial Protocol/LLDB extensions - qHostInfo, qRegisterInfo, qMemoryRegionInfo and friends
- Format:GDB Remote Serial Protocol/Emulator stubs - QEMU, Dolphin, mGBA
- Debugging a crashed process instead of a live one: Format:ELF (Executable and Linkable Format)/Core dumps, Format:Minidump, Format:Windows kernel crash dump.
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.