gdb: Packets
E.2 Packets
===========
The following table provides a complete list of all currently defined
COMMANDs and their corresponding response DATA. 
File-I/O Remote
Protocol Extension, for details about the File I/O extension of the
remote protocol.
Each packet's description has a template showing the packet's overall
syntax, followed by an explanation of the packet's meaning. We include
spaces in some of the templates for clarity; these are not part of the
packet's syntax. No GDB packet uses spaces to separate its components.
For example, a template like 'foo BAR BAZ' describes a packet beginning
with the three ASCII bytes 'foo', followed by a BAR, followed directly
by a BAZ. GDB does not transmit a space character between the 'foo' and
the BAR, or between the BAR and the BAZ.
Several packets and replies include a THREAD-ID field to identify a
thread. Normally these are positive numbers with a target-specific
interpretation, formatted as big-endian hex strings. A THREAD-ID can
also be a literal '-1' to indicate all threads, or '0' to pick any
thread.
In addition, the remote protocol supports a multiprocess feature in
which the THREAD-ID syntax is extended to optionally include both
process and thread ID fields, as 'pPID.TID'. The PID (process) and TID
(thread) components each have the format described above: a positive
number with target-specific interpretation formatted as a big-endian hex
string, literal '-1' to indicate all processes or threads
(respectively), or '0' to indicate an arbitrary process or thread.
Specifying just a process, as 'pPID', is equivalent to 'pPID.-1'. It is
an error to specify all processes but a specific thread, such as
'p-1.TID'. Note that the 'p' prefix is _not_ used for those packets and
replies explicitly documented to include a process ID, rather than a
THREAD-ID.
The multiprocess THREAD-ID syntax extensions are only used if both
GDB and the stub report support for the 'multiprocess' feature using
'qSupported'. multiprocess extensions, for more information.
Note that all packet forms beginning with an upper- or lower-case
letter, other than those described here, are reserved for future use.
Here are the packet descriptions.
'!'
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.
'?'
Indicate the reason the target halted. The reply is the same as
for step and continue. This packet has a special interpretation
when the target is in non-stop mode; see Remote Non-Stop.
Reply: Stop Reply Packets, for the reply specifications.
'A ARGLEN,ARGNUM,ARG,...'
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'
The arguments were set.
'E NN'
An error occurred.
'b BAUD'
(Don't use this packet; its behavior is not well-defined.) 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._
'B ADDR,MODE'
Set (MODE is 'S') or clear (MODE is 'C') a breakpoint at ADDR.
Don't use this packet. Use the 'Z' and 'z' packets instead (
insert breakpoint or watchpoint packet).
'bc'
Backward continue. Execute the target system in reverse. No
parameter. Reverse Execution, for more information.
Reply: Stop Reply Packets, for the reply specifications.
'bs'
Backward single step. Execute one instruction in reverse. No
parameter. Reverse Execution, for more information.
Reply: Stop Reply Packets, for the reply specifications.
'c [ADDR]'
Continue at ADDR, which is the address to resume. If ADDR is
omitted, resume at current address.
This packet is deprecated for multi-threading support. vCont
packet.
Reply: Stop Reply Packets, for the reply specifications.
'C SIG[;ADDR]'
Continue with signal SIG (hex signal number). If ';ADDR' is
omitted, resume at same address.
This packet is deprecated for multi-threading support. vCont
packet.
Reply: Stop Reply Packets, for the reply specifications.
'd'
Toggle debug flag.
Don't use this packet; instead, define a general set packet (
General Query Packets).
'D'
'D;PID'
The first form of the packet is used to detach GDB from the remote
system. It is sent to the remote target before GDB disconnects via
the 'detach' command.
The second form, including a process ID, is used when multiprocess
protocol extensions are enabled (multiprocess extensions),
to detach only a specific process. The PID is specified as a
big-endian hex string.
Reply:
'OK'
for success
'E NN'
for an error
'F RC,EE,CF;XX'
A reply from GDB to an 'F' packet sent by the target. This is part
of the File-I/O protocol extension. File-I/O Remote Protocol
Extension, for the specification.
'g'
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 gdbarch
functions 'DEPRECATED_REGISTER_RAW_SIZE' and
'gdbarch_register_name'.
When reading registers from a trace frame (Using the
Collected Data Analyze Collected Data.), the stub may also
return a string of literal 'x''s in place of the register data
digits, to indicate that the corresponding register has not
been collected, thus its value is unavailable. For example,
for an architecture with 4 registers of 4 bytes each, the
following reply indicates to GDB that registers 0 and 2 have
not been collected, while registers 1 and 3 have been
collected, and both have zero value:
-> g
<- xxxxxxxx00000000xxxxxxxx00000000
'E NN'
for an error.
'G XX...'
Write general registers. read registers packet, for a
description of the XX... data.
Reply:
'OK'
for success
'E NN'
for an error
'H OP THREAD-ID'
Set thread for subsequent operations ('m', 'M', 'g', 'G', et.al.).
Depending on the operation to be performed, OP should be 'c' for
step and continue operations (note that this is deprecated,
supporting the 'vCont' command is a better option), and 'g' for
other operations. The thread designator THREAD-ID has the format
and interpretation described in thread-id syntax.
Reply:
'OK'
for success
'E NN'
for an error
'i [ADDR[,NNN]]'
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'
DONTPRINTYET Signal, then cycle step. step with signal packet. *NoteDONTPRINTYET Signal, then cycle step. step with signal packet.
cycle step packet.
'k'
Kill request.
The exact effect of this packet is not specified.
For a bare-metal target, it may power cycle or reset the target
system. For that reason, the 'k' packet has no reply.
For a single-process target, it may kill that process if possible.
A multiple-process target may choose to kill just one process, or
all that are under GDB's control. For more precise control, use
the vKill packet (vKill packet).
If the target system immediately closes the connection in response
to 'k', GDB does not consider the lack of packet acknowledgment to
be an error, and assumes the kill was successful.
If connected using 'target extended-remote', and the target does
not close the connection in response to a kill request, GDB probes
the target state as if a new connection was opened (?
packet).
'm ADDR,LENGTH'
Read LENGTH addressable memory units starting at address ADDR
(addressable memory unit). Note that ADDR may not be
aligned to any particular boundary.
The stub need not use any particular size or alignment when
gathering data from memory for the response; even if ADDR is
word-aligned and LENGTH is a multiple of the word size, the stub is
free to use byte accesses, or not. For this reason, this packet
may not be suitable for accessing memory-mapped I/O devices.
Reply:
'XX...'
Memory contents; each byte is transmitted as a two-digit
hexadecimal number. The reply may contain fewer addressable
memory units than requested if the server was able to read
only part of the region of memory.
'E NN'
NN is errno
'M ADDR,LENGTH:XX...'
Write LENGTH addressable memory units starting at address ADDR
(addressable memory unit). The data is given by XX...;
each byte is transmitted as a two-digit hexadecimal number.
Reply:
'OK'
for success
'E NN'
for an error (this includes the case where only part of the
data was written).
'p N'
Read the value of register N; N is in hex. read registers
packet, for a description of how the returned register value is
encoded.
Reply:
'XX...'
the register's value
'E NN'
for an error
''
Indicating an unrecognized QUERY.
'P N...=R...'
Write register N... with value R.... The register number N is in
hexadecimal, and R... contains two hex digits for each byte in the
register (target byte order).
Reply:
'OK'
for success
'E NN'
for an error
'q NAME PARAMS...'
'Q NAME PARAMS...'
General query ('q') and set ('Q'). These packets are described
fully in General Query Packets.
'r'
Reset the entire system.
Don't use this packet; use the 'R' packet instead.
'R XX'
Restart the program being debugged. The XX, while needed, is
ignored. This packet is only available in extended mode (
extended mode).
The 'R' packet has no reply.
's [ADDR]'
Single step, resuming at ADDR. If ADDR is omitted, resume at same
address.
This packet is deprecated for multi-threading support. vCont
packet.
Reply: Stop Reply Packets, for the reply specifications.
'S SIG[;ADDR]'
Step with signal. This is analogous to the 'C' packet, but
requests a single-step, rather than a normal resumption of
execution.
This packet is deprecated for multi-threading support. vCont
packet.
Reply: Stop Reply Packets, for the reply specifications.
't ADDR:PP,MM'
Search backwards starting at address ADDR for a match with pattern
PP and mask MM, both of which are are 4 byte long. There must be
at least 3 digits in ADDR.
'T THREAD-ID'
Find out if the thread THREAD-ID is alive. thread-id
syntax.
Reply:
'OK'
thread is still alive
'E NN'
thread is dead
'v'
Packets starting with 'v' are identified by a multi-letter name, up
to the first ';' or '?' (or the end of the packet).
'vAttach;PID'
Attach to a new process with the specified process ID PID. The
process ID is a hexadecimal integer identifying the process. In
all-stop mode, all threads in the attached process are stopped; in
non-stop mode, it may be attached without being stopped if that is
supported by the target.
This packet is only available in extended mode (extended
mode).
Reply:
'E NN'
for an error
'Any stop packet'
for success in all-stop mode (Stop Reply Packets)
'OK'
for success in non-stop mode (Remote Non-Stop)
'vCont[;ACTION[:THREAD-ID]]...'
Resume the inferior, specifying different actions for each thread.
For each inferior thread, the leftmost action with a matching
THREAD-ID is applied. Threads that don't match any action remain
in their current state. Thread IDs are specified using the syntax
described in thread-id syntax. If multiprocess extensions
(multiprocess extensions) are supported, actions can be
specified to match all threads in a process by using the 'pPID.-1'
form of the THREAD-ID. An action with no THREAD-ID matches all
threads. Specifying no actions is an error.
Currently supported actions are:
'c'
Continue.
'C SIG'
Continue with signal SIG. The signal SIG should be two hex
digits.
's'
Step.
'S SIG'
Step with signal SIG. The signal SIG should be two hex
digits.
't'
Stop.
'r START,END'
Step once, and then keep stepping as long as the thread stops
at addresses between START (inclusive) and END (exclusive).
The remote stub reports a stop reply when either the thread
goes out of the range or is stopped due to an unrelated
reason, such as hitting a breakpoint. range stepping.
If the range is empty (START == END), then the action becomes
equivalent to the 's' action. In other words, single-step
once, and report the stop (even if the stepped instruction
jumps to START).
(A stop reply may be sent at any point even if the PC is still
within the stepping range; for example, it is valid to
implement this packet in a degenerate way as a single
instruction step operation.)
The optional argument ADDR normally associated with the 'c', 'C',
's', and 'S' packets is not supported in 'vCont'.
The 't' action is only relevant in non-stop mode (Remote
Non-Stop) and may be ignored by the stub otherwise. A stop reply
should be generated for any affected thread not already stopped.
When a thread is stopped by means of a 't' action, the
corresponding stop reply should indicate that the thread has
stopped with signal '0', regardless of whether the target uses some
other signal as an implementation detail.
The server must ignore 'c', 'C', 's', 'S', and 'r' actions for
threads that are already running. Conversely, the server must
ignore 't' actions for threads that are already stopped.
_Note:_ In non-stop mode, a thread is considered running until GDB
acknowleges an asynchronous stop notification for it with the
'vStopped' packet (Remote Non-Stop).
The stub must support 'vCont' if it reports support for
multiprocess extensions (multiprocess extensions).
Reply: Stop Reply Packets, for the reply specifications.
'vCont?'
Request a list of actions supported by the 'vCont' packet.
Reply:
'vCont[;ACTION...]'
The 'vCont' packet is supported. Each ACTION is a supported
command in the 'vCont' packet.
''
The 'vCont' packet is not supported.
'vCtrlC'
Interrupt remote target as if a control-C was pressed on the remote
terminal. This is the equivalent to reacting to the '^C' ('\003',
the control-C character) character in all-stop mode while the
target is running, except this works in non-stop mode.
interrupting remote targets, for more info on the all-stop
variant.
Reply:
'E NN'
for an error
'OK'
for success
'vFile:OPERATION:PARAMETER...'
Perform a file operation on the target system. For details, see
Host I/O Packets.
'vFlashErase:ADDR,LENGTH'
Direct the stub to erase LENGTH bytes of flash starting at ADDR.
The region may enclose any number of flash blocks, but its start
and end must fall on block boundaries, as indicated by the flash
block size appearing in the memory map (Memory Map Format).
GDB groups flash memory programming operations together, and sends
a 'vFlashDone' request after each group; the stub is allowed to
delay erase operation until the 'vFlashDone' packet is received.
Reply:
'OK'
for success
'E NN'
for an error
'vFlashWrite:ADDR:XX...'
Direct the stub to write data to flash address ADDR. The data is
passed in binary form using the same encoding as for the 'X' packet
(Binary Data). The memory ranges specified by
'vFlashWrite' packets preceding a 'vFlashDone' packet must not
overlap, and must appear in order of increasing addresses (although
'vFlashErase' packets for higher addresses may already have been
received; the ordering is guaranteed only between 'vFlashWrite'
packets). If a packet writes to an address that was neither erased
by a preceding 'vFlashErase' packet nor by some other
target-specific method, the results are unpredictable.
Reply:
'OK'
for success
'E.memtype'
for vFlashWrite addressing non-flash memory
'E NN'
for an error
'vFlashDone'
Indicate to the stub that flash programming operation is finished.
The stub is permitted to delay or batch the effects of a group of
'vFlashErase' and 'vFlashWrite' packets until a 'vFlashDone' packet
is received. The contents of the affected regions of flash memory
are unpredictable until the 'vFlashDone' request is completed.
'vKill;PID'
Kill the process with the specified process ID PID, which is a
hexadecimal integer identifying the process. This packet is used
in preference to 'k' when multiprocess protocol extensions are
supported; see multiprocess extensions.
Reply:
'E NN'
for an error
'OK'
for success
'vMustReplyEmpty'
The correct reply to an unknown 'v' packet is to return the empty
string, however, some older versions of 'gdbserver' would
incorrectly return 'OK' for unknown 'v' packets.
The 'vMustReplyEmpty' is used as a feature test to check how
'gdbserver' handles unknown packets, it is important that this
packet be handled in the same way as other unknown 'v' packets. If
this packet is handled differently to other unknown 'v' packets
then it is possile that GDB may run into problems in other areas,
specifically around use of 'vFile:setfs:'.
'vRun;FILENAME[;ARGUMENT]...'
Run the program FILENAME, passing it each ARGUMENT on its command
line. The file and arguments are hex-encoded strings. If FILENAME
is an empty string, the stub may use a default program (e.g. the
last program run). The program is created in the stopped state.
This packet is only available in extended mode (extended
mode).
Reply:
'E NN'
for an error
'Any stop packet'
for success (Stop Reply Packets)
'vStopped'
Notification Packets.
'X ADDR,LENGTH:XX...'
Write data to memory, where the data is transmitted in binary.
Memory is specified by its address ADDR and number of addressable
memory units LENGTH (addressable memory unit); 'XX...' is
binary data (Binary Data).
Reply:
'OK'
for success
'E NN'
for an error
'z TYPE,ADDR,KIND'
'Z TYPE,ADDR,KIND'
Insert ('Z') or remove ('z') a TYPE breakpoint or watchpoint
starting at address ADDRESS of kind KIND.
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,KIND'
'Z0,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]'
Insert ('Z0') or remove ('z0') a software breakpoint at address
ADDR of type KIND.
A software breakpoint is implemented by replacing the instruction
at ADDR with a software breakpoint or trap instruction. The KIND
is target-specific and typically 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. Some
Architecture-Specific Protocol Details::); if no
architecture-specific value is being used, it should be '0'. KIND
is hex-encoded. COND_LIST is an optional list of conditional
expressions in bytecode form that should be evaluated on the
target's side. These are the conditions that should be taken into
consideration when deciding if the breakpoint trigger should be
reported back to GDB.
See also the 'swbreak' stop reason (swbreak stop reason)
for how to best report a software breakpoint event to GDB.
The COND_LIST parameter is comprised of a series of expressions,
concatenated without separators. Each expression has the following
form:
'X LEN,EXPR'
LEN is the length of the bytecode expression and EXPR is the
actual conditional expression in bytecode form.
The optional CMD_LIST parameter introduces commands that may be run
on the target, rather than being reported back to GDB. The
parameter starts with a numeric flag PERSIST; if the flag is
nonzero, then the breakpoint may remain active and the commands
continue to be run even when GDB disconnects from the target.
Following this flag is a series of expressions concatenated with no
separators. Each expression has the following form:
'X LEN,EXPR'
LEN is the length of the bytecode expression and EXPR is the
actual commands expression in bytecode form.
_Implementation note: It is possible for a target to copy or move
code that contains software 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
'E NN'
for an error
'z1,ADDR,KIND'
'Z1,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]'
Insert ('Z1') or remove ('z1') a hardware breakpoint at address
ADDR.
A hardware breakpoint is implemented using a mechanism that is not
dependent on being able to modify the target's memory. The KIND,
COND_LIST, and CMD_LIST arguments have the same meaning as in 'Z0'
packets.
_Implementation note: A hardware breakpoint is not affected by code
movement._
Reply:
'OK'
success
''
not supported
'E NN'
for an error
'z2,ADDR,KIND'
'Z2,ADDR,KIND'
Insert ('Z2') or remove ('z2') a write watchpoint at ADDR. The
number of bytes to watch is specified by KIND.
Reply:
'OK'
success
''
not supported
'E NN'
for an error
'z3,ADDR,KIND'
'Z3,ADDR,KIND'
Insert ('Z3') or remove ('z3') a read watchpoint at ADDR. The
number of bytes to watch is specified by KIND.
Reply:
'OK'
success
''
not supported
'E NN'
for an error
'z4,ADDR,KIND'
'Z4,ADDR,KIND'
Insert ('Z4') or remove ('z4') an access watchpoint at ADDR. The
number of bytes to watch is specified by KIND.
Reply:
'OK'
success
''
not supported
'E NN'
for an error
Info Catalog
gdb: Overview
gdb: Remote Protocol
gdb: Stop Reply Packets