### 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`.