|Debugging with GDB|
There may be occasions when you need to know something about the protocol—for example, if there is only one serial port to your target machine, you might want your program to do something special if it recognizes a packet meant for gdb.
In the examples below, ‘->’ and ‘<-’ are used to indicate transmitted and received data, respectively.
All gdb commands and responses (other than acknowledgments and notifications, see Notification Packets) are sent as a packet. A packet is introduced with the character ‘$’, the actual packet-data, and the terminating character ‘#’ followed by a two-digit checksum:
Implementors should note that prior to gdb 5.0 the protocol specification also included an optional two-digit sequence-id:
When either the host or the target machine receives a packet, the first response expected is an acknowledgment: either ‘+’ (to indicate the package was received correctly) or ‘-’ (to request retransmission):
The ‘+’/‘-’ acknowledgments can be disabled once a connection is established. See Packet Acknowledgment, for details.
The host (gdb) sends commands, and the target (the debugging stub incorporated in your program) sends a response. In the case of step and continue commands, the response is only sent when the operation has completed, and the target has again stopped all threads in all attached processes. This is the default all-stop mode behavior, but the remote protocol also supports gdb's non-stop execution mode; see Remote Non-Stop, for details.
packet-data consists of a sequence of characters with the exception of ‘#’ and ‘$’ (see ‘X’ packet for additional exceptions).
Implementors should note that prior to gdb 5.0, the character ‘:’ could not appear as the third character in a packet (as it would potentially conflict with the sequence-id).
Binary data in most packets is encoded either as two hexadecimal digits per byte of binary data. This allowed the traditional remote protocol to work over connections which were only seven-bit clean. Some packets designed more recently assume an eight-bit clean connection, and use a more efficient encoding to send and receive binary data.
The binary data representation uses
7d (ascii ‘}’)
as an escape character. Any escaped byte is transmitted as the escape
character followed by the original character XORed with
For example, the byte
0x7d would be transmitted as the two
0x7d 0x5d. The bytes
0x23 (ascii ‘#’),
0x24 (ascii ‘$’), and
‘}’) must always be escaped. Responses sent by the stub
must also escape
0x2a (ascii ‘*’), so that it
is not interpreted as the start of a run-length encoded sequence
Response data can be run-length encoded to save space.
Run-length encoding replaces runs of identical characters with one
instance of the repeated character, followed by a ‘*’ and a
repeat count. The repeat count is itself sent encoded, to avoid
binary characters in data: a value of n is sent as
+29. For a repeat count greater or equal to 3, this
produces a printable ascii character, e.g. a space (ascii
code 32) for a repeat count of 3. (This is because run-length
encoding starts to win for counts 3 or more.) Thus, for example,
‘0* ’ is a run-length encoding of “0000”: the space character
after ‘*’ means repeat the leading
32 - 29 = 3 more times.
The printable characters ‘#’ and ‘$’ or with a numeric value greater than 126 must not be used. Runs of six repeats (‘#’) or seven repeats (‘$’) can be expanded using a repeat count of only five (‘"’). For example, ‘00000000’ can be encoded as ‘0*"00’.
The error response returned for some packets includes a two character error number. That number is not well defined.
For any command not supported by the stub, an empty response (‘$#00’) should be returned. That way it is possible to extend the protocol. A newer gdb can tell if a packet is supported based on that response.
At a minimum, a stub is required to support the ‘g’ and ‘G’ commands for register access, and the ‘m’ and ‘M’ commands for memory access. Stubs that only control single-threaded targets can implement run control with the ‘c’ (continue), and ‘s’ (step) commands. Stubs that support multi-threading targets should support the ‘vCont’ command. All other commands are optional.