xref: /aosp_15_r20/external/gsc-utils/docs/usb_updater.md (revision 4f2df630800bdcf1d4f0decf95d8a1cb87344f5f)

EC update over USB
==================

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.

Cr50-specific notes
-------------------

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.

Common-code notes
-----------------

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.

Update protocol
---------------

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`.

### State machine (update over USB)

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):

  * Reply with `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):

* If no data is received in 5 seconds, go back to IDLE state.
* If host sends `UPDATE_DONE` command (by setting `dest address` to
  `0xb007ab1e`), go back to IDLE state.
* If host sends a valid block start with a valid address, copy the rest
  of the payload and go to INSIDE_BLOCK 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.

  * If buffer is full (i.e. matches the total expected PDU size), write the
    data and go to OUTSIDE_BLOCK.
  * Else, stay in INSIDE_BLOCK.

### Vendor commands (channeled TPM command, Cr50)

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 (common code)

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):

* UPDATE_EXTRA_CMD_IMMEDIATE_RESET (0): Tell EC to reboot immediately.
* UPDATE_EXTRA_CMD_JUMP_TO_RW (1): Tell EC (in RO) to jump to RW, if the
  signature verifies.
* UPDATE_EXTRA_CMD_STAY_IN_RO (2): Tell EC (in RO), to stay in RO, and not
  jump to RW automatically. After this command is sent, a reset is necessary
  for the EC to accept to jump to RW again.
* UPDATE_EXTRA_CMD_UNLOCK_RW (3): Tell EC to unlock RW on next reset.
* UPDATE_EXTRA_CMD_UNLOCK_ROLLBACK (4): Tell EC to unlock ROLLBACK on next reset.
* UPDATE_EXTRA_CMD_INJECT_ENTROPY (5): Inject entropy into the device-specific
  unique identifier (takes at least CONFIG_ROLLBACK_SECRET_SIZE=32 bytes of
  data).
* UPDATE_EXTRA_CMD_PAIR_CHALLENGE (6): Tell EC to answer a X25519 challenge
  for pairing. Takes in a `struct pair_challenge` as data, answers with a
  `struct pair_challenge_response`.