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.