| # 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_gsc.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_gsc.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 HW Write Protect |
| Cr50 has a couple of ways to remove HW 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 HW 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 > crossystem wpsw_cur |
| |
| 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 > futility flash --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_gsc.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 HW WP is disabled. ccd open takes the AP out of dev |
| mode, so you can reenter dev mode and check the HW WP status from the AP. |
| |
| From AP (after reentering dev mode): |
| |
| AP > crossystem wpsw_cur |
| |
| |
| 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 > futility flash --wp-disable |
| |
| [Disable SW WP]: ./case_closed_debugging_gsc.md#AP-Off |
| [enter dev mode]: ./case_closed_debugging_gsc.md#enter-dev-mode |
| [sparkfun]: https://www.sparkfun.com/products/14746 |
| [Setup CCD]: ./case_closed_debugging_gsc.md#CCD-Setup |
| [SuzyQ]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/main/docs/ccd.md#suzyq-suzyqable |
| [Type-C Servo V4]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/main/docs/servo_v4.md |
| [wp console command]: ./case_closed_debugging_gsc.md#WP-control |
| |
