mirror of
https://github.com/andreili/katapult.git
synced 2025-08-23 19:34:06 +02:00
protocol: update for latest changes
Signed-off-by: Eric Callahan <arksine.code@gmail.com>
This commit is contained in:
Eric Callahan
Eric Callahan
parent
5e7d632c4f
commit
7db2911aed
176
protocol.md
176
protocol.md
@ -6,7 +6,9 @@
|
||||
Each command and response is framed as follows:
|
||||
|
||||
```
|
||||
<2 byte header> <1 byte command> <1 byte payload word length> <payload> <2 byte trailer> <2 byte crc>
|
||||
<2 byte header> <1 byte command> <1 byte payload word length> <payload> <2 byte crc> <2 byte trailer>
|
||||
| | | | | |
|
||||
-<0x01><0x88>-- ----------------- CRC Checked Data -------------------- --<0x99><0x03>--
|
||||
```
|
||||
|
||||
- The header is <0x01><0x88>
|
||||
@ -15,10 +17,10 @@ Each command and response is framed as follows:
|
||||
corresponds to a payload 4 bytes in length.
|
||||
- The payload is optional depending on the command. If present it must be a
|
||||
multiple of 4 bytes in length.
|
||||
- Any arguments within the payload should be sent in big endian byte order.
|
||||
- The CRC is performed on the entire frame (header through trailer) using
|
||||
- The CRC is performed on the command byte, length byte, and payload using
|
||||
the standard CRC16-CCITT algorithm.
|
||||
- The CRC and all integer arguments are sent in big endian byte order.
|
||||
- The CRC and all integer arguments within the payload are sent in little-endian
|
||||
byte order.
|
||||
|
||||
### Commands
|
||||
|
||||
@ -29,88 +31,97 @@ The bootloader accepts the following commands:
|
||||
Initiates communication with the bootloader. This command has no payload:
|
||||
|
||||
```
|
||||
<0x01><0x88><0x11><0x00><0x99><0x03><CRC>
|
||||
<0x01><0x88><0x11><0x00><CRC><0x99><0x03>
|
||||
```
|
||||
|
||||
Responds with [acknowledged](#acknowledged-0xa0) containing a 4 byte payload
|
||||
Responds with [acknowledged](#acknowledged-0xa0) containing a 16 byte payload
|
||||
in the following format:
|
||||
|
||||
```
|
||||
<0x11><0x00><2 byte block_size>
|
||||
<4 byte orig_command><4 byte protocol_version><4 byte start_address><4 byte block_size>
|
||||
```
|
||||
|
||||
The `block_size` is a 16 bit unsigned integer in big endian byte order. It
|
||||
represents the size of a block (in bytes) expected in the `send block` and
|
||||
`request block` commands. Typically this should be 64 bytes.
|
||||
- `orig_command` - must be `0x11`
|
||||
- `protocol_version` - The current version of the protocol. This is an integer
|
||||
value, where each of the 3 least significant bytes represent a part of the
|
||||
version string. For example, a value of `0x00010002` represents `1.0.2`.
|
||||
- `start_address` - The application start address in flash memory. All addresses
|
||||
provided in the `send_block` and `request block` commands must start at this
|
||||
address.
|
||||
- `block_size` - the size of a block (in bytes) expected in the `send block` and
|
||||
`request block` commands. Typically this should be 64 bytes.
|
||||
|
||||
|
||||
#### Send Block: `0x12`
|
||||
|
||||
Sends a block of data to be written. This command takes a `block index`
|
||||
argument followed by the block of data:
|
||||
Sends a block of data to be written.
|
||||
|
||||
```
|
||||
<0x01><0x88><0x12><1 byte payload word length><4 byte block_index><block_data><0x99><0x03><CRC>
|
||||
<0x01><0x88><0x12><1 byte payload word length><4 byte block_address><block_data><CRC><0x99><0x03>
|
||||
```
|
||||
The `payload word length` will include one word for the `block_address` argument
|
||||
plus `block_size / 4` for the data.
|
||||
|
||||
The `payload word length` will include one word for the block index argument
|
||||
plus `block_size // 4` for the data.
|
||||
|
||||
The `block_index` refers to a single block within the binary of `block_size`
|
||||
bytes, starting at 0. It should be sent as 32-bit integer in big endian format.
|
||||
The `block_address` refers to a address in flash memory where the block write
|
||||
should begin. The first `block_address` must be the `start_address` received
|
||||
in the [connect](#connect-0x11) command.
|
||||
|
||||
The `block_data` is the data contained with in the block. If the final block
|
||||
is less than `block_size` in length it should be padded with `0xFF` to fill
|
||||
the remainder.
|
||||
|
||||
Responds with [acknowledged](#acknowledged-0xa0) containing a 4 byte payload
|
||||
Responds with [acknowledged](#acknowledged-0xa0) containing an 8 byte payload
|
||||
in the following format:
|
||||
|
||||
```
|
||||
<0x12><0x00><2 byte block_index>
|
||||
<4 byte orig_command><4 byte block_address>
|
||||
```
|
||||
|
||||
The returned `block_index` is a 16-bit unsigned integer in big endian byte
|
||||
order. It must match the `block_index` sent in the request.
|
||||
- `orig_command`: Must be `0x12`
|
||||
- `block_address`: Must match the `block_address` sent in the command
|
||||
|
||||
#### EOF: `0x13`
|
||||
|
||||
Indicates that the end of file has been reached and the bootloader should
|
||||
write any remaining in the buffer to flash. This command has no payload:
|
||||
write any remaining data in the buffer to flash. This command has no payload:
|
||||
|
||||
```
|
||||
<0x01><0x88><0x13><0x00><0x99><0x03><CRC>
|
||||
<0x01><0x88><0x13><0x00><CRC><0x99><0x03>
|
||||
```
|
||||
|
||||
Responds with [acknowledged](#acknowledged-0xa0) containing a 4 byte payload
|
||||
Responds with [acknowledged](#acknowledged-0xa0) containing an 8 byte payload
|
||||
in the following format:
|
||||
|
||||
```
|
||||
<0x13><0x00><2 byte page_count>
|
||||
<4 byte orig_command><4 byte page_count>
|
||||
```
|
||||
|
||||
The `page_count` is a 16-bit unsigned integer in big endian byte order. It
|
||||
represents the total number of pages written to flash.
|
||||
- `orig_command`: Must be `0x13`
|
||||
- `page_count`: The total number of pages written to flash.
|
||||
|
||||
#### Request Block: `0x14`
|
||||
|
||||
Requests of block of data in flash, used for verification. This command takes
|
||||
a `block index` argument indicating the block to read:
|
||||
Requests of block of data in flash, used for verification.
|
||||
|
||||
```
|
||||
<0x01><0x88><0x14><0x01><4 byte block_index><0x99><0x03><CRC>
|
||||
<0x01><0x88><0x14><0x01><4 byte block_address><CRC><0x99><0x03>
|
||||
```
|
||||
|
||||
The `block_index` is a 32-bit unsigned integer in big endian byte order.
|
||||
The `block_address` refers to a address in flash memory where the block read
|
||||
should begin. The first `block_address` must be the `start_address` received
|
||||
in the [connect](#connect-0x11) command.
|
||||
|
||||
Responds with [acknowledged](#acknowledged-0xa0) containing a payload
|
||||
in the following format:
|
||||
|
||||
```
|
||||
<0x14><0x00><2 byte block_index><block_data>
|
||||
<4 byte orig_command><4 byte block_address><block_data>
|
||||
```
|
||||
|
||||
The returned `block_index` is a 16-bit unsigned integer in big endian byte
|
||||
order. It must match the `block_index` sent in the request.
|
||||
- `orig_command`: Must be `0x14`
|
||||
- `block_address`: Must match the `block_address` sent in the command
|
||||
- `block_data`: The requested block of data
|
||||
|
||||
|
||||
#### Complete: `0x15`
|
||||
|
||||
@ -118,112 +129,33 @@ Indicates that process is complete. The bootloader will reset and attempt
|
||||
to jump to the application after responding to this command:
|
||||
|
||||
```
|
||||
<0x01><0x88><0x15><0x00><0x99><0x03><CRC>
|
||||
<0x01><0x88><0x15><0x00><CRC><0x99><0x03>
|
||||
```
|
||||
|
||||
Responds with [acknowledged](#acknowledged-0xa0) containing a 4 byte payload
|
||||
in the following format:
|
||||
|
||||
```
|
||||
<0x15><0x00><0x00><0x00>
|
||||
<4 byte orig_command>
|
||||
```
|
||||
|
||||
### Responses
|
||||
|
||||
All responses contain a payload of at least 4 bytes, where the first
|
||||
byte contains the command being responded to. It is possible for
|
||||
a response to include another argument within this first word.
|
||||
|
||||
#### Acknowledged: `0xa0`
|
||||
|
||||
This response indicate successful execution of a command:
|
||||
This response indicates successful execution of a command:
|
||||
|
||||
```
|
||||
<0x01><0x88><0xa0><payload word length><payload><0x99><0x03><CRC>
|
||||
<0x01><0x88><0xa0><payload word length><payload><CRC><0x99><0x03>
|
||||
```
|
||||
|
||||
The payload depends on the command.
|
||||
|
||||
#### Invalid Command: `0xf0`
|
||||
#### NACK: `0xf1`
|
||||
|
||||
Indicates the the bootloader received an invalid command:
|
||||
Indicates that the bootloader encountered an error when processing
|
||||
a command.
|
||||
|
||||
```
|
||||
<0x01><0x88><0xf0><0x01><4 byte payload><0x99><0x03><CRC>
|
||||
<0x01><0x88><0xf1><0x00><0x68><0x95><0x99><0x03>
|
||||
```
|
||||
|
||||
The payload is in the following format:
|
||||
|
||||
```
|
||||
<1 byte orig_command><0x00><0x00><0x00>
|
||||
```
|
||||
|
||||
The `orig_command` is the invalid command received.
|
||||
|
||||
#### CRC Mismatch: `0xf1`
|
||||
|
||||
Indicates that CRC verification failed on the requested command:
|
||||
|
||||
```
|
||||
<0x01><0x88><0xf1><0x01><4 byte payload><0x99><0x03><CRC>
|
||||
```
|
||||
|
||||
The payload is in the following format:
|
||||
|
||||
```
|
||||
<1 byte orig_command><0x00><2 byte calculated_crc>
|
||||
```
|
||||
|
||||
The `command` is the command received from the original request.
|
||||
The `calculated_crc` is a 16-bit unsigned integer represented
|
||||
the CRC calculated on the frame.
|
||||
|
||||
#### Invalid Block: `0xf2`
|
||||
|
||||
Indicates that the payload contained in a [send block](#send-block-0x12)
|
||||
command is not of the expected lenght:
|
||||
|
||||
```
|
||||
<0x01><0x88><0xf2><0x01><4 byte payload><0x99><0x03><CRC>
|
||||
```
|
||||
|
||||
The payload is in the following format:
|
||||
|
||||
```
|
||||
<1 byte orig_command><0x00><0x00><0x00>
|
||||
```
|
||||
|
||||
The `orig_command` is the command received which generated
|
||||
|
||||
#### Invalid Trailer: `0xf3`
|
||||
|
||||
Indicates that the trailer of the frame is not `<0x88><0x03>`:
|
||||
|
||||
```
|
||||
<0x01><0x88><0xf3><0x01><4 byte payload><0x99><0x03><CRC>
|
||||
```
|
||||
|
||||
The payload is in the following format:
|
||||
|
||||
```
|
||||
<1 byte orig_command><0x00><0x00><0x00>
|
||||
```
|
||||
|
||||
The `orig_command` is the command received from the original request.
|
||||
|
||||
#### Invalid Length: `0xf4`
|
||||
|
||||
Indicates that the payload length of a request is too large
|
||||
to fit within the buffer:
|
||||
|
||||
```
|
||||
<0x01><0x88><0xf4><0x01><4 byte payload><0x99><0x03><CRC>
|
||||
```
|
||||
|
||||
The payload is in the following format:
|
||||
|
||||
```
|
||||
<1 byte orig_command><0x00><0x00><0x00>
|
||||
```
|
||||
|
||||
The `orig_command` is the command received from the original request.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user