summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorNicolas Boichat <drinkcat@google.com>2017-04-25 08:54:34 +0800
committerchrome-bot <chrome-bot@chromium.org>2017-07-13 22:03:37 -0700
commit78a9c2b840f1feac521aa66256ec7d67d415740b (patch)
treed031539d3214fb7b9a62a13998e8c6b6a2defd74 /docs
parent53f6c38e9297adaf3f8384ac1e7ab29957f40064 (diff)
downloadchrome-ec-78a9c2b840f1feac521aa66256ec7d67d415740b.tar.gz
docs: Add USB updater documentation to docs folder
Mostly copied from extra/usb_updater/usb_updater.c, makes it easier to reference from multiple locations (usb_updater, header files, etc.). BRANCH=none BUG=b:36375666 TEST=~/chromium/src/tools/md_browser/md_browser.py -d docs Change-Id: I6939ef74dd18b28ce5b8211c9a84f4adcf4e56b0 Reviewed-on: https://chromium-review.googlesource.com/486479 Commit-Ready: Nicolas Boichat <drinkcat@chromium.org> Tested-by: Nicolas Boichat <drinkcat@chromium.org> Reviewed-by: Aseda Aboagye <aaboagye@chromium.org>
Diffstat (limited to 'docs')
-rw-r--r--docs/usb_updater.md120
1 files changed, 120 insertions, 0 deletions
diff --git a/docs/usb_updater.md b/docs/usb_updater.md
new file mode 100644
index 0000000000..987c21893b
--- /dev/null
+++ b/docs/usb_updater.md
@@ -0,0 +1,120 @@
+EC update over USB
+==================
+
+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 `usb_updater` 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.
+
+Update protocol
+---------------
+
+The host (either a local AP or a workstation) is the master 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.
+
+### Vendor commands
+
+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.