andreil/katapult
1
0
Fork 0
mirror of https://github.com/andreili/katapult.git synced 2025-08-23 19:34:06 +02:00
Code Issues Packages Projects Releases Wiki Activity

protocol: update for latest changes

Browse Source 
Signed-off-by:  Eric Callahan <arksine.code@gmail.com>
This commit is contained in:
Eric Callahan 2022-05-08 19:43:29 -04:00 committed by Eric Callahan
parent 5e7d632c4f
commit 7db2911aed
1 changed files with 54 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
protocol.md
View File

@ -6,7 +6,9 @@
Each command and response is framed as follows: 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> - 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. corresponds to a payload 4 bytes in length.
- The payload is optional depending on the command. If present it must be a - The payload is optional depending on the command. If present it must be a
multiple of 4 bytes in length. 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 command byte, length byte, and payload using
- The CRC is performed on the entire frame (header through trailer) using
the standard CRC16-CCITT algorithm. 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 ### Commands
@ -29,88 +31,97 @@ The bootloader accepts the following commands:
Initiates communication with the bootloader. This command has no payload: 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: 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 - `orig_command` - must be `0x11`
represents the size of a block (in bytes) expected in the `send block` and - `protocol_version` - The current version of the protocol. This is an integer
`request block` commands. Typically this should be 64 bytes. 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` #### Send Block: `0x12`
Sends a block of data to be written. This command takes a `block index` Sends a block of data to be written.
argument followed by the block of data:
``` ```
<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 The `block_address` refers to a address in flash memory where the block write
plus `block_size // 4` for the data. should begin. The first `block_address` must be the `start_address` received
in the [connect](#connect-0x11) command.
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_data` is the data contained with in the block. If the final block 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 is less than `block_size` in length it should be padded with `0xFF` to fill
the remainder. 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: 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 - `orig_command`: Must be `0x12`
order. It must match the `block_index` sent in the request. - `block_address`: Must match the `block_address` sent in the command
#### EOF: `0x13` #### EOF: `0x13`
Indicates that the end of file has been reached and the bootloader should 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: 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 - `orig_command`: Must be `0x13`
represents the total number of pages written to flash. - `page_count`: The total number of pages written to flash.
#### Request Block: `0x14` #### Request Block: `0x14`
Requests of block of data in flash, used for verification. This command takes Requests of block of data in flash, used for verification.
a `block index` argument indicating the block to read:
``` ```
<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 Responds with [acknowledged](#acknowledged-0xa0) containing a payload
in the following format: 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 - `orig_command`: Must be `0x14`
order. It must match the `block_index` sent in the request. - `block_address`: Must match the `block_address` sent in the command
- `block_data`: The requested block of data
#### Complete: `0x15` #### 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: 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 Responds with [acknowledged](#acknowledged-0xa0) containing a 4 byte payload
in the following format: in the following format:
``` ```
<0x15><0x00><0x00><0x00> <4 byte orig_command>
``` ```
### Responses ### 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` #### 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. 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.