Next: , Previous: Standard Replies, Up: Remote Protocol


D.3 Packets

The following table provides a complete list of all currently defined commands and their corresponding response data. See File-I/O Remote Protocol Extension, for details about the File I/O extension of the remote protocol.

Note that all packet forms beginning with an upper- or lower-case letter, other than those described here, are reserved for future use.

A stub is required to support the `g', `G', `m', `M', `c', and `s' commands. All other commands are optional.

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.

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.

`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).

`c [addr]'
Continue. addr is address to resume. If addr is omitted, resume at current address.

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.

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'
Detach gdb from the remote system. Sent to the remote target before gdb disconnects via the detach command.

Reply:

`OK'
for success

`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.

`G XX...'
Write general registers. See read registers packet, for a description of the XX... data.

Reply:

`OK'
for success

`H c t'
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 `0' which means pick any thread.

Reply:

`OK'
for success

`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.

`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'
All the data was written successfully. (If only part of the data was written, this command returns an error.)

`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

`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

`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.

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.

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 XX'
Find out if the thread XX is alive.

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 is a hexadecimal integer identifying the process. If the stub is currently controlling a process, it is killed. The attached process is stopped.

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)

`vCont[;action[:tid]]...'
Resume the inferior, specifying different actions for each thread. If an action is specified with no tid, 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. Specifying multiple default actions is an error; specifying no actions is also an error. Thread IDs are specified in hexadecimal. Currently supported actions are:
`c'
Continue.
`C sig'
Continue with signal sig. sig should be two hex digits.
`s'
Step.
`S sig'
Step with signal sig. sig should be two hex digits.

The optional addr argument normally associated with these packets is not supported in `vCont'.

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.memtype'
for vFlashErase addressing non-flash memory

`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

`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.
`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. If the stub is currently controlling a process, it is killed.

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)

`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

`z type,addr,length'
`Z type,addr,length'
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'
`Z0,addr,length'
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

`z1,addr,length'
`Z1,addr,length'
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

`z2,addr,length'
`Z2,addr,length'
Insert (`Z2') or remove (`z2') a write watchpoint.

Reply:

`OK'
success

`z3,addr,length'
`Z3,addr,length'
Insert (`Z3') or remove (`z3') a read watchpoint.

Reply:

`OK'
success

`z4,addr,length'
`Z4,addr,length'
Insert (`Z4') or remove (`z4') an access watchpoint.

Reply:

`OK'
success