D.2. Packets

The following table provides a complete list of all currently defined commands and their corresponding response data.

! -- extended mode

Enable extended mode. In extended mode, the remote server is made persistent. The R packet is used to restart the program being debugged.

Reply:

OK

The remote target both supports and has enabled extended mode.

? -- last signal

Indicate the reason the target halted. The reply is the same as for step and continue.

Reply: (refer to Section D.3 Stop Reply Packets, for the reply specifications.

a -- reserved

Reserved for future use.

Aarglen,argnum,arg,… -- set program arguments (reserved)

Initialized argv[] array passed into program. arglen specifies the number of bytes in the hex encoded byte stream arg. See gdbserver for more details.

Reply:

OK, ENN

No other details.

bbaud -- set baud (deprecated)

Change the serial line speed to baud.

JTC: When does the transport layer state change? When it's received, or after the ACK is transmitted. In either case, there are problems if the command or the acknowledgment packet is dropped.

Stan: If people really wanted to add something like this, and get it working for the first time, they ought to modify ser-unix.c to send some kind of out-of-band message to a specially-setup stub and have the switch happen "in between" packets, so that from remote protocol's point of view, nothing actually happened.

Baddr,mode -- set breakpoint (deprecated)

Set (mode is S) or clear (mode is C) a breakpoint at addr.

This packet has been replaced by the Z and z packets.

caddr -- continue

addr is address to resume. If addr is omitted, resume at current address.

Reply: (refer to Section D.3 Stop Reply Packets, for the reply specifications.

Csig;addr -- continue with signal

Continue with signal sig (hex signal number). If ;addr is omitted, resume at same address.

Reply: (refer to Section D.3 Stop Reply Packets, for the reply specifications.

d -- toggle debug (deprecated)

Toggle debug flag.

D -- detach

Detach gdb from the remote system. Sent to the remote target before gdb disconnects via the detach command.

Reply:

no response

{No value for ` <listitem>GDBN'} does not check for any response after sending this packet.

e -- reserved

Reserved for future use.

E -- reserved

Reserved for future use.

f -- reserved

Reserved for future use.

FRC,EE,CF;XX -- Reply to target's F packet.

This packet is send by gdb as reply to a F request packet sent by the target. This is part of the File-I/O protocol extension. Refer to Section D.7 File-I/O remote protocol extension, for the specification.

g -- read registers

Read general registers.

Reply:

XX…

Each byte of register data is described by two hex digits. The bytes with the register are transmitted in target byte order. The size of each register and their position within the g packet are determined by the gdb internal macros REGISTER_RAW_SIZE and REGISTER_NAME macros. The specification of several standard g packets is specified below.

ENN

for an error.

GXX… -- write regs

Reply:

OK

for success

ENN

for an error

h -- reserved

Reserved for future use.

Hct… -- set thread

Set thread for subsequent operations (m, M, g, G, et.al.). c depends on the operation to be performed: it should be c for step and continue operations, g for other operations. The thread designator t… may be -1, meaning all the threads, a thread number, or zero which means pick any thread.

Reply:

OK

for success

ENN

for an error

iaddr,nnn -- cycle step (draft)

Step the remote target by a single clock cycle. If ,nnn is present, cycle step nnn cycles. If addr is present, cycle step starting at that address.

I -- signal then cycle step (reserved)

j -- reserved

Reserved for future use.

J -- reserved

Reserved for future use.

k -- kill request

FIXME: There is no description of how to operate when a specific thread context has been selected (that is, does 'k' kill only that thread?).

K -- reserved

Reserved for future use.

l -- reserved

Reserved for future use.

L -- reserved

Reserved for future use.

maddr,length -- read memory

Read length bytes of memory starting at address addr. Neither gdb nor the stub assume that sized memory transfers are assumed using word aligned accesses. FIXME: A word aligned memory transfer mechanism is needed.

Reply:

XX…

XX… is mem contents. Can be fewer bytes than requested if able to read only part of the data. Neither gdb nor the stub assume that sized memory transfers are assumed using word aligned accesses. FIXME: A word aligned memory transfer mechanism is needed.

ENN

NN is errno

Maddr,length:XX… -- write mem

Write length bytes of memory starting at address addr. XX… is the data.

Reply:

OK

for success

ENN

for an error (this includes the case where only part of the data was written).

n -- reserved

Reserved for future use.

N -- reserved

Reserved for future use.

o -- reserved

Reserved for future use.

O -- reserved

Reserved for future use.

pn… -- read reg (reserved)

Reply:

r….

The hex encoded value of the register in target byte order.

Pn…=r… -- write register

Write register n… with value r…, which contains two hex digits for each byte in the register (target byte order).

Reply:

OK

for success

ENN

for an error

qquery -- general query

Request info about query. In general gdb queries have a leading upper case letter. Custom vendor queries should use a company prefix (in lower case) ex: qfsf.var. query may optionally be followed by a , or ; separated list. Stubs must ensure that they match the full query name.

Reply:

XX…

Hex encoded data from query. The reply can not be empty.

ENN

error reply

Indicating an unrecognized query.

Qvar=val -- general set

Set value of var to val.

Refer to Section D.4 General Query Packets, for a discussion of naming conventions.

r -- reset (deprecated)

Reset the entire system.

RXX -- remote restart

Restart the program being debugged. XX, while needed, is ignored. This packet is only available in extended mode.

Reply:

no reply

The R packet has no reply.

saddr -- step

addr is address to resume. If addr is omitted, resume at same address.

Reply: (refer to Section D.3 Stop Reply Packets, for the reply specifications.

Ssig;addr -- step with signal

Like C but step not continue.

Reply: (refer to Section D.3 Stop Reply Packets, for the reply specifications.

taddr:PP,MM -- search

Search backwards starting at address addr for a match with pattern PP and mask MM. PP and MM are 4 bytes. addr must be at least 3 digits.

TXX -- thread alive

Find out if the thread XX is alive.

Reply:

OK

thread is still alive

ENN

thread is dead

u -- reserved

Reserved for future use.

U -- reserved

Reserved for future use.

v -- reserved

Reserved for future use.

V -- reserved

Reserved for future use.

w -- reserved

Reserved for future use.

W -- reserved

Reserved for future use.

x -- reserved

Reserved for future use.

Xaddr,length:XX… -- write mem (binary)

addr is address, length is number of bytes, XX… is binary data. The characters $, #, and 0x7d are escaped using 0x7d.

Reply:

OK

for success

ENN

for an error

y -- reserved

Reserved for future use.

Y reserved

Reserved for future use.

ztype,addr,length -- remove breakpoint or watchpoint (draft), Ztype,addr,length -- insert breakpoint or watchpoint (draft)

Insert (Z) or remove (z) a type breakpoint or watchpoint starting at address address and covering the next length bytes.

Each breakpoint and watchpoint packet type is documented separately.

Implementation notes: A remote target shall return an empty string for an unrecognized breakpoint or watchpoint packet type. A remote target shall support either both or neither of a given Ztype… and ztype… packet pair. To avoid potential problems with duplicate packets, the operations should be implemented in an idempotent way.

z0,addr,length -- remove memory breakpoint (draft), Z0,addr,length -- insert memory breakpoint (draft)

Insert (Z0) or remove (z0) a memory breakpoint at address addr of size length.

A memory breakpoint is implemented by replacing the instruction at addr with a software breakpoint or trap instruction. The length is used by targets that indicates the size of the breakpoint (in bytes) that should be inserted (e.g., the arm and mips can insert either a 2 or 4 byte breakpoint).

Implementation note: It is possible for a target to copy or move code that contains memory breakpoints (e.g., when implementing overlays). The behavior of this packet, in the presence of such a target, is not defined.

Reply:

OK

success

not supported

ENN

for an error

z1,addr,length -- remove hardware breakpoint (draft), Z1,addr,length -- insert hardware breakpoint (draft)

Insert (Z1) or remove (z1) a hardware breakpoint at address addr of size length.

A hardware breakpoint is implemented using a mechanism that is not dependant on being able to modify the target's memory.

Implementation note: A hardware breakpoint is not affected by code movement.

Reply:

OK

success

not supported

ENN

for an error

z2,addr,length -- remove write watchpoint (draft), Z2,addr,length -- insert write watchpoint (draft)

Insert (Z2) or remove (z2) a write watchpoint.

Reply:

OK

success

not supported

ENN

for an error

z3,addr,length -- remove read watchpoint (draft), Z3,addr,length -- insert read watchpoint (draft)

Insert (Z3) or remove (z3) a read watchpoint.

Reply:

OK

success

not supported

ENN

for an error

z4,addr,length -- remove access watchpoint (draft), Z4,addr,length -- insert access watchpoint (draft)

Insert (Z4) or remove (z4) an access watchpoint.

Reply:

OK

success

not supported

ENN

for an error