Format:GDB Remote Serial Protocol/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 regnum attribute, and the feature names an i386/amd64, ARM, AArch64 or RISC-V stub must provide.
Numbering rule
The g/G packets carry all registers concatenated in increasing register-number order, and p/P address one register by number (hex). If the stub sends a target description (qXfer:features:read:target.xml), each <reg> element gets regnum if given, else the previous register's number plus one (the first register defaults to 0); numbers continue across <feature> elements. Without a description GDB falls back to its built-in per-architecture layout, which is why a stub that sends a bare g for a core GDB already knows may work without XML. (GDB manual, Target Description Format.)
A <reg> has name (unique), bitsize, optional regnum, save-restore (yes/no), type (int, float, code_ptr, data_ptr, uint32, a feature-defined flags/vector type, ...) and group.
Document shape
<?xml version="1.0"?>
<target version="1.0">
<architecture>armv4t</architecture>
<osabi>none</osabi>
<feature name="org.gnu.gdb.arm.core">
<reg name="r0" bitsize="32" type="uint32"/> ...
<reg name="cpsr" bitsize="32" regnum="25" type="cpsr_flags"/>
</feature>
</target>
The fragment above is from mGBA's stub (r0-r12, sp, lr, pc, then cpsr pinned at regnum 25): 25 is the slot the old ARM FPA registers f0-f7 and fps occupy in GDB's built-in ARM layout, so the XML skips them. Its g reply only holds 17 words (r0-r14, pc, cpsr) while p 19 (hex 0x19 = 25) reaches cpsr.
Required features (from the manual)
- x86:
org.gnu.gdb.i386.core(eax..edi+eip, or rax..r15+rip; eflags, cs ss ds es fs gs; st0-st7; fctrl fstat ftag fiseg fioff foseg fooff fop); optional.sse(xmm0-7/15, mxcsr),.avx(ymm0h..),.avx512(xmm16-31, ymm16h-31h, zmm*h, k0-k7),.linux(orig_eax / orig_rax),.segments(fs_base, gs_base),.pkeys(pkru),.pl3_ssp. - AArch64:
org.gnu.gdb.aarch64.core,.fpu,.sve(z0-z31 ...) and others; ARM:org.gnu.gdb.arm.core,.vfp,.m-profile; MIPS, PowerPC (org.gnu.gdb.power.core...), RISC-V (org.gnu.gdb.riscv.cpu,.fpu,.csr,.virtual), LoongArch (org.gnu.gdb.loongarch.baser0-r31, pc, badv). Each has its own section in the manual's Standard Target Features.
Worked layouts from emulators
- Dolphin (big-endian PowerPC 750) answers
pfor: 0-31 r0-r31 (32-bit), 32-63 f0-f31 (64-bit), 64 pc, 65 msr, 66 cr, 67 lr, 68 ctr, 69 xer, 70 fpscr, 71-86 segment registers sr0-sr15, 87 PVR, 88-103 IBAT/DBAT SPRs, 104 SDR1, 105 ASR, 106 DAR, 107 DSISR. This is the numbering of GDB's built-in PowerPC layout. Itsgreply only contains the 32 GPRs (32 x 8 hex digits). - mGBA (ARM7TDMI): see above.
- LLDB does not use the XML: it queries
qRegisterInfo<hex index>one register at a time; see Format:GDB Remote Serial Protocol/LLDB extensions. Registers there carry gcc/dwarf numbers (x86-64 rax is dwarf 0, rbx 3, rcx 2, rdx 1, rsi 4, rdi 5, rbp 6, rsp 7, r8-r15 8-15, rip 16, xmm0 17).
See Format:GDB Remote Serial Protocol for framing and packets.
Evidence & references
gdb/doc/gdb.texinfo (Target Description Format, i386/AArch64/ARM/RISC-V/LoongArch Features) in bminor/binutils-gdb; mgba-emu/mgba src/debugger/gdb-stub.c; dolphin-emu/dolphin Source/Core/Core/PowerPC/GDBStub.cpp; lldbgdbremote.md in llvm/llvm-project. Unverified: exact full register order of GDB's built-in x86-64 layout (rax rbx rcx rdx rsi rdi rbp rsp r8-r15 rip eflags cs ss ds es fs gs, then st0-7...) is quoted from memory of the target XML files, not read.