Next: Stop Reply Packets, Previous: Overview, Up: Remote Protocol
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.
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’. See 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.
Reply:
Reply:
See Stop Reply Packets, for the reply specifications.
argv[] array passed into program. arglen
specifies the number of bytes in the hex encoded byte stream
arg. See gdbserver for more details.
Reply:
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.
Don't use this packet. Use the ‘Z’ and ‘z’ packets instead (see insert breakpoint or watchpoint packet).
Reply: See Stop Reply Packets, for the reply specifications.
Reply:
See Stop Reply Packets, for the reply specifications.
This packet is deprecated for multi-threading support. See vCont packet.
Reply:
See Stop Reply Packets, for the reply specifications.
This packet is deprecated for multi-threading support. See vCont packet.
Reply:
See Stop Reply Packets, for the reply specifications.
Don't use this packet; instead, define a general set packet
(see General Query Packets).
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:
Reply:
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
Reply:
Reply:
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 (see 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
(see ? packet).
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:
Reply:
Reply:
Reply:
Don't use this packet; use the ‘R’ packet instead.
The ‘R’ packet has no reply.
This packet is deprecated for multi-threading support. See vCont packet.
Reply:
See Stop Reply Packets, for the reply specifications.
This packet is deprecated for multi-threading support. See vCont packet.
Reply:
See Stop Reply Packets, for the reply specifications.
Reply:
This packet is only available in extended mode (see extended mode).
Reply:
Currently supported actions are:
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 (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.
Reply:
Reply:
Reply:
Reply:
This packet is only available in extended mode (see extended mode).
Reply:
Reply:
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.
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.
See also the ‘swbreak’ stop reason (see swbreak stop reason) for how to best report a memory breakpoint event to gdb.
The cond_list parameter is comprised of a series of expressions, concatenated without separators. Each expression has the following 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:
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:
A hardware breakpoint is implemented using a mechanism that is not dependant on being able to modify the target's memory. The kind and cond_list have the same meaning as in ‘Z0’ packets.
Implementation note: A hardware breakpoint is not affected by code movement.
Reply:
Reply:
Reply:
Reply: