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](http://en.wikipedia.org/wiki/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.