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/Emulator stubs

From ReverseEngineering.wiki

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::1234 opens the stub, -S freezes the CPU at start (command-line behaviour from QEMU's documentation, not re-read here). Unverified: the default port 1234 with -s.
  • qSupported reply, 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 answered vCont;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), and qqemu.PhyMemMode / Qqemu.PhyMemMode:0|1 (switch m/M between virtual and physical addressing in system mode), qemu.Supported discovery.

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, and InitLocal(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).
  • qSupported is answered with the fixed string swbreak+;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. g returns 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 (architecture armv4t, osabi none, feature org.gnu.gdb.arm.core) and a generated memory-map XML from the core's mapped blocks (ram when writable, else rom). Replies to qSupported feature words it parses: swbreak, hwbreak; QStartNoAckMode is 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, breakpoint T05swbreak:;/T05hwbreak:; when the client announced both, otherwise an S05... form; watchpoints T05watch/rwatch/awatch:<addr>; or plain S05 (it deliberately sends S05 for write watchpoints in the non-standard behaviour modes so that GDB does not suppress unchanged writes).
  • p/P register 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).