3.4 KiB
PULSE Flash Imaging
This document describes the PULSE flash imaging protocol. This protocol was originally designed for use over PULSEv1, but also works over the PULSEv2 Best-Effort transport.
The flash imaging protocol is used to write raw data directly to the external flash. It is a message-oriented protocol encapsulated in PULSE frames. The primary goals of the protocol are reliability and speed over high-latency links.
-
All client-sent commands elicit responses
-
As much as possible, any command can be resent without corrupting the flashing process. This is to accommodate the situation where the command was received and acted upon but the response was lost, and the client retried the command.
-
Any notification (server→client message which is not a response to a command) can be lost without holding up the flashing process. There must be a way to poll for the status of all operations which elicit notifications.
-
Most of the state is tracked by the client. The server only has to maintain a minimal, fixed-size amount of state.
The idempotence of writing to flash is leveraged in the design of this protocol to effectively implement a Selective Repeat ARQ with an unlimited window size without requiring the server to keep track of which frames are missing. Any Write Data command to the same location in flash can be repeated any number of times with no ill effects.
Message format
All fields in a message which are more than one octet in length are transmitted least-significant octet (LSB) first.
All messages begin with a 1-octet Opcode, followed by zero or more data fields depending on the message. All Address fields are offsets from the beginning of flash. Address and Length fields are specified in units of bytes.
Client Commands
1 - Erase flash region
Address: 4 octets Length: 4 octets
2 - Write data to flash
Address: 4 octets Data: 1+ octets
The data length is implied.
3 - Checksum flash region
Address: 4 octets Length: 4 octets
4 - Query flash region geometry
Region: 1 octet
| Region | Description |
|---|---|
| 1 | PRF |
| 2 | Firmware resources |
5 - Finalize flash region
Region: 1 octet
Inform the server that writing is complete and perform whatever task is necessary to finalize the data written to the region. This may be a no-op.
Region numbers are the same as for the "Query flash region geometry" message.
Server Responses
128 - ACKnowledge erase command
Address: 4 octets Length: 4 octets Complete?: 1 octet
Complete field is zero if the erase is in progress, nonzero when the erase is complete.
129 - ACKnowledge write command
Address: 4 octets Length: 4 octets Complete?: 1 octet
130 - Checksum result
Address: 4 octets Length: 4 octets Checksum: 4 octets
The legacy Pebble checksum ("STM32 CRC") of the specified memory is returned.
131 - Flash region geometry
Region: 1 octet Address: 4 octets Length: 4 octets
A length of zero indicates that the region does not exist.
132 - ACKnowledge finalize flash region command
Region: 1 octet
192 - Malformed command
Bad message: 9 octets Error string: 0+ octets
193 - Internal error
Error string: 0+ octets
Something has gone terribly wrong which prevents flashing from proceeding.