Next: , Up: Remote Protocol



D.1 Overview

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.