Format:GDB Remote Serial Protocol/Emulator stubs
Appearance
Topic page of Format:GDB Remote Serial Protocol.
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 client must expect.
QEMU (system and user mode)
- Source: gdbstub/gdbstub.c (GPL-2.0-or-later) in qemu/qemu.
-s/-gdb tcp::1234opens the stub,-Sfreezes the CPU at start (command-line behaviour from QEMU's documentation, not re-read here). Unverified: the default port 1234 with-s. qSupportedreply, assembled in handle_query_supported:PacketSize=<MAX_PACKET_LENGTH hex>, then;qXfer:features:read+when the CPU has a core XML,;ReverseStep+;ReverseContinue+with record/replay, in user mode;qXfer:auxv:read+,;QCatchSyscalls+,;qXfer:siginfo:read+,;qXfer:exec-file:read+, and always;vContSupported+;multiprocess+.vCont?is answeredvCont;c;C;s;S.- The target description is generated at runtime from each CPU's register list (annex
target.xml, built by joining per-CPU XML fragments); register numbers follow the registers the CPU class registers, so they differ per architecture and per QEMU version. - QEMU extensions:
qqemu.sstepbits,qqemu.sstep/Qqemu.sstep=<mask>(control which interrupts/timers are masked while single-stepping), andqqemu.PhyMemMode/Qqemu.PhyMemMode:0|1(switchm/Mbetween virtual and physical addressing in system mode),qemu.Supporteddiscovery.
Dolphin (GameCube/Wii, big-endian PowerPC 750 "Gekko/Broadway")
- Source: Source/Core/Core/PowerPC/GDBStub.cpp (GPL-2.0-or-later) in dolphin-emu/dolphin. Two entry points:
Init(port)binds a TCP socket on INADDR_ANY and blocks in accept() until a client connects, andInitLocal(socket)(non-Windows) listens on a Unix-domain socket path after unlinking it. The Dolphin build must have been started with the GDB stub option (command-line/config, not read here). qSupportedis answered with the fixed stringswbreak+;hwbreak+;qC->QC1;qfThreadInfo->m1;qsThreadInfo->l;qAttached->1;qHostInfo-> cputype/cpusubtype of PowerPC 750,endian:big;ptrsize:4; everything unknown gets the empty reply. There is no XML target description: GDB's built-in PowerPC layout is used.- Handled packets:
? q H T k g G p P m M s c C z Z.greturns r0-r31 only. See the register map in Format:GDB Remote Serial Protocol/Registers and target description. - Only thread 1 exists (
Hg0/Hg1/Hg-1,T1).
mGBA (Game Boy Advance, ARM7TDMI)
- Source: src/debugger/gdb-stub.c (MPL-2.0) in mgba-emu/mgba.
GDBStubListen(stub, port, bindAddress, watchpointsBehavior)opens a TCP listener (one client). Packet loop handles+ - $and 0x03 (break), then commands? c g G H T m M p P q Q s v X Z z. - It serves the XML
target.xml(architecturearmv4t, osabi none, featureorg.gnu.gdb.arm.core) and a generatedmemory-mapXML from the core's mapped blocks (ramwhen writable, elserom). Replies toqSupportedfeature words it parses:swbreak,hwbreak;QStartNoAckModeis honoured;qfThreadInfo->m1. Reads over 512 bytes (m) are refused with error 06 (GDB_BAD_ARGUMENTS); unsupported command error is 07. - Stops: manual break
S02, breakpointT05swbreak:;/T05hwbreak:;when the client announced both, otherwise anS05...form; watchpointsT05watch/rwatch/awatch:<addr>;or plainS05(it deliberately sends S05 for write watchpoints in the non-standard behaviour modes so that GDB does not suppress unchanged writes). p/Pregister 0x19 (25) is cpsr, matching the XML's regnum.
PCSX2 and others
Unverified: PCSX2 had no GDB stub in the sources checked; the repository was not read for this page. Other emulators with GDB stubs worth checking: Ares/higan, Yuzu forks, RPCS3 (its own debugger), Citra/Lime3DS, melonDS, PPSSPP (has a GDB-like stub), Bochs (gdbstub option).
See Format:GDB Remote Serial Protocol for framing and packets.
Evidence & references
qemu/qemu gdbstub/gdbstub.c; dolphin-emu/dolphin Source/Core/Core/PowerPC/GDBStub.cpp; mgba-emu/mgba src/debugger/gdb-stub.c (all read from the default branch in October 2026).