4.1 The standard remote protocol

The standard remote protocol is a simple, packet based scheme. A debug packet whose contents are <data> is encapsulated for transmission in the form:

	$ <data> # CSUM1 CSUM2

<data> must be ASCII alphanumeric and cannot include characters $ or #. If <data> starts with two characters followed by :, then the existing stubs interpret this as a sequence number. For example, the command g is used to read the values of the registers. So, a packet to do this would look like

        $g#67

CSUM1 and CSUM2 are an ascii representation in hex of an 8-bit checksum of <data>, the most significant nibble is sent first. the hex digits 0-9,a-f are used.

A simple protocol is used when communicating with the target. This is mainly to give a degree of error handling over the serial cable. For each packet transmitted successfully, the target responds with a + (ACK). If there was a transmission error, then the target responds with a - (NAK). An error is determined when the checksum doesn’t match the calculated checksum for that data record. Upon reciept of the ACK, GDB can then transmit the next packet.

Here is a list of the main functions that need to be supported. Each data packet is a command with a set number of bytes in the command packet. Most commands either return data, or respond with a NAK. Commands that don’t return data respond with an ACK. All data values are ascii hex digits. Every byte needs two hex digits to represent t. This means that a byte with the value ‘7’ becomes ‘07’. On a 32 bit machine this works out to 8 characters per word. All of the bytes in a word are stored in the target byte order. When writing the host side of the GDB protocol, be careful of byte order, and make sure that the code will run on both big and little endian hosts and produce the same answers.

These functions are the minimum required to make a GDB backend work. All other commands are optional, and not supported by all GDB backends.

‘read registers g’

returns XXXXXXXX...

Registers are in the internal order for GDB, and the bytes in a register are in the same order the machine uses. All values are in sequence starting with register 0. All registers are listed in the same packet. A sample packet would look like $g#.

‘write registers GXXXXXXXX...’

XXXXXXXX is the value to set the register to. Registers are in the internal order for GDB, and the bytes in a register are in the same order the machine uses. All values are in sequence starting with register 0. All registers values are listed in the same packet. A sample packet would look like $G000000001111111122222222...#

returns ACK or NAK

‘read memory mAAAAAAAA,LLLL’

AAAAAAAA is address, LLLL is length. A sample packet would look like $m00005556,0024#. This would request 24 bytes starting at address 00005556

returns XXXXXXXX... XXXXXXXX is the memory contents. Fewer bytes than requested will be returned if only part of the data can be read. This can be determined by counting the values till the end of packet # is seen and comparing that with the total count of bytes that was requested.

‘write memory MAAAAAAAA,LLLL:XXXXXXXX’

AAAAAAAA is the starting address, LLLL is the number of bytes to be written, and XXXXXXXX is value to be written. A sample packet would look like $M00005556,0024:101010101111111100000000...#

returns ACK or NAK for an error. NAK is also returned when only part of the data is written.

‘continue cAAAAAAAAA’

AAAAAAAA is address to resume execution at. If AAAAAAAA is omitted, resume at the curent address of the pc register.

returns the same replay as last signal. There is no immediate replay to cont until the next breakpoint is reached, and the program stops executing.

‘step sAA..AA’

AA..AA is address to resume If AA..AA is omitted, resume at same address.

returns the same replay as last signal. There is no immediate replay to step until the next breakpoint is reached, and the program stops executing.

‘last signal ?’

This returns one of the following:

• SAA Where AA is the number of the last signal. Exceptions on the target are converted to the most similar Unix style signal number, like SIGSEGV. A sample response of this type would look like $S05#.
• TAAnn:XXXXXXXX;nn:XXXXXXXX;nn:XXXXXXXX; AA is the signal number. nn is the register number. XXXXXXXX is the register value.
• WAA The process exited, and AA is the exit status. This is only applicable for certains sorts of targets.

These are used in some GDB backends, but not all.

‘write reg Pnn=XXXXXXXX’

Write register nn with value XXXXXXXX.

returns ACK or NAK

‘kill request k’

‘toggle debug d’

toggle debug flag (see 386 & 68k stubs)

‘reset r’

reset – see sparc stub.

‘reserved other’

On other requests, the stub should ignore the request and send an empty response $#<checksum>. This way we can extend the protocol and GDB can tell whether the stub it is talking to uses the old or the new.

‘search tAA:PP,MM’

Search backwards starting at address AA for a match with pattern PP and mask MM. PP and MM are 4 bytes.

‘general query qXXXX’

Request info about XXXX.

‘general set QXXXX=yyyy’

Set value of XXXX to yyyy.

‘query sect offs qOffsets’

Get section offsets. Reply is Text=xxx;Data=yyy;Bss=zzz

‘console output Otext’

Send text to stdout. The text gets display from the target side of the serial connection.

Responses 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 run length encoding starts to win). You can’t use a value of where n >126 because it’s only a two byte value. An example would be a 0*03 means the same thing as 0000.