diff options
author | Tom Hughes <tomhughes@chromium.org> | 2019-06-13 11:24:19 -0700 |
---|---|---|
committer | Commit Bot <commit-bot@chromium.org> | 2019-08-06 18:51:06 +0000 |
commit | 6f76b0a778ee95f82a947aa7d887b1dbb2bc6ac4 (patch) | |
tree | 407755f0b3aa9e49ba3e859b51a59c5947df1e21 /README.md | |
parent | f9d396bf6d4466801549049642960db115a10870 (diff) | |
download | chrome-ec-6f76b0a778ee95f82a947aa7d887b1dbb2bc6ac4.tar.gz |
docs: Add fingerprint (FPMCU) docs
BRANCH=none
BUG=chromium:973205
TEST=make buildall -j
TEST=View Markdown Preview in CLion
TEST=View Markdown in gitiles
Change-Id: I64c6060bdf41f69af05a8ffd64d437fb1fd2b507
Signed-off-by: Tom Hughes <tomhughes@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1658525
Reviewed-by: Aseda Aboagye <aaboagye@chromium.org>
Commit-Queue: Aseda Aboagye <aaboagye@chromium.org>
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 187 |
1 files changed, 17 insertions, 170 deletions
@@ -31,6 +31,20 @@ and [video](http://youtu.be/Ie7LRGgCXC8) from the header) is highly recommended for serial console and JTAG access to the EC. 1. A sense of adventure! +## Terminology + +### EC + +EC (aka Embedded Controller) can refer to many things in the Chrome OS +documentation due to historical reasons. If you just see the term "EC", it +probably refers to "the" EC (i.e. the first one that existed). Most Chrome OS +devices have an MCU, known as "the EC" that controls lots of things (key +presses, turning the AP on/off). The OS that was written for "the" EC is now +running on several different MCUs on Chrome OS devices with various tweaks +(e.g. the FPMCU, the touchpad one that can do palm rejection, etc.). It's quite +confusing, so try to be specific and use terms like FPMCU to distinguish the +fingerprint MCU from "the EC". + ## Getting the EC code The code for the EC is open source and is included in the Chromium OS @@ -554,176 +568,7 @@ addresses are offset. ## Write Protect -The EC has read-only (RO) and read-write (RW) firmware. Coming out of reset, the -EC boots into its RO firmware. The RO firmware boots the host and asks it verify -a hash of the RW firmware (software sync). If the RW firmware is invalid, it is -updated from a copy in the hosts RW firmware. Once the EC RW firmware is valid, -the EC jumps to it (without rebooting). The RO firmware is locked in the factory -and is never changed. The RW firmware can be updated later by pushing a new -system firmware containing an updated EC RW region. - -Note that both the RO and RW firmware regions are normally protected once write -protect has been turned on. The RW region is unprotected at EC boot until it has -been verified by the host. The RW region is protected before the Linux kernel is -loaded. - -### Hardware Write Protect - -A hardware-based mechanism is used to prevent the RO firmware from being -changed. The most common design is to have an input grounded by a screw. When -the screw is inserted, hardware write protect is enabled. This grounded signal -can be read by the host chipset and EC. It is also routed to the “write protect” -pin on any SPI flash chips containing firmware. - -### Software Write Protect - -Software-based write protect state stored in non-volatile memory. If hardware -write protect is enabled, software write protect can be enabled but can’t be -disabled. If hardware write protect is disabled, software write protect can be -enabled or disabled (note that some implementations require an EC reset to -disable software write protect). - -The underlying mechanism implementing software write protect may differ between -EC chips. However the common requirements are that software write protect can -only be disabled when hardware write protect is off and that the RO firmware -must be protected before jumping to RW firmware if protection is enabled. - -### `ectool` - -`ectool` includes commands to enable and disable software write protect. - -#### `ectool flashprotect` - -Print out current flash protection state. - -``` -Flash protect flags: 0x0000000f wp_gpio_asserted ro_at_boot ro_now all_now -Valid flags: 0x0000003f wp_gpio_asserted ro_at_boot ro_now all_now STUCK INCONSISTENT -Writable flags: 0x00000000 -``` - -`Flash protect flags` - Current flags that are set. - -`Valid flags` - All the options for flash protection. - -`Writable flags` - The flags that currently can be changed. (In this case, no -flags can be changed). - -Flags: - -* `wp_gpio_asserted` - Whether the hardware write protect GPIO is currently - asserted (read only). - -* `ro_at_boot` - Whether the EC will write protect the RO firmware on the next - boot of the EC. - -* `ro_now` - Protect the read-only portion of flash immediately. Requires - hardware WP be enabled. - -* `all_now` - Protect the entire flash (including RW) immediately. Requires - hardware WP be enabled. - -* `STUCK` - Flash protection settings have been fused and can’t be cleared - (should not happen during normal operation. Read only.) - -* `INCONSISTENT` - One or more banks of flash is not protected when it should - be (should not happen during normal operation. Read only.). - -#### `ectool flashprotect enable` - -Set `ro_at_boot` flag. The next time the EC is reset it will protect the flash. -Note that this requires a cold reset. - -#### `ectool flashprotect enable now` - -Set `ro_at_boot` `ro_now all_now` flags and immediately protect the flash. Note -that this will fail if hardware write protect is disabled. - -#### `ectool flashprotect disable` - -Clear `ro_at_boot` flag. This can only be cleared if the EC booted without -hardware write protect enabled. - -Note that you must reset the EC to clear write protect after removing the screw. -If the `ro_at_boot` flag set and the EC resets with the HW gpio disabled, the EC -will leave the flash unprotected (`ro_now` and `all_now` flags are not set) but -leave `ro_at_boot` flag set. - -### Flashrom - -Flashrom can also be used to query and enable/disable -[EC flash protection](http://dev.chromium.org/chromium-os/firmware-porting-guide/firmware-ec-write-protection). - -#### View the current state of flash protection - -```bash -(chroot) $ flashrom -p ec --wp-status -``` - -``` -WP: status: 0x00 -WP: status.srp0: 0 -WP: write protect is disabled. -WP: write protect range: start=0x00000000, len=0x00000000 -``` - -#### Enable protection - -This is immediate. The protection range indicates the RO region of the firmware. - -```bash -(chroot) $ flashrom -p ec --wp-enable -``` - -``` -SUCCESS -``` - -```bash -(chroot) $ flashrom -p ec --wp-status -``` - -``` -WP: status: 0x80 -WP: status.srp0: 1 -WP: write protect is enabled. -WP: write protect range: start=0x00000000, len=0x0001f800 -``` - -#### Disable protection - -Disable can only be done with hardware write protect disabled. - -```bash -(chroot) $ flashrom -p ec --wp-disable -``` - -``` -FAILED: RO_AT_BOOT is not clear. -FAILED -``` - -Reboot with screw removed. Note that protection is still enabled but the -protection range is zero. - -```bash -(chroot) $ flashrom -p ec --wp-status -``` - -``` -WP: status: 0x80 -WP: status.srp0: 1 -WP: write protect is enabled. -WP: write protect range: start=0x00000000, len=0x00000000 -``` - -```bash -(chroot) $ flashrom -p ec --wp-disable -``` - -``` -SUCCESS -``` +See [Firmware Write Protection]. ## EC Version Strings @@ -787,3 +632,5 @@ passed as an environment variable `BOARD`: ``` cheese_v1.1.1755-4da9520 ``` + +[Firmware Write Protection]: ./docs/write_protection.md |