chip/g (Cr50) and common code (hammer, servo_micro/v4) update over USB protocols share a lot in terms of protocol and ideas, but use different code bases.
chip/g EC-side implementation is found in chip/g/*upgrade*, and the userspace tool which provides updates over USB among with supporting other features and interfaces is found in extra/usb_updater/gsctool.c.
Common code uses implementations in common/*update*.c and include/*update*.h, and extra/usb_updater/usb_updater2.c for the userspace updater.
The Cr50 firmware image consists of multiple sections, of interest to the USB updater are the RO and RW code sections, two of each. When firmware update session is established, the Cr50 device reports locations of backup RW and RO sections (those not currently used by the device).
Based on this information the updater carves out the appropriate sections from the full Cr50 firmware binary image and sends them to the device for programming into flash. Once the new sections are programmed and the device is restarted, the new RO and RW are used if they pass verification and are logically newer than the existing sections.
There are two ways to communicate with the Cr50 device: USB and /dev/tpm0 (when gsctool is running on a chromebook with the Cr50 device). Originally different protocols were used to communicate over different channels, starting with version 3 the same protocol is used.
For non-Cr50 or chip/g devices (common code), the layout is a bit different, as devices usually have a single RO and a single RW, where RO is truly read-only in production, and verifies RW before jumping to it.
For testing and development, usb_updater2 is provided, while production code will use hammerd (in src/platform/hammerd) to update the device.
The host (either a local AP or a workstation) is the controller of the firmware update protocol, it sends data to the Cr50 device, which processes it and responds.
The encapsulation format is different between the /dev/tpm0 and USB cases:
4 bytes 4 bytes 4 bytes variable size
+-----------+--------------+---------------+----------~~--------------+
+ total size| block digest | dest address | data |
+-----------+--------------+---------------+----------~~--------------+
\ \ /
\ \ /
\ +----- FW update PDU sent over /dev/tpm0 -----------+
\ /
+--------- USB frame, requires total size field ------------+
The update protocol data units (PDUs) are passed over /dev/tpm0, the encapsulation includes integrity verification and destination address of the data (more of this later). /dev/tpm0 transactions pretty much do not have size limits, whereas the USB data is sent in chunks of the size determined when the USB connection is set up. This is why USB requires an additional encapsulation into frames to communicate the PDU size to the client side so that the PDU can be reassembled before passing to the programming function.
In general, the protocol consists of two phases: connection establishment and actual image transfer.
The very first PDU of the transfer session is used to establish the connection. The first PDU does not have any data, and the dest address field is set to zero. Receiving such a PDU signals the programming function that the host intends to transfer a new image.
The response to the first PDU varies depending on the protocol version.
Note that protocol versions before 5 are described here for completeness, but are not supported any more.
Version 1 is used over /dev/tpm0. The response is either 4 or 1 bytes in size. The 4 byte response is the base address of the backup RW section, and there is no support for RO updates. The one byte response is an error indication, possibly reporting flash erase failure, command format error, etc.
Version 2 is used over USB. The response is 8 bytes in size. The first four bytes are either the base address of the backup RW section (still no RO updates), or an error code, the same as in Version 1. The second 4 bytes are the protocol version number (set to 2).
All versions above 2 behave the same over /dev/tpm0 and USB.
Version 3 response is 16 bytes in size. The first 4 bytes are the error code the second 4 bytes are the protocol version (set to 3) and then 4 byte offset of the RO section followed by the 4 byte offset of the RW section.
Version 4 response in addition to version 3 provides header revision fields for active RO and RW images running on the target.
Once the connection is established, the image to be programmed into flash is transferred to the Cr50 in 1K PDUs. In versions 1 and 2 the address in the header is the absolute address to place the block to, in version 3 and later it is the offset into the flash.
Protocol version 5 includes RO and RW key ID information into the first PDU response. The key ID could be used to tell between prod and dev signing modes, among other things.
Protocol version 6 does not change the format of the first PDU response, but it indicates the target's ability to channel TPM vendor commands through USB connection.
Common-code updater also uses protocol version 6, but has a fairly different first_response_pdu header, indicated by setting 1 in the higher 16-bit for the protocol version field (header_type). The response includes fields such as maximum PDU size (which is not fixed to 1KB like for Cr50), flash protection status, version string, and a minimum rollback version.
Details can be found in include/update_fw.h.
This describes the EC-side state machine for update over USB.
IDLE state:
If host sends update start PDU (a command without any payload, digest = 0 and base = 0):
first_update_pdu block. Go to OUTSIDE_BLOCK state.If host sends a vendor command (see below), execute that, reply, and stay in IDLE state. Note that vendor commands are only accepted in IDLE state.
OUTSIDE_BLOCK (preparing to receive start of PDU):
UPDATE_DONE command (by setting dest address to 0xb007ab1e), go back to IDLE state.INSIDE_BLOCK (in a middle of a PDU):
If no data is received in 5 seconds, go back to IDLE state.
Copy data to a buffer.
When channeling TPM vendor commands the USB frame looks as follows:
4 bytes 4 bytes 4 bytes 2 bytes variable size +-----------+--------------+---------------+-----------+------~~~-------+ + total size| block digest | EXT_CMD | vend. sub.| data | +-----------+--------------+---------------+-----------+------~~~-------+
Where Vend. sub is the vendor subcommand, and data field is subcommand dependent. The target tells between update PDUs and encapsulated vendor subcommands by looking at the EXT_CMD value - it is set to 0xbaccd00a and as such is guaranteed not to be a valid update PDU destination address.
These commands cannot exceed the USB packet size (typically 64 bytes), as no reassembly is performed for such frames.
The vendor command response size is not fixed, it is subcommand dependent.
The Cr50 device responds to each update PDU with a confirmation which is 4 bytes in size in protocol version 2, and 1 byte in size in all other versions. Zero value means success, non-zero value is the error code reported by Cr50.
Again, vendor command responses are subcommand specific.
Vendor commands for command code look very similar to the TPM vendor commands above, except that we use UPDATE_EXTRA_CMD (b007ab1f) instead of EXT_CMD, and Vend. sub. have a limit set of values (unless otherwise noted, commands take no parameter, and reply with a single 1-byte status code):
struct pair_challenge as data, answers with a struct pair_challenge_response.