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 respectfully.
All GDB commands and responses (other than acknowledgments) 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:
$
packet-data#
checksum
The two-digit checksum is computed as the modulo 256 sum of all
characters between the leading $
and the trailing #
(an
eight bit unsigned checksum).
Implementors should note that prior to GDB 5.0 the protocol specification also included an optional two-digit sequence-id:
$
sequence-id:
packet-data#
checksum
That sequence-id was appended to the acknowledgment. GDB has never output sequence-ids. Stubs that handle packets added since GDB 5.0 must not accept 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):
->$
packet-data#
checksum <-+
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 (the target has again stopped).
packet-data consists of a sequence of characters with the
exception of #
and $
(see X
packet for additional
exceptions).
Fields within the packet should be separated using ,
;
or
:
. Except where otherwise noted all numbers are represented in
HEX with leading zeros suppressed.
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).
Response data can be run-length encoded to save space. A *
means that the next character is an ASCII encoding giving a repeat count
which stands for that many repetitions of the character preceding the
*
. The encoding is n+29
, yielding a printable character
where n >=3
(which is where rle starts to win). The printable
characters $
, #
, +
and -
or with a numeric
value greater than 126 should not be used.
Some remote systems have used a different run-length encoding mechanism
loosely refered to as the cisco encoding. Following the *
character are two hex digits that indicate the size of the packet.
So:
"0*
"
means the same as "0000".
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.
A stub is required to support the g
, G
, m
, M
,
c
, and s
commands. All other commands are
optional.