diff options
| author | Vadim Bendebury <vbendeb@chromium.org> | 2020-07-01 14:53:27 -0700 |
|---|---|---|
| committer | Commit Bot <commit-bot@chromium.org> | 2020-07-10 22:54:06 +0000 |
| commit | dccc9023faec5a7c55487fcf6ca6d1b96d4cd08e (patch) | |
| tree | e4903bbd1fb2f735eb0e0121ab985b28a4a935c7 /docs | |
| parent | 23ea3fbd4a6e52b8a54f4278bbed8975af34cca7 (diff) | |
| download | chrome-ec-dccc9023faec5a7c55487fcf6ca6d1b96d4cd08e.tar.gz | |
docs: update CCD docs locations
BRANCH=none
BUG=none
TEST=verified that gitfiles points at the correct documents.
Signed-off-by: Vadim Bendebury <vbendeb@chromium.org>
Change-Id: I6123e74449d6dbda1645f4293dd24914ccaf0d37
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2276330
Reviewed-by: Jett Rink <jettrink@chromium.org>
Reviewed-by: Tom Hughes <tomhughes@chromium.org>
Commit-Queue: Tom Hughes <tomhughes@chromium.org>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/case_closed_debugging.md | 228 | ||||
| -rw-r--r-- | docs/case_closed_debugging_cr50.md | 835 | ||||
| -rw-r--r-- | docs/ccd_howtos.md | 386 | ||||
| -rw-r--r-- | docs/fingerprint/fingerprint-authentication-design-doc.md | 2 | ||||
| -rw-r--r-- | docs/usb-c.md | 8 | ||||
| -rw-r--r-- | docs/write_protection.md | 12 |
6 files changed, 17 insertions, 1454 deletions
diff --git a/docs/case_closed_debugging.md b/docs/case_closed_debugging.md index ab6202af92..05373f1de9 100644 --- a/docs/case_closed_debugging.md +++ b/docs/case_closed_debugging.md @@ -1,226 +1,2 @@ -# Case Closed Debugging (CCD) - -Case closed debugging is a feature of the EC codebase that can bridge UART -consoles and SPI buses from a DUT (Device Under Test) to the host machine via -USB. This allows the host to access and update much of the DUT's state. Use -cases include automated hardware testing as well as simplified debug console -access and firmware flashing for kernel and system developers. - -[TOC] - -## Prerequisites - -### Supported Devices - -We have added CCD support for two chip families: stm32 and gchips. Ryu, -[`servo_micro`], and [`servo_v4`] use the stm32 support. Cr50 uses gchips -support. All boards with Cr50 have support for case closed debugging. - -### Suzy-Q - -[Suzy-Q] is a Type-C dongle that exposes USB2.0/3.0 on a Type-A socket, case -closed debugging over SBU1/2 on a micro Type-B socket, and charging over a -Type-C socket. You will need one to access the case closed debugging USB -interface. Full details, including where to buy and how to make your own are in -the [Suzy-Q docs][Suzy-Q]. - -### Chromium OS flashrom - -The functionality to flash the AP firmware image over case closed debugging is -currently only supported by the ChromiumOS version of flashrom, so you will need -to have that built. The easiest way to do so is to just setup the Chromium OS -SDK. - -### Udev rules file - -There is a udev rules file, `extra/usb_serial/51-google-serial.rules` that -should be installed in `/etc/udev/rules.d/` and udev should be told to reread -its rules. This rules file can be installed using the `extra/usb_serial/install` -script. - -### Kernel module - -A trivial Linux kernel module that identifies case closed debug capable USB -interfaces can be found in `extra/usb_serial`. This module is also built and -installed using the `extra/usb_serial/install` script. - -### Chromium OS chroot - -This is really only a requirement for using flashrom. If you only need access to -the serial consoles then a checkout of the EC firmware repository should be -sufficient. - -## Setup - -### Device Under Test (DUT) - -If the DUT doesn't have a new enough PD firmware you will need to update the -firmware using a Servo, `ectool`, or MCU specific DFU mode, all of which are -outside the scope of this document. - -Make sure your DUT is charged up, because while using [Suzy-Q] you can't -currently charge the device. - -### Suzy-Q - -[Suzy-Q] should be connected to the DUT using the Type-C cable and connector -integrated into [Suzy-Q]. This connector may need to be flipped to make case -closed debugging work because the SBU lines that are used to expose the PD MCU's -USB interface are not orientation invariant. Only one port on the DUT will -support CCD. Try using the other port if the CCD device doesn't appear. [Suzy-Q] -should be connected to the Host with a Type-A (Host) to Micro Type-B ([Suzy-Q]) -cable. Look for the device [`vendor:product ID`](#Troubleshooting) to your host -sees the CCD device. - -### Host - -Depending on your kernel version the consoles may exist at `/dev/ttyUSB*`. If -using those works for you, you don't need to install any drivers or Udev rules. - -If you want your host to generate useful symlinks for the different CCD -consoles, install the Udev rule. It will generate symlinks in -`/dev/google/<device name>/serial/<console name>` for each serial console that a -device exports. It will also mark the DUT as incompatible with ModemManager. -This last part ensures that ModemManager doesn't attempt to open and manipulate -the various serial consoles exported by the device. - -The kernel module in `extra/usb_serial` should be compiled and installed in the -running kernel. It just adds an entry into the `usbserial` module's driver table -that causes `usbserial` to recognize any case closed debugging serial console as -a simple USB serial device. This addition has already made its way into the -upstream kernel (v3.19), so eventually this module can be removed. The -`extra/usb_serial/install` script will build and install the kernel module as -well as install the udev rules file. - -If for some reason you can't or don't want to use the kernel module the install -script provides a `--fallback` option that will install a udev rules file and -helper script instead that will add each new CCD capable device that is attached -to the host to the list of devices that usbserial will handle. The disadvantage -of this method is that it will generate `/dev/ttyUSB*` entries for any USB -interface on the device that has an IN/OUT pair of bulk endpoints. This results -in extra `/dev/ttyUSB*` entries that should not be used because they are -actually I2C or SPI bridges. - -The raiden module solves this by identifying a CCD serial port by the subclass -and protocol numbers of the USB device interface. This means that there does not -need to be a list of CCD capable device IDs anywhere. - -## Basic CCD - -Here's the basic information for how to use CCD. Cr50 restricts debugging -features to try and ensure only the device owner can use CCD. For information on -how to get access to Cr50 CCD see the [Cr50 specific CCD doc][Cr50 CCD]. - -### Consoles - -The serial consoles exposed by case closed debugging can be found in -`/dev/ttyUSB*` or `/dev/google/<device name>/serial/<console name>` if you -installed the Udev rules. The consoles can be opened with any program that you -would normally use to open a TTY character device such as minicom or screen. - -If you installed the Udev rules, the console path will be determined based on -the device and USB bus. The `<device name>` field is generated from the DUT's -USB descriptor `iProduct` field as well as the USB bus index and device path on -that bus (the list of port numbers for the hub connections between the Host and -DUT). As such it is unique to a particular setup and won't change across reboots -of either the Host or the DUT. The `<console name>` field is just the -`iInterface` USB descriptor field from the particular USB interface that is -associated with this console device. This allows a single DUT to expose multiple -serial consoles in a discoverable and consistent manner. - -If you're using the consoles at `/dev/ttyUSB*`, you can just check which console -it is by running a few commands like `version`. - -### Flash AP - -Programming the AP SPI flash with a new firmware image can be done with flashrom -using the command: - -```bash -(chroot) $ sudo /usr/sbin/flashrom -p raiden_debug_spi -w /build/<board>/firmware/image.bin -``` - -If there are more than one case closed debug capable devices connected to the -host you will have to disambiguate the DUT with additional programmer -parameters. Flashrom will list all DUTs that are found along with programmer -parameters that can be used to identify the intended DUT. Flashrom programmer -added to the programmer name (the `-p` argument) by appending a colon and then a -colon and then a comma separated list of `key=value` pairs. The `serial` -parameter is best for this. - -```bash -(chroot) $ sudo /usr/sbin/flashrom -p raiden_debug_spi:serial=${SERIAL} -w /build/<board>/firmware/image.bin -``` - -Cr50 can be used to flash the AP or EC. You will need to specify the AP as the -target device, so cr50 knows to flash the AP. - -```bash -(chroot) $ sudo flashrom -p raiden_debug_spi:target=AP -w image.bin -``` - -### Flash EC - -You can use `util/flash_ec` to flash the EC. Steps for flashing the EC are more -complex and board specific than flashing the AP. This script will handle all the -board specific setup. - -## Known Issues - -1. Charge and the use of the Type-A port on [Suzy-Q] do not work, so for now if - you need to attach a flash drive, or use Fastboot/adb you'll need to swap - cables. - -2. Ryu implementation: software sync of the EC/PD processor and the jump from - RO to RW versions will cause the case closed debugging USB device to - disconnect and reconnect. This can be prevented by disabling software sync. - This is done by setting the `GBB_FLAG_DISABLE_EC_SOFTWARE_SYNC` and - `GBB_FLAG_DISABLE_PD_SOFTWARE_SYNC` flags with`gbb_utility. - -## Troubleshooting - -Check for the CCD device using the following `vendor:product` IDs - -Device | VID:PID ---------------- | ----------- -[`servo_micro`] | `18d1:501a` -[`servo_v4`] | `18d1:501b` -[`servo_v2`] | `18d1:5002` -`ryu` | `18d1:500f` -`cr50` | `18d1:5014` - -See the [`SERVO_PID_DEFAULTS`] in the servo code for all values. - -### Can't see the CCD device on the host - -1. Type-C cable from [Suzy-Q] to the DUT may be upside down. The SBU lines used - for case closed debugging are not orientation invariant. -1. You may be using the wrong device port. Try using the other port. -1. The device may not be charged enough to boot. [Suzy-Q] can't charge the - device or supply enough power for the DUT to boot. Make sure the device is - somewhat charged. - -### No console interfaces are available in the "/dev/google/<name>" directory - -1. Kernel module may not be loaded. -1. Udev rules file might not be installed correctly. -1. PD firmware version may be too old. -1. Type-C cable from [Suzy-Q] to the DUT may be upside down. The SBU lines used - for case closed debugging are not orientation invariant. - -### Garbage messages (AT command set) show up on one or more consoles - -1. ModemManager has claimed the interface, Udev rules file may not be installed - correctly. - -### Console interfaces appear and then quickly disappear - -1. Software sync from the AP has replaced the PD firmware with a version that - is not compatible with case closed debugging. - -[`servo_v4`]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/servo_v4.md -[`servo_v2`]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/servo_v2.md -[`servo_micro`]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/servo_micro.md -[Cr50 CCD]: ./case_closed_debugging_cr50.md -[Suzy-Q]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/ccd.md#suzyq-suzyqable -[`SERVO_PID_DEFAULTS`]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/ff8e96686ef3d9ad2e26125ca8268cb7f7666f6c/servo/interface/ftdi_common.py#28 +The has been moved into a [different +branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging.md) diff --git a/docs/case_closed_debugging_cr50.md b/docs/case_closed_debugging_cr50.md index 0e244c15a0..6eb622cc37 100644 --- a/docs/case_closed_debugging_cr50.md +++ b/docs/case_closed_debugging_cr50.md @@ -1,833 +1,2 @@ -# Google Security Chip (GSC) Case Closed Debugging (CCD) - -Cr50 is the firmware that runs on the Google Security Chip (GSC), which has -support for [Case Closed Debugging](CCD). - -This document explains how to setup CCD, so you can access all of the necessary -features to develop firmware on your Chrome OS device, access -[debug consoles][consoles], and [disable hardware write protect][hw-wp]. - -[TOC] - -## Overview - -Cr50 CCD was designed to restrict CCD access to device owners and is implemented -through **CCD privilege levels** ([`Open`], [`Unlocked`], [`Locked`]) that can -be used to enable access to different **[CCD capabilities][cap]**. Capability -settings can be modified to require certain privilege levels to access each -capability. Device owners can use these settings to customize CCD so that it is -as open or restricted as they want. - -Cr50 CCD exposes [3 debug consoles][consoles]: AP, EC, and Cr50 as well as -control over [Hardware Write Protect][hw-wp]. Cr50 CCD also allows -[flashing the AP firmware] or [flashing the EC firmware]. - -### Capability and Privilege Levels {#cap-priv} - -Privilege Levels | ----------------- | -`Open` | -`Unlocked` | -`Locked` | - -Capability Setting | Definition ------------------- | ---------- -`IfOpened` | Specified capability is allowed if Cr50 Privilege Level is `Open`. -`UnlessLocked` | Specified capability is allowed unless Cr50 Privilege Level is `Locked`. -`Always` | Specified capability is always allowed, regardless of Cr50 Privilege Level. - -Capability Setting | Privilege Level Required ------------------- | ---------------------------------------- -`IfOpened` | `Open` -`UnlessLocked` | `Open` or `Unlocked` -`Always` | `Open`, `Unlocked`, `Locked` (any state) - -## CCD Capabilities {#cap} - -The default Cr50 privilege level is [`Locked`] with the following capability -settings: - -Capability | Default | Function ------------------ | ---------- | -------- -`UartGscRxAPTx` | `Always` | AP console read access -`UartGscTxAPRx` | `Always` | AP console write access -`UartGscRxECTx` | `Always` | EC console read access -`UartGscTxECRx` | `IfOpened` | EC console write access -[`FlashAP`] | `IfOpened` | Allows flashing the AP -[`FlashEC`] | `IfOpened` | Allows flashing the EC -[`OverrideWP`] | `IfOpened` | Override hardware write protect -`RebootECAP` | `IfOpened` | Allow rebooting the EC/AP from the Cr50 console -`GscFullConsole` | `IfOpened` | Allow access to restricted Cr50 console commands -`UnlockNoReboot` | `Always` | Allow unlocking Cr50 without rebooting the AP -`UnlockNoShortPP` | `Always` | Allow unlocking Cr50 without physical presence -`OpenNoTPMWipe` | `IfOpened` | Allow opening Cr50 without wiping the TPM -`OpenNoLongPP` | `IfOpened` | Allow opening Cr50 without physical presence -`BatteryBypassPP` | `Always` | Allow opening Cr50 without physical presence and developer mode if the battery is removed -`UpdateNoTPMWipe` | `Always` | Allow updating Cr50 without wiping the TPM -`I2C` | `IfOpened` | Allow access to the I2C master (used for measuring power) -`FlashRead` | `Always` | Allow dumping a hash of the AP or EC flash -`OpenNoDevMode` | `IfOpened` | Allow opening Cr50 without developer mode -`OpenFromUSB` | `IfOpened` | Allow opening Cr50 from USB - -## Consoles {#consoles} - -Cr50 presents 3 consoles through CCD: AP, EC, and Cr50, each of which show up on -your host machine as a `/dev/ttyUSBX` device when a debug cable ([Suzy-Q] or -[Type-C Servo v4]) is plugged in to the DUT. - -Console | Default access | Capability Name -------- | ------------------------------------------- | --------------- -Cr50 | always read/write, but commands are limited | `GscFullConsole` enables the full set of Cr50 console commands -AP | read/write | `UartGscRxAPTx` / `UartGscTxAPRx` -EC | read-only | `UartGscRxECTx` / `UartGscTxECRx` - -### Connecting to a Console - -When a debug cable ([Suzy-Q] or [Type-C Servo v4]) is plugged in to the DUT, the -3 consoles will show up as `/dev/ttyUSBX` devices. You can connect to them with -your favorite terminal program (e.g., `minicom`, `screen`, etc). You can also -use the [`usb_console`] command to connect to Cr50 (`18d1:5014`) and specify the -interface to choose between the consoles. - -```bash -# Install `usb_console` -(chroot) sudo emerge ec-devutils -``` - -```bash -# Connect to Cr50 console -(chroot) $ usb_console -d 18d1:5014 -``` - -```bash -# Connect to AP console -(chroot) $ usb_console -d 18d1:5014 -i 1 -``` - -```bash -# Connect to EC console -(chroot) $ usb_console -d 18d1:5014 -i 2 -``` - -#### Using "servod" to access the console - -[`servod`] can be used to create alternative console devices when combined with -a [Servo]. - -First, make sure your [servo firmware is updated][update servo v4]. - -Next, start [`servod`]: - -```bash -(chroot) $ sudo servod -b $BOARD -``` - -Then use `dut-control` to display the console devices: - -```bash -(chroot) $ dut-control cr50_uart_pty ec_uart_pty cpu_uart_pty -``` - -Connect to the console devices with your favorite terminal program (e.g., -`minicom`, `screen`, etc.). - -## CCD Open {#ccd-open} - -Some basic CCD functionality is accessible by default: read-only access to the -EC console, read-write access to the AP console, and a few basic Cr50 console -commands. Note that while Cr50 has read-write access to the AP console by -default, the AP console itself is disabled for production devices. - -In order to access all CCD functionality or to modify capability settings, Cr50 -CCD needs to be [`Open`]. - -1. Connect to the Cr50 console by connecting a [Suzy-Q] or [Type-C Servo v4] to - the DUT and running the following command: - - ```bash - (chroot) $ usb_console -d 18d1:5014 - ``` - - *** note - **NOTE**: If another program is already connected to the Cr50 console, - you'll see `tx [Errno 16] Resource Busy`. For example, this will happen if - [`servod`] is running. - *** - -1. At the Cr50 console, use the `version` command to make sure you have a - recent enough version to use CCD. The relevant version is either `RW_A` or - `RW_B`, whichever has the asterisk next to it: - - ``` - cr50 > version - - Chip: g cr50 B2-C - Board: 0 - RO_A: * 0.0.10/29d77172 - RO_B: 0.0.10/c2a3f8f9 - RW_A: * 0.3.23/cr50_v1.9308_87_mp.320-aa1dd98 <---- This is the version - RW_B: 0.3.18/cr50_v1.9308_87_mp.236-8052858 - BID A: 00000000:00000000:00000000 Yes - BID B: 00000000:00000000:00000000 Yes - Build: 0.3.23/cr50_v1.9308_87_mp.320-aa1dd98 - tpm2:v1.9308_26_0.36-d1631ea - cryptoc:v1.9308_26_0.2-a4a45f5 - 2019-10-14 19:18:05 @chromeos-ci-legacy-us-central2 - ``` - -1. Production (`MP`) versions of Cr50 firmware use a [minor version][semver] of - `3`: `0.3.x`. Production firmware versions `0.3.9` or newer support CCD. - - Development (`PrePVT`) versions of Cr50 firmware use a minor version of - `4`: `0.4.x`. Development firmware versions `0.4.9` or newer support CCD. - - Your device likely supports CCD if it was manufactured in the last few - years. If you have an older version, follow the [Updating Cr50] instructions - before continuing. - -1. Put the device into [Recovery Mode] and enable [Developer Mode]. - - *** note - **NOTE**: Developer Mode has to be enabled as described. Using GBB flags to - force Developer Mode will not work. - *** - - If you can't put your device into [Developer Mode] because it doesn't boot, - follow the [CCD Open Without Booting the Device] instructions. - -1. Verify Cr50 knows the device is in [Developer Mode] by finding `TPM: - dev_mode` in the Cr50 console `ccd` command output: - - ``` - cr50 > ccd - ... - TPM: dev_mode <==== This is the important part - ... - ``` - -1. Start the CCD open process from the AP. - - ```bash - (dut) $ gsctool -a -o - ``` - -1. Over the next 5 minutes you will be prompted to press the power button - multiple times. After the last power button press the device will reboot. - - *** note - **WARNING**: Opening CCD causes Cr50 to forget that it is in - [Developer Mode], so when the device reboots, it will say that the OS - image is invalid. Use the key combinations to enter [Recovery Mode] and - re-enable [Developer Mode]. See [this bug] for details. - *** - -1. Use the `ccd` command on the Cr50 console to verify the state is [`Open`]: - - ``` - cr50 > ccd - - State: Opened - ... - ``` - -1. **The [`Open`] state is lost if Cr50 reboots, the device loses power (e.g., - battery runs out and AC is not plugged in), or the battery is removed. Note - that Cr50 does not reboot when the system reboots; it only reboots if it is - updated, the devices loses power, the battery runs out, or it crashes**. If - you plan on [flashing the AP firmware] or [flashing the EC firmware], it is - recommended you modify the capability settings or set a CCD password, so you - can reopen the device in the case that you accidentally brick it with bad - firmware. The simplest way to do this is to reset to factory settings and - enable testlab mode: - - ``` - cr50 > ccd reset factory - ``` - - ``` - cr50 > ccd testlab enable - ``` - - For full details, see the section on [CCD Open Without Booting the Device]. - -## Configuring CCD Capability Settings - -Cr50 capabilities allow you to configure CCD to restrict or open the device as -much as you want. You can use the `ccd` command on the Cr50 console to check and -modify the capabilities, but CCD has to be [`Open`] to change the capabilities. - -Setting capabilities you want to use to [`Always`] will make them accessible -even if CCD loses the [`Open`] state, which happens when Cr50 reboots or the -device loses power. - -Basic CCD functionality is covered by `UartGscTxECRx`, `UartGscRxECTx`, -`UartGscTxAPRx`, `UartGscRxAPTx`, [`FlashAP`], [`FlashEC`], [`OverrideWP`], and -`GscFullConsole`. - -``` -cr50 > ccd set $CAPABILITY $REQUIREMENT -``` - -### Examples - -#### EC Console - -If the EC console needs to be read-write even when CCD is [`Locked`] set the -capability to [`Always`]: - -``` -cr50 > ccd set UartGscTxECRx Always -``` - -#### Restrict Consoles - -If you want to restrict capabilities more than [`Always`], you can set them to -[`IfOpened`], which will make it so that it is only accessible when CCD is -[`Open`]ed, not [`Lock`]ed: - -##### Restrict EC - -``` -cr50 > ccd set UartGscTxECRx IfOpened -cr50 > ccd set UartGscRxECTx IfOpened -``` - -##### Restrict AP - -``` -cr50 > ccd set UartGscTxAPRx IfOpened -cr50 > ccd set UartGscRxAPTx IfOpened -``` - -#### Most Accessible - -If you want things as accessible as possible and want all capabilities to be -[`Always`], you can run - -``` -cr50 > ccd reset factory -``` - -This will also permanently disable write protect. To reset write protect run - -``` -cr50 > wp follow_batt_pres atboot -``` - -To reset capabilities to Default run - -``` -cr50 > ccd reset -``` - -## Flashing EC {#flashec} - -Flashing the EC is restricted by the `FlashEC` capability. - -The steps to flash the EC differ based on the board being used, but the -[`flash_ec`] script will handle this for you. - -```bash -(chroot) $ sudo servod -b $BOARD -(chroot) $ ~/trunk/src/platform/ec/util/flash_ec -i $IMAGE -b $BOARD -``` - -## Flashing the AP {#flashap} - -*** note -**WARNING**: Before attempting to flash the AP firmware, start with the -[CCD Open] steps; if you flash broken firmware before opening CCD, you may make -it impossible to restore your device to a working state. -*** - -Flashing the AP is restricted by the `FlashAP` capability. - -```bash -(chroot) $ sudo flashrom -p raiden_debug_spi:target=AP -w $IMAGE -``` - -This default flashing command takes a very long time to complete, there are ways -to [speed up the flashing process] by cutting some corners. - -If you have many CCD devices connected, you may want to use the Cr50 serial -number: - -```bash -(chroot) $ lsusb -vd 18d1:5014 | grep iSerial -``` - -You can then add the serial number to the [`flashrom`] command: - -```bash -(chroot) $ sudo flashrom -p raiden_debug_spi:target=AP,serial=$SERIAL -w $IMAGE -``` - -**If you don't see Cr50 print any messages when you're running the [`flashrom`] -command and you have more than one Cr50 device connected to your workstation, -you probably need to use the serial number.** - -### Special Cases {#flashap-special-cases} - -Cr50 puts the device in reset to flash the AP. Due to hardware limitations Cr50 -may not be able to disable hardware write protect while the device is in reset. -If you want to reflash the AP RO firmware using CCD and your board has issues -disabling hardware write protect, you may need to also disable software write -protect. - -To determine if the board you are using has this issue: - -1. Disable write protect using the Cr50 console command: - - ``` - cr50 > wp disable - ``` - -1. Check if hardware write protect disabled when the AP is off: - - ```bash - (chroot) $ sudo flashrom -p raiden_debug_spi:target=AP --wp-status - ``` - -1. If the last command shows that hardware write protect is still enabled when - the AP is off, then you need to disable software write protect: - - ```bash - (chroot) $ flashrom -p host --wp-disable - ``` - -## Control Hardware Write Protect {#hw-wp} - -Control of hardware write protect is restricted by the `OverrideWP` capability. -When the capability is allowed, the hardware write protect setting can be -controlled with the `wp` command in the Cr50 console. Otherwise, the hardware -write protect is determined based on the presence of the battery. - -Hardware Write Protect Setting | Battery State | Hardware Write Protect State ------------------------------- | ------------------------------ | ---------------------------- -`follow_batt_pres` | Connected | Enabled -`follow_batt_pres` | Disconnected | Disabled -`follow_batt_pres` | N/A (Chromebox has no battery) | Write Protect Screw means Enabled -`enabled` | Any | Enabled -`disabled` | Any | Disabled - -### Write Protect Commands - -``` -cr50 > wp [enable|disable|follow_batt_pres] -``` - -There are two write protect settings: the current setting and the `atboot` -setting. - -The `wp` command adjusts the current write protect setting that will last until -Cr50 reboots or loses power. Note that Cr50 does not reboot when the rest of the -system reboots. It will only reboot in the cases where the firmware is being -updated, it crashes, the battery completely drains, the battery is removed, or -power is otherwise lost. - -The `atboot` setting is the state of the write protect when Cr50 boots; it -defaults to `follow_batt_pres`. - -To change the `atboot` setting, add the `atboot` arg to the `wp` command: - -``` -cr50 > wp atboot [enable|disable|follow_batt_pres] -``` - -You can query the write protect state with `gsctool`: - -```bash -(dut) $ gsctool -a -w - -... -Flash WP: forced disabled <-- Current hardware write protect state - at boot: forced disabled <-- "atboot" hardware write protect state - -``` - -`gsctool -a -w` Status | Hardware Write Protect State ----------------------- | ------------------------------------ -`forced disabled` | Disabled -`forced enabled` | Enabled -`enabled` | Enabled, following battery presence -`disabled` | Disabled, following battery presence - -### Special Case Devices - -Bob devices have a write protect screw in addition to battery presence. The -write protect screw will force enable write protect until it's removed. If Cr50 -is set to `follow_batt_pres`, you need to remove the write protect screw and -disconnect the battery to disable write protect. If you run `wp disable`, you -will also need to remove the screw. - -If you are attempting to flash the AP, see the [Flashing the AP Special Cases] -section for additional steps you may have to take to disable write protection. - -## UART Rescue mode - -### Overview - -UART Rescue Mode is a feature of the Cr50 RO firmware that supports programming -the RW firmware using only the UART interface. This is used to recover a bad RW -firmware update (which should be rare). - -This is also useful when bringing up new designs, as this allows to update Cr50 -image even before USB CCD or TPM interfaces are operational. - -UART rescue works on all existing devices, all it requires is that Cr50 console -is mapped to a `/dev/xxx` device on the workstation (the same device used to -attach a terminal to the console). - -Rescue works as follows: when the RO starts, after printing the regular banner -on the console it prints a magic string to the console and momentarily waits for -the host to send a sync symbol, to indicate that an alternative RW will have to -be loaded over UART. The RO also enters this mode if there is no valid RW to -run. - -When rescue mode is triggered, the RO is expecting the host to transfer a single -RW image in hex format. - -### Install the cr50-rescue utility - -The `cr50-rescue` utility is used to flash a given firmware to Cr50 using rescue -mode. This tool must be installed inside the chroot. - -```bash -(chroot) $ sudo emerge cr50-utils -``` - -### Preparing an RW image - -To prepare the signed hex RW image, fetch a released image from Google storage, -which can be found by running: - -```bash -(chroot) $ gsutil ls gs://chromeos-localmirror/distfiles/cr50* -``` - -(depending on your setup you might have to do this inside chroot). Copy the -image you want to use for rescue to your workstation and extract cr50.bin.prod -from the tarball. - -The latest Cr50 images can be found in the [chromeos-cr50 ebuild]. Generally, -you should always use the PROD_IMAGE indicated in that file. Once rescued, the -user can update to the PREPVT image later if needed. - -Once the binary image is ready, use the following commands to carve out the RW A -section out of it and convert it into hex format: - -```bash -(chroot) $ dd if=<cr50 bin file> of=cr50.rw.bin skip=16384 count=233472 bs=1 -objcopy -I binary -O ihex --change-addresses 0x44000 cr50.rw.bin cr50.rw.hex -``` - -then you can use `cr50.rw.hex` as the image passed to `cr50-rescue`. - -### Programming the RW image with rescue mode - -With servo_micro (or servo_v2 reworked for connecting to Cr50 console), run -[`servod`] and disable Cr50 ec3po and UART timestamp: - -```bash -(chroot) $ dut-control cr50_uart_timestamp:off dut-control cr50_ec3po_interp_connect:off -``` - -Get a raw Cr50 UART device path and use it for `cr50-rescue` argument `-d` -below. - -```bash -(chroot) $ dut-control raw_cr50_uart_pty -``` - -Prior to running `cr50-rescue`, the terminal from the Cr50 console UART must be -disconnected, and Cr50 must be unpowered-- the system needs to have AC power and -battery disconnected. - -After ensuring those steps, the rescue command may be run as follows: - -```bash -(chroot) $ cr50-rescue -v -i <path to the signed hex RW image> -d <cr50 console UART tty> -``` - -After starting the command, provide power to the board and rescue mode will -start automatically. After flashing successfully (see sample output below), Cr50 -must be unpowered again, by disconnecting AC power and battery. - -Note that `<cr50 console UART tty>` above has to be a direct FTDI interface, -`pty` devices created by [`servod`] do not work for this purpose. Use either -servo-micro or a USB/UART cable. Note that multifunctional *SPI-UART/FTDI/USB -cables might not work*, as they impose a significant delay in the UART stream, -which makes the synchronization described below impossible. - -`cr50-rescue` starts listening on the console UART and printing it out to the -terminal. When the target is reset, `cr50-rescue` detects the `Bldr |` string in -the target output, at this point the utility intercepts the boot process and the -target proceeds to receiving the new RW image and saving it into flash. Note the -currently present RW and RW_B images will be wiped out first. - -#### Sample output - -```bash -(chroot) $ cr50-rescue -v -i cr50.3.24.rw.hex -d /dev/pts/0 - -low 00044000, high 0007cfff -base 00044000, size 00039000 -..startAdr 00000000 -..maxAdr 0x0003d000 -..dropped to 0x0003a188 -..skipping from 0x00000000 to 0x00004000 -226 frames -(waiting for "Bldr |") -Havn2|00000000_000000@0 -exp ?36 -Himg =2CD687F2B1579ED1E85C7F35055550A63B9B146E2CAC808295C59F97849F08E7 -Hfss =184D83B3D89599C90E4852EF16F9FAEEEED07BC0AFDF1028136AA3C9F71D4F43 -Hinf =44D21600B3723BDB0DCB9E0891E9F7373FC1BDE69598C9D7F04B1ABEB70529BD -exp ?40 -exp ?48 -exp ?67 -jump @00080400 - -Bldr |(waiting for "oops?|")1527394 -retry|0 -oops?|0.1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21.22.23.24.25.26.27.28.29.30.31.32.33.34.35.36.37.38.39.40.41.42.43.44.45.46.47.48.49.50.51.52.53.54.55.56.57.58.59.60.61.62.63.64.65.66.67.68.69.70.71.72.73.74.75.76.77.78.79.80.81.82.83.84.85.86.87.88.89.90.91.92.93.94.95.96.97.98.99.100.101.102.103.104.105.106.107.108.109.110.111.112.113.114.115.116.117.118.119.120.121.122.123.124.125.126.127.128.129.130.131.132.133.134.135.136.137.138.139.140.141.142.143.144.145.146.147.148.149.150.151.152.153.154.155.156.157.158.159.160.161.162.163.164.165.166.167.168.169.170.171.172.173.174.175.176.177.178.179.180.181.182.183.184.185.186.187.188.189.190.191.192.193.194.195.196.197.198.199.200.201.202.203.204.205.206.207.208.209.210.211.212.213.214.215.216.217.218.219.220.221.222.223.224.225.done! -``` - -## CCD Open Without Booting the Device {#ccd-open-no-boot} - -If you can’t boot your device, you won’t be able to enable [Developer Mode] to -send the open command from the AP. If you have enabled CCD on the device before, -Cr50 may be configured in a way that you can still open Cr50. - -### Option 1: Remove the battery - -If you can remove the battery, you can bypass the [Developer Mode] requirements. -`ccd open` is allowed from the Cr50 console if the Chrome OS Firmware Management -Parameters (`FWMP`) do not disable CCD and the battery is disconnected. This is -the most universal method and will work even if you haven’t enabled CCD before. - -1. Disconnect the battery - -1. Send `ccd open` from the Cr50 console. - -### Option 2: "OpenNoDevMode" and "OpenFromUSB" are set to Always - -If "OpenNoDevMode" and "OpenFromUSB" are set to Always, you will be able to open -Cr50 from the Cr50 console without enabling [Developer Mode]: - -``` -cr50 > ccd open -``` - -You will still need physical presence (i.e., press the power button) unless -`testlab` mode is also enabled: - -``` -cr50 > ccd testlab - CCD test lab mode enabled -``` - -#### Enabling - -If CCD is [`Open`], you can enable these settings with: - -``` -cr50 > ccd set OpenFromUSB Always -cr50 > ccd set OpenNoDevMode Always -``` - -### Option 3: CCD Password is Set - -If the CCD password is set, you can open from the Cr50 console without -[Developer Mode]. - -``` -cr50 > ccd open $PASSWORD -cr50 > ccd unlock $PASSWORD -``` - -Alternatively, you can use `gsctool`, entering the password when prompted: - -``` -(dut) $ gsctool -a -o -(dut) $ gsctool -a -u -``` - -#### Enabling - -When CCD is [`Open`], run the `gsctool` command and enter the password when -prompted. - -```bash -(chroot) $ gsctool -a -P -``` - -You can use the CCD command on the Cr50 console to check if the password is set. - -``` -cr50 > ccd - ... - Password: [none|set] - ... -``` - -#### Disabling - -When CCD is [`Open`], you can use `gsctool` to clear the password: - -```bash -(dut) $ gsctool -a -P clear:$PASSWORD -``` - -Alternatively, you can use the Cr50 console to clear the password and reset CCD -capabilities to their default values: - -``` -cr50 > ccd reset -``` - -## Troubleshooting - -### rddkeepalive - -Cr50 only enables CCD when it detects a debug accessory is connected (e.g., -[Suzy-Q] or [Type-C Servo v4]). It detects the cable based on the voltages on -the CC lines. If you are flashing the EC and AP or working with unstable -hardware, these CC voltages may become unreliable for detecting a debug -accessory. - -To work around this, you can force Cr50 to always assume that a debug cable is -detected: - -``` -cr50 > rddkeepalive enable -``` - -*** note -**NOTE**: Enabling `rddkeepalive` does increase power consumption. -*** - -To disable: - -``` -cr50 > rddkeepalive disable -``` - -### Updating Cr50 {#updating-cr50} - -Production (`MP`) versions of Cr50 firmware use a [minor version][semver] of -`3`: `0.3.x`. Production firmware versions `0.3.9` or newer support CCD. - -Development (`PrePVT`) versions of Cr50 firmware use a minor version of `4`: -`0.4.x`. Development firmware versions `0.4.9` or newer support CCD. - -There aren't many differences between the MP and PrePVT versions of images, but -it is a little easier to CCD [`Open`] PrePVT images. You can't run PrePVT images -on MP devices, so if you're trying to update to PrePVT and it fails try using -the MP image. - -1. Flash a test image newer than M66. - -1. Enable [Developer Mode] and connect a debug cable ([`Suzy-Q`] or [`Type-C - Servo v4`]). - -1. Check the running Cr50 version with `gsctool`: - -```bash -(dut) $ sudo gsctool -a -f - -... -RW 0.4.26 <-- The "RW" version is the one to check -``` - -1. Update Cr50 using the firmware in the OS image: - -*Production (MP) image*: - -```bash -(dut) $ sudo gsctool -a /opt/google/cr50/firmware/cr50.bin.prod -``` - -*Development (PrePVT) image*: - -```bash -(dut) $ sudo gsctool -a /opt/google/cr50/firmware/cr50.bin.prepvt -``` - -1. Check the Cr50 version again to make sure it's either `0.3.X` or `0.4.X`. - -### Speed up Flashing the AP {#speed-up-ap-flash} - -In the [default AP flashing steps][flashap] [`flashrom`] reads the entire flash -contents and only erases and programs the pages that have to be modified. -However, when Cr50 controls the SPI bus, it can only run at 1.5 MHz, versus the -50 MHz that the AP normally runs it at. - -We can take advantage of the fact that Chrome OS device AP firmware is split -into sections, only a few of which are essential for maintaining the device -identity and for booting the device in recovery mode to program faster by only -reading and writing sections we care about: - -```bash -# This will save device flash map and VPD sections in -# /tmp/bios.essentials.bin. VPD sections contain information like device -# firmware ID, WiFi calibration, enrollment status, etc. Use the below command -# only if you need to preserve the DUT's identity, no need to run it in case -# the DUT flash is not programmed at all, or you do not care about preserving -# the device identity. -sudo flashrom -p raiden_debug_spi:target=AP -i FMAP -i RO_VPD -i RW_VPD -r /tmp/bios.essentials.bin --fast-verify - -# This command will erase the entire flash chip in one shot, the fastest -# possible way to erase. -sudo flashrom -p raiden_debug_spi:target=AP -E --do-not-diff - -# This command will program essential flash sections necessary for the -# Chrome OS device to boot in recovery mode. Note that the SI_ALL section is -# not always present in the flash image, do not include it if it is not in -# dump_fmap output. -sudo flashrom -p raiden_debug_spi:target=AP -w image-atlas.bin -i FMAP -i WP_RO [-i SI_ALL] --do-not-diff --noverify - -# This command will restore the previously preserved VPD sections of the -# flash, provided it was saved in the first step above. -sudo flashrom -p raiden_debug_spi:target=AP -w /tmp/bios.essential.bin -i RO_VPD -i RW_VPD --do-not-diff --noverify -``` - -Once flash is programmed, the device can be booted in recovery mode and start -Chrome OS from external storage, following the usual recovery procedure. Once -Chrome OS is installed, AP flash can be updated to include the rest of the image -by running [`flashrom`] or `futility` from the device bash prompt. - -[Case Closed Debugging]: ./case_closed_debugging.md -[chromeos-cr50 ebuild]: https://chromium.googlesource.com/chromiumos/overlays/chromiumos-overlay/+/refs/heads/master/chromeos-base/chromeos-cr50/chromeos-cr50-0.0.1.ebuild -[Developer Mode]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_mode.md#dev-mode -[Recovery Mode]: https://chromium.googlesource.com/chromiumos/docs/+/master/debug_buttons.md -[Servo]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/servo.md -[`servod`]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/servo.md -[Type-C Servo v4]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/servo_v4.md -[update servo v4]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/servo_v4.md#updating-firmware -[Suzy-Q]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/ccd.md#SuzyQ-SuzyQable -[`hdctools`]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/master/README.md -[`FlashAP`]: #flashap -[flashing the AP firmware]: #flashap -[flashap]: #flashap -[Flashing the AP Special Cases]: #flashap-special-cases -[`FlashEC`]: #flashec -[flashing the EC firmware]: #flashec -[`OverrideWP`]: #hw-wp -[`Always`]: #cap-priv -[`IfOpened`]: #cap-priv -[`Open`]: #cap-priv -[`Locked`]: #cap-priv -[`Unlocked`]: #cap-priv -[Updating Cr50]: #updating-cr50 -[CCD Open Without Booting the Device]: #ccd-open-no-boot -[cap]: #cap -[consoles]: #consoles -[hw-wp]: #hw-wp -[`flash_ec`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/util/flash_ec -[CCD Open]: #ccd-open -[`flashrom`]: https://chromium.googlesource.com/chromiumos/third_party/flashrom/+/master/README.chromiumos -[speed up the flashing process]: #speed-up-ap-flash -[this bug]: https://issuetracker.google.com/149420712 -[semver]: https://semver.org/ -[`usb_console`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/extra/usb_serial/console.py +The has been moved into a [different +branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md) diff --git a/docs/ccd_howtos.md b/docs/ccd_howtos.md index 93d272e1b5..624253d22c 100644 --- a/docs/ccd_howtos.md +++ b/docs/ccd_howtos.md @@ -1,384 +1,2 @@ -# CCD How-tos -This doc contains tutorials for using CCD. These tutorials only cover using GSC -CCD. Some use cases will be very similar to using CCD from ryu, servo micro, or -servo v4, but these guides are not guaranteed to work for them. More detailed -instructions on how to use different parts of CCD are in the -[GSC CCD doc](case_closed_debugging_cr50.md). - -[TOC] - ---- -## How to Use SuzyQ -This goes through the steps to connect SuzyQ and start using CCD. - -### Requirements - -* A [SuzyQ]. If you don't have one, they're sold at [sparkfun] -* A ChromeOS device that supports CCD. - -### Steps - -1. **Charge your chromebook.** Suzyq can't charge your device. If it's not - charged, the device may run out of power while debugging. - -2. **Connect the type A side of Suzyq to your workstation.** - -3. **Connect the type C part of your Suzyq to your chromebook.** - -4. **Verify the CCD device exists.** - - * **Look for a device with the right vid:pid.** Cr50 vid:pid is 18d1:5014. - You can use lsusb to check that it shows up. - - > lsusb -vd 18d1:5014 - - * **Debug connection issues**. If the device doesn't show up, disconnect - suzyq from the DUT and either flip it or plug it into the other port. If - your device has 2 type c ports, there are 4 ways to connect suzyq. Only - one works. - - * **Port:** The DUT only supports CCD on one type C port. Try the - other port if CCD doesn't show up. - - * **Orientation:** Suzyq is orientation dependent, so it may be on the - correct port, but it needs to be flipped. - -5. **Check basic CCD functionality**. After the CCD device shows up, the cr50, ec, - and ap consoles should show up in /dev/ttyUSB\* - - * Search for console names. - - > ls /dev/ttyUSB* - - * If you run the `ls` command before and after connecting suzyq, then the - new devices should be the CCD consoles. The consoles are ordered. Cr50 - should be the lowest ttyUSB device, then AP, and EC should have the - highest number. Running `ver` on all of them could also let you know - which one is which if you don't want to remember the order. - - * Open the console. - - > minicom -D /dev/ttyUSB0 - - * AP and EC consoles may be read-only depending on the CCD state. See the - [Setup CCD] instructions to enable them. Being able to use the cr50 - console is a good enough sign that your Suzyq setup is ok. - ---- -## Setup CCD for FAFT - -These are the most generic instructions. - -There are other ways to open ccd that may be faster, but they don't work for all -devices. You can see the other open methods in the ccd setup doc to find other -ways if this way doesn't work for you. - -The entering dev mode instructions will be for clamshell devices. If your device -is not a clamshell, check out the [full dev mode instructions]. - -#### Requirements - -* A [Type-C Servo V4]. FAFT needs the ethernet and usb key to run. You can't - run with suzyq. -* A micro usb cable. -* A chromeos PD charger. -* A ChromeOS device that supports CCD. -* Access to the AP console. -* The device needs to be able to boot. -* The GBB\_FLAG\_FORCE\_DEV\_SWITCH\_ON GBB flag is cleared. - -### Steps - - -1. **Charge your chromebook.** Servo V4 can charge your device, but it's good - to charge it before setting up ccd. Servo v4 may encounter different issues - if your device isn't charged. - -2. **Connect the type A side of the micro usb cable to your workstation.** - -3. **Connect the micro usb of your cable to "HOST" port of servo v4.** - -4. **Update Servo V4 from the chroot.** - - chroot > sudo emerge servo-firmware - chroot > sudo servo_updater -b servo_v4 - -5. **Connect the PD charger to the "DUT POWER" port of servo v4.** - -6. **Connect the type C part of the Servo V4 to your chromebook.** The DUT - should now be charging through servo v4. Check that the green light in - the corner of servo v4 lights up. - -7. **Verify the CCD device exists.** - - * **Look for a device with the right vid:pid.** Cr50 vid:pid is 18d1:5014. - You can use lsusb to check that it shows up. - - > lsusb -vd 18d1:5014 - - * **Debug connection issues**. - - * **Port:** The DUT only supports CCD on one type C port. Try the - other port if CCD doesn't show up. - - * **Orientation:** Orientation shouldn't matter with Servo V4. If it - does, please file a bug. - - * **Charge State:** Make sure the the green light in the corner of - servo v4 is lit. - -8. **Connect to the Cr50 console**. After the CCD device shows up, the cr50, ec, - and ap consoles should show up in /dev/ttyUSB\* - - * Search for console names. - - > ls /dev/ttyUSB* - - * If you run the `ls` command before and after connecting the Servo V4 - type C cable to the DUT, then the new devices should be the CCD - consoles. The consoles are ordered. Cr50 should be the lowest ttyUSB - device, then AP, and EC should have the highest number. Running `ver` - on all of them could also let you know which one is which if you don't - want to remember the order. - **Servo V4 has it's own console. It might be useful to do this step to - find the device consoles** - - * Open the console. - - > minicom -D /dev/ttyUSB1 - - * Make sure `version` shows some version information. - -9. **Open CCD.** Here's the most generic way to open ccd. For the full open - options see [Setup CCD]. - - * **[Enter dev mode](case_closed_debugging_cr50.md#enter-dev-mode).** - These are clamshell instructions for other types of chromeOS devices - refer to the full setup doc. - - * Boot into recovery by pressing the power button, refresh, and - escape. - - * At the recovery screen press Ctrl+D and enter. - - * **Use gsctool to open Cr50 from the AP. Press the power button when - prompted.** This will take ~5 minutes. - - AP > gsctool -a -o - -10. **Set all capabilities to Always** and confirm they're Always. - - cr50 > ccd reset factory - cr50 > ccd - -11. **Enable Testlab Mode.** Tap the power button when prompted. This will - take a couple of seconds. - - cr50 > ccd testlab enable - - -12. **Start servod and make sure the EC console works.** - - - * enter chroot with `cros_sdk --no-ns-pid` - - * start servod - - chroot > sudo servod -b $BOARD - - * Check EC uart works. - - chroot > dut-control ec_board - -13. **Try running a test** Use autotest_dir, so you don't need to about what - autotest packages to emerge. firmware_ECHash is just a short test. If your - board doesn't have an EC, try something else. Use firmware_FAFTSetup to - verify the setup will work with faft-ec and faft-bios. - - chroot > test_that $IP --autotest_dir \ - ~/trunk/src/third_party/autotest/files/ firmware_ECHash - -14. **Debug Setup** - - - * **Cr50 capabilities:** EC uart capability needs to always be accessible. - **Make sure UartGscTxECRx and all other capabilities are always.** - - cr50 > ccd - - * **Make sure servod started using the CCD device**. Verify the ccd - serialname has the right format. Cr50 serialname should have the - format [0-9a-f]{8}-[0-9a-f]{8} - - chroot > dut-control ccd_serialname - - If the control doesn't exist or the serianame is wrong try to find - ccd serialname and start servod explicitly selecting it. - - find serialname and use it to restart servod. - - chroot > lsusb -vd 18d1:5014 | grep iSerial - chroot > sudo servod -b $BOARD -s $SERIALNAME - - -### Final Checks - - * All capabilities are Always - - cr50 > ccd - - * Testlab mode is enabled - - cr50 > ccd testlab - - * EC uart works - - chroot > dut-control ec_board ---- -## I Just Want to Disable Write Protect -Cr50 has a couple of ways to remove write protect. The biggest difference in the -process is whether or not you want to open the case and whether or not you need -write protect disable to be permanent. - -**Opening CCD might require the AP can boot. If you're relying on CCD to recover -a bricked machine, you may want to do the optional CCD setup steps before -flashing RO firmware.** - -### Process if You're Okay Opening Case -Cr50 will disable write protect if you remove the battery. - -#### Steps - -1. **Open the Case.** - -2. **Remove the battery.** Cr50 disables write protect when the battery is - disconnected. On chromeboxes you need to remove the write protect screw. - -3. (bob only) remove the write protect screw. Bob uses cr50 and a write protect - screw. Cr50 has to disable write protect and the screw has to be removed for - write protect to be disabled. - -4. (optional) Check write protect is disabled from the AP. - - AP > flashrom --wp-status - -5. (optional) Reconnecting the battery will reenable write protect. You can - disable SW write protect if you want to be able to rewrite RO firmware - without needing to keep the battery disconnected. - - AP > flashrom -p host --wp-disable - -6. **(recommended) Run some basic commands to setup CCD.** It's really easy to - open cr50 with the battery removed. You might want to setup CCD while you - already have the case open and the battery is disconnected. Doing these - extra CCD setup steps may make it easier to recover a bricked device using - CCD. These will require SuzyQ. - - * **Open Cr50** from the AP or Cr50 console. This will happen immediately. - - - AP > gsctool -a -o - - or - - Cr50 > ccd open - - - - * **Setup capabilities.** This can only be done from the Cr50 console. - - Enable flashing the AP/EC CCD open. - - Cr50 > ccd set OverrideWP Always - Cr50 > ccd set FlashAP Always - Cr50 > ccd set FlashEC Always - - Enable opening Cr50 without booting the AP. - - Cr50 > ccd set OpenNoDevMode Always - Cr50 > ccd set OpenFromUSB Always - -### Process With Case Closed -Full instructions are at [Setup CCD], but here are are the basic steps. If -you're unsure about a step here you should take a look at the [Setup CCD] doc. -It goes into a lot more detail. - -#### Requirements - -* A [SuzyQ]. Cr50 console access is required to disable write protect. -* The device needs to be able to boot. -* The GBB\_FLAG\_FORCE\_DEV\_SWITCH\_ON GBB flag is cleared. - -#### Steps -1. **Open CCD.** Here's the most generic way to open ccd. For the full open - options see [Setup CCD]. - - * **[Enter dev mode](case_closed_debugging_cr50.md#enter-dev-mode).** - These are clamshell instructions for other types of chromeOS devices - refer to the full setup doc. - - * Boot into recovery by pressing the power button, refresh, and - escape. - - * At the recovery screen press Ctrl+D and enter. - - * **Use gsctool to open Cr50 from the AP.** Press the power button when - prompted. This will take ~5 minutes. - - AP > gsctool -a -o - -2. **[Connect](#How-to-Use-SuzyQ) to the Cr50 console** using SuzyQ or servo - v4. - - > minicom -D /dev/ttyUSB0 - -3. **Disable write protect** using Cr50 [wp console command]. - - cmd to disable until cr50 reboots: - - cr50 > wp disable - - cmd to disable it indefinitely: - - cr50 > wp disable atboot - - -4. (optional) Check write protect is disabled. ccd open takes the AP out of dev - mode, so you can reenter dev mode and check the wp status from the AP or you - can use ccd to check. - - From AP (after reentering dev mode): - - AP > flashrom --wp-status - - Using CCD: - - from chroot > flashrom -p raiden_debug_spi:target=AP --wp-status - -5. **(recommended) Setup capabilities**, so you can flash the device or open - ccd without being able to boot the AP. - - Make flashing the AP/EC accessible without opening CCD - - Cr50 > ccd set OverrideWP Always - Cr50 > ccd set FlashAP Always - Cr50 > ccd set FlashEC Always - - Enable opening Cr50 without booting the AP - - Cr50 > ccd set OpenNoDevMode Always - Cr50 > ccd set OpenFromUSB Always - -6. **(recommended) [Disable SW WP]** to flash RO firmware if your board has - issues disabling HW WP with the AP off. - - AP > flashrom -p host --wp-disable - -[Disable SW WP]: ./case_closed_debugging_cr50.md#AP-Off -[enter dev mode]: ./case_closed_debugging_cr50.md#enter-dev-mode -[sparkfun]: https://www.sparkfun.com/products/14746 -[Setup CCD]: ./case_closed_debugging_cr50.md#CCD-Setup -[SuzyQ]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/master/docs/ccd.md#suzyq-suzyqable -[Type-C Servo V4]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/master/docs/servo_v4.md -[wp console command]: ./case_closed_debugging_cr50.md#WP-control - +The has been moved into a [different +branch](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/ccd_howtos.md) diff --git a/docs/fingerprint/fingerprint-authentication-design-doc.md b/docs/fingerprint/fingerprint-authentication-design-doc.md index 225d8e8a45..7103239822 100644 --- a/docs/fingerprint/fingerprint-authentication-design-doc.md +++ b/docs/fingerprint/fingerprint-authentication-design-doc.md @@ -716,7 +716,7 @@ The log file is `/var/log/cros_fp.log`. [AuthSession]: https://chromium.googlesource.com/chromiumos/platform2/+/eae39a9ad1239f8fbfa8164255578b306ff6ba5c/biod/biometrics_manager.h#96 [biod D-Bus API]: https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/master/system_api/dbus/biod/ [biod upstart script]: https://chromium.googlesource.com/chromiumos/platform2/+/master/biod/init/biod.conf -[ccd open]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/docs/case_closed_debugging_cr50.md#Open-CCD +[ccd open]: https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md#Open-CCD [CDD]: https://source.android.com/compatibility/android-cdd#7_3_10_fingerprint_sensor [Chromium OS EC]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/README.md [clobber-state]: https://chromium.googlesource.com/chromiumos/platform2/+/962ab1bc481db0cf504b5449eb3a3d5008ea7601/init/clobber_state.cc#475 diff --git a/docs/usb-c.md b/docs/usb-c.md index c47d62b4f0..1549b2abcc 100644 --- a/docs/usb-c.md +++ b/docs/usb-c.md @@ -7,8 +7,7 @@ different modes. This includes but isn't limited to: power up to 100W (if supported by device). * Reversed cable mode. This requires a mux to switch the signals before getting to the SoC (or AP). -* Debug accessory mode, e.g. - [Case Closed Debugging (CCD)](case_closed_debugging_cr50.md) +* Debug accessory mode, e.g. [Case Closed Debugging (CCD)] * Multiple uses for the 4 differential pair signals including * USB SuperSpeed mode (up to 4 lanes for USB data) * DisplayPort Alternate Mode (up to 4 lanes for DisplayPort data) @@ -209,8 +208,9 @@ TODO(https://crbug.com/974302): mention `USB_CHG_P#` and `CHARGER` TODO(https://crbug.com/974302): Mention how this works even though it is in depthcharge. Probing now. Need new driver in depthcharge -[USB PD Spec Id]: https://www.usb.org/document-library/usb-power-delivery +[Case Closed Debugging (CCD)]: https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md [Introduction to USB Power Delivery]: https://www.microchip.com/wwwAppNotes/AppNotes.aspx?appnote=en575003 -[USB TCPM Spec Id]: https://www.usb.org/document-library/usb-type-ctm-port-controller-interface-specification +[USB PD Spec Id]: https://www.usb.org/document-library/usb-power-delivery [USB TC Spec Id]: https://www.usb.org/document-library/usb-type-cr-cable-and-connector-specification-revision-20-august-2019 +[USB TCPM Spec Id]: https://www.usb.org/document-library/usb-type-ctm-port-controller-interface-specification [config header link]: ../include/config.h diff --git a/docs/write_protection.md b/docs/write_protection.md index e57f71045a..00e384ee16 100644 --- a/docs/write_protection.md +++ b/docs/write_protection.md @@ -292,10 +292,10 @@ https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1222094 The EC code command handlers (`command_flash_erase`, `command_flash_write`, etc.) return an error if `EC_FLASH_PROTECT_ALL_NOW` is set. -[write_protect_gpio]: https://chromium.googlesource.com/chromiumos/platform/ec/+/aaba1d5efd51082d143ce2ac64e6caf9cb14d5e5/include/ec_commands.h#1599 -["CCD open"]: ./case_closed_debugging_cr50.md#Open-CCD -[Cr50 console]: ./case_closed_debugging_cr50.md#Consoles -[`OverrideWP`]: ./case_closed_debugging_cr50.md -[wp_screw]: https://www.chromium.org/chromium-os/firmware-porting-guide/firmware-ec-write-protection -[`system_is_locked()`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/aaba1d5efd51082d143ce2ac64e6caf9cb14d5e5/common/system.c#195 +["CCD open"]: https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md#Open-CCD +[Cr50 console]: https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md#Consoles [Servo]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/master/README.md +[`OverrideWP`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md +[`system_is_locked()`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/aaba1d5efd51082d143ce2ac64e6caf9cb14d5e5/common/system.c#195 +[wp_screw]: https://www.chromium.org/chromium-os/firmware-porting-guide/firmware-ec-write-protection +[write_protect_gpio]: https://chromium.googlesource.com/chromiumos/platform/ec/+/aaba1d5efd51082d143ce2ac64e6caf9cb14d5e5/include/ec_commands.h#1599 |