1EC update over USB 2================== 3 4chip/g (Cr50) and common code (hammer, servo_micro/v4) update over USB protocols 5share a lot in terms of protocol and ideas, but use different code bases. 6 7chip/g EC-side implementation is found in `chip/g/*upgrade*`, and the 8userspace tool which provides updates over USB among with supporting other 9features and interfaces is found in `extra/usb_updater/gsctool.c`. 10 11Common code uses implementations in `common/*update*.c` and 12`include/*update*.h`, and `extra/usb_updater/usb_updater2.c` for the userspace 13updater. 14 15Cr50-specific notes 16------------------- 17 18The Cr50 firmware image consists of multiple sections, of interest to the 19USB updater are the RO and RW code sections, two of each. When firmware update 20session is established, the Cr50 device reports locations of backup RW and RO 21sections (those not currently used by the device). 22 23Based on this information the updater carves out the appropriate sections from 24the full Cr50 firmware binary image and sends them to the device for 25programming into flash. Once the new sections are programmed and the device 26is restarted, the new RO and RW are used if they pass verification and are 27logically newer than the existing sections. 28 29There are two ways to communicate with the Cr50 device: USB and `/dev/tpm0` 30(when `gsctool` is running on a chromebook with the Cr50 device). Originally 31different protocols were used to communicate over different channels, 32starting with version 3 the same protocol is used. 33 34Common-code notes 35----------------- 36 37For non-Cr50 or chip/g devices (common code), the layout is a bit different, 38as devices usually have a single RO and a single RW, where RO is truly read-only 39in production, and verifies RW before jumping to it. 40 41For testing and development, `usb_updater2` is provided, while production code 42will use `hammerd` (in `src/platform/hammerd`) to update the device. 43 44Update protocol 45--------------- 46 47The host (either a local AP or a workstation) is the controller of the firmware 48update protocol, it sends data to the Cr50 device, which processes it and 49responds. 50 51The encapsulation format is different between the `/dev/tpm0` and USB cases: 52 53 4 bytes 4 bytes 4 bytes variable size 54 +-----------+--------------+---------------+----------~~--------------+ 55 + total size| block digest | dest address | data | 56 +-----------+--------------+---------------+----------~~--------------+ 57 \ \ / 58 \ \ / 59 \ +----- FW update PDU sent over /dev/tpm0 -----------+ 60 \ / 61 +--------- USB frame, requires total size field ------------+ 62 63The update protocol data units (PDUs) are passed over `/dev/tpm0`, the 64encapsulation includes integrity verification and destination address of 65the data (more of this later). `/dev/tpm0` transactions pretty much do not 66have size limits, whereas the USB data is sent in chunks of the size 67determined when the USB connection is set up. This is why USB requires an 68additional encapsulation into frames to communicate the PDU size to the 69client side so that the PDU can be reassembled before passing to the 70programming function. 71 72In general, the protocol consists of two phases: connection establishment 73and actual image transfer. 74 75The very first PDU of the transfer session is used to establish the 76connection. The first PDU does not have any data, and the `dest address` 77field is set to zero. Receiving such a PDU signals the programming function 78that the host intends to transfer a new image. 79 80The response to the first PDU varies depending on the protocol version. 81 82Note that protocol versions before 5 are described here for completeness, 83but are not supported any more. 84 85Version 1 is used over `/dev/tpm0`. The response is either 4 or 1 bytes in 86size. The 4 byte response is the *base address* of the backup RW section, 87and there is no support for RO updates. The one byte response is an error 88indication, possibly reporting flash erase failure, command format error, etc. 89 90Version 2 is used over USB. The response is 8 bytes in size. The first four 91bytes are either the *base address* of the backup RW section (still no RO 92updates), or an error code, the same as in Version 1. The second 4 bytes 93are the protocol version number (set to 2). 94 95All versions above 2 behave the same over `/dev/tpm0` and USB. 96 97Version 3 response is 16 bytes in size. The first 4 bytes are the error code 98the second 4 bytes are the protocol version (set to 3) and then 4 byte 99*offset* of the RO section followed by the 4 byte *offset* of the RW section. 100 101Version 4 response in addition to version 3 provides header revision fields 102for active RO and RW images running on the target. 103 104Once the connection is established, the image to be programmed into flash 105is transferred to the Cr50 in 1K PDUs. In versions 1 and 2 the address in 106the header is the absolute address to place the block to, in version 3 and 107later it is the offset into the flash. 108 109Protocol version 5 includes RO and RW key ID information into the first PDU 110response. The key ID could be used to tell between prod and dev signing 111modes, among other things. 112 113Protocol version 6 does not change the format of the first PDU response, 114but it indicates the target's ability to channel TPM vendor commands 115through USB connection. 116 117Common-code updater also uses protocol version 6, but has a fairly different 118`first_response_pdu` header, indicated by setting `1` in the higher 16-bit for 119the protocol version field (`header_type`). The response includes fields 120such as maximum PDU size (which is not fixed to 1KB like for Cr50), flash 121protection status, version string, and a minimum rollback version. 122 123Details can be found in `include/update_fw.h`. 124 125### State machine (update over USB) 126 127This describes the EC-side state machine for update over USB. 128 129IDLE state: 130 131* If host sends update start PDU (a command without any payload, digest = 0 132 and base = 0): 133 134 * Reply with `first_update_pdu` block. Go to OUTSIDE_BLOCK state. 135 136* If host sends a vendor command (see below), execute that, reply, and stay 137 in IDLE state. Note that vendor commands are only accepted in IDLE state. 138 139OUTSIDE_BLOCK (preparing to receive start of PDU): 140 141* If no data is received in 5 seconds, go back to IDLE state. 142* If host sends `UPDATE_DONE` command (by setting `dest address` to 143 `0xb007ab1e`), go back to IDLE state. 144* If host sends a valid block start with a valid address, copy the rest 145 of the payload and go to INSIDE_BLOCK state. 146 147INSIDE_BLOCK (in a middle of a PDU): 148 149* If no data is received in 5 seconds, go back to IDLE state. 150* Copy data to a buffer. 151 152 * If buffer is full (i.e. matches the total expected PDU size), write the 153 data and go to OUTSIDE_BLOCK. 154 * Else, stay in INSIDE_BLOCK. 155 156### Vendor commands (channeled TPM command, Cr50) 157 158When channeling TPM vendor commands the USB frame looks as follows: 159 160 4 bytes 4 bytes 4 bytes 2 bytes variable size 161 +-----------+--------------+---------------+-----------+------~~~-------+ 162 + total size| block digest | EXT_CMD | vend. sub.| data | 163 +-----------+--------------+---------------+-----------+------~~~-------+ 164 165Where `Vend. sub` is the vendor subcommand, and data field is subcommand 166dependent. The target tells between update PDUs and encapsulated vendor 167subcommands by looking at the `EXT_CMD` value - it is set to `0xbaccd00a` and 168as such is guaranteed not to be a valid update PDU destination address. 169 170These commands cannot exceed the USB packet size (typically 64 bytes), as 171no reassembly is performed for such frames. 172 173The vendor command response size is not fixed, it is subcommand dependent. 174 175The Cr50 device responds to each update PDU with a confirmation which is 4 176bytes in size in protocol version 2, and 1 byte in size in all other 177versions. Zero value means success, non-zero value is the error code 178reported by Cr50. 179 180Again, vendor command responses are subcommand specific. 181 182### Vendor commands (common code) 183 184Vendor commands for command code look very similar to the TPM vendor commands 185above, except that we use `UPDATE_EXTRA_CMD` (`b007ab1f`) instead of `EXT_CMD`, 186and `Vend. sub.` have a limit set of values (unless otherwise noted, commands 187take no parameter, and reply with a single 1-byte status code): 188 189* UPDATE_EXTRA_CMD_IMMEDIATE_RESET (0): Tell EC to reboot immediately. 190* UPDATE_EXTRA_CMD_JUMP_TO_RW (1): Tell EC (in RO) to jump to RW, if the 191 signature verifies. 192* UPDATE_EXTRA_CMD_STAY_IN_RO (2): Tell EC (in RO), to stay in RO, and not 193 jump to RW automatically. After this command is sent, a reset is necessary 194 for the EC to accept to jump to RW again. 195* UPDATE_EXTRA_CMD_UNLOCK_RW (3): Tell EC to unlock RW on next reset. 196* UPDATE_EXTRA_CMD_UNLOCK_ROLLBACK (4): Tell EC to unlock ROLLBACK on next reset. 197* UPDATE_EXTRA_CMD_INJECT_ENTROPY (5): Inject entropy into the device-specific 198 unique identifier (takes at least CONFIG_ROLLBACK_SECRET_SIZE=32 bytes of 199 data). 200* UPDATE_EXTRA_CMD_PAIR_CHALLENGE (6): Tell EC to answer a X25519 challenge 201 for pairing. Takes in a `struct pair_challenge` as data, answers with a 202 `struct pair_challenge_response`. 203