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.
Note that all packet forms beginning with an upper- or lower-case
letter, other than those described here, are reserved for future use.
- `!'
-
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:
See 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
(see insert breakpoint or watchpoint packet).
- `bc'
- Backward continue. Execute the target system in reverse. No parameter.
See Reverse Execution, for more information.
Reply:
See Stop Reply Packets, for the reply specifications.
- `bs'
- Backward single step. Execute one instruction in reverse. No parameter.
See Reverse Execution, for more information.
Reply:
See Stop Reply Packets, for the reply specifications.
- `c [addr]'
- Continue. addr is address to resume. If addr is omitted,
resume at current address.
This packet is deprecated for multi-threading support. See vCont packet.
Reply:
See 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. See vCont packet.
Reply:
See Stop Reply Packets, for the reply specifications.
- `d'
- Toggle debug flag.
Don't use this packet; instead, define a general set packet
(see 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 (see 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. See 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
. The
specification of several standard `g' packets is specified below.
When reading registers from a trace frame (see Using the 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. See 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.). op depends on the operation to be performed:
it should be `c' for step and continue operations (note that this
is deprecated, supporting the `vCont' command is a better
option), `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'
- Signal, then cycle step. See step with signal packet. See cycle step packet.
- `k'
- Kill request.
FIXME: There is no description of how to operate when a specific
thread context has been selected (i.e. does 'k' kill only that
thread?).
- `m addr,length'
- Read length bytes of memory starting at address addr.
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 bytes 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 bytes of memory starting at address addr.
XX... is the data; 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.
See 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. XX, while needed, is ignored.
This packet is only available in extended mode (see extended mode).
The `R' packet has no reply.
- `s [addr]'
- Single step. addr is the address at which to resume. If
addr is omitted, resume at same address.
This packet is deprecated for multi-threading support. See vCont packet.
Reply:
See 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. See vCont packet.
Reply:
See 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. PP and MM are 4 bytes.
addr must be at least 3 digits.
- `T thread-id'
- Find out if the thread thread-id is alive. See 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 (see extended mode).
Reply:
- `E nn'
- for an error
- `Any stop packet'
- for success in all-stop mode (see Stop Reply Packets)
- `OK'
- for success in non-stop mode (see Remote Non-Stop)
- `vCont[;action[:thread-id]]...'
-
Resume the inferior, specifying different actions for each thread.
If an action is specified with no thread-id, then it is applied to any
threads that don't have a specific action specified; if no default action is
specified then other threads should remain stopped in all-stop mode and
in their current state in non-stop mode.
Specifying multiple
default actions is an error; specifying no actions is also an error.
Thread IDs are specified using the syntax described in thread-id syntax.
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.
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
(see 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 stub must support `vCont' if it reports support for
multiprocess extensions (see multiprocess extensions). Note that in
this case `vCont' actions can be specified to apply to all threads
in a process by using the `ppid.-1' form of the
thread-id.
Reply:
See 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.
- `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 (see 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 (see 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 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
- `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 (see extended mode).
Reply:
- `E nn'
- for an error
- `Any stop packet'
- for success (see Stop Reply Packets)
- `vStopped'
-
In non-stop mode (see Remote Non-Stop), acknowledge a previous stop
reply and prompt for the stub to report another one.
Reply:
- `Any stop packet'
- if there is another unreported stop event (see Stop Reply Packets)
- `OK'
- if there are no unreported stop events
- `X addr,length:XX...'
-
Write data to memory, where the data is transmitted in binary.
addr is address, length is number of bytes,
`XX...' is binary data (see 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...]'
- Insert (`Z0') or remove (`z0') a memory breakpoint at address
addr of type kind.
A memory 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
architectures have additional meanings for kind;
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 GDBN.
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.
see Architecture-Specific Protocol Details.
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
- `E NN'
- for an error
- `z1,addr,kind'
- `Z1,addr,kind[;cond_list...]'
- Insert (`Z1') or remove (`z1') a hardware breakpoint at
address addr.
A hardware breakpoint is implemented using a mechanism that is not
dependant on being able to modify the target's memory. kind
and cond_list 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.
kind is interpreted as the number of bytes to watch.
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.
kind is interpreted as the number of bytes to watch.
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.
kind is interpreted as the number of bytes to watch.
Reply:
- `OK'
- success
- `'
- not supported
- `E NN'
- for an error