1# CCD How-tos 2This doc contains tutorials for using CCD. These tutorials only cover using GSC 3CCD. Some use cases will be very similar to using CCD from ryu, servo micro, or 4servo v4, but these guides are not guaranteed to work for them. More detailed 5instructions on how to use different parts of CCD are in the 6[GSC CCD doc](case_closed_debugging_gsc.md). 7 8[TOC] 9 10--- 11## How to Use SuzyQ 12This goes through the steps to connect SuzyQ and start using CCD. 13 14### Requirements 15 16* A [SuzyQ]. If you don't have one, they're sold at [sparkfun] 17* A ChromeOS device that supports CCD. 18 19### Steps 20 211. **Charge your chromebook.** Suzyq can't charge your device. If it's not 22 charged, the device may run out of power while debugging. 23 242. **Connect the type A side of Suzyq to your workstation.** 25 263. **Connect the type C part of your Suzyq to your chromebook.** 27 284. **Verify the CCD device exists.** 29 30 * **Look for a device with the right vid:pid.** Cr50 vid:pid is 18d1:5014. 31 You can use lsusb to check that it shows up. 32 33 > lsusb -vd 18d1:5014 34 35 * **Debug connection issues**. If the device doesn't show up, disconnect 36 suzyq from the DUT and either flip it or plug it into the other port. If 37 your device has 2 type c ports, there are 4 ways to connect suzyq. Only 38 one works. 39 40 * **Port:** The DUT only supports CCD on one type C port. Try the 41 other port if CCD doesn't show up. 42 43 * **Orientation:** Suzyq is orientation dependent, so it may be on the 44 correct port, but it needs to be flipped. 45 465. **Check basic CCD functionality**. After the CCD device shows up, the cr50, ec, 47 and ap consoles should show up in /dev/ttyUSB\* 48 49 * Search for console names. 50 51 > ls /dev/ttyUSB* 52 53 * If you run the `ls` command before and after connecting suzyq, then the 54 new devices should be the CCD consoles. The consoles are ordered. Cr50 55 should be the lowest ttyUSB device, then AP, and EC should have the 56 highest number. Running `ver` on all of them could also let you know 57 which one is which if you don't want to remember the order. 58 59 * Open the console. 60 61 > minicom -D /dev/ttyUSB0 62 63 * AP and EC consoles may be read-only depending on the CCD state. See the 64 [Setup CCD] instructions to enable them. Being able to use the cr50 65 console is a good enough sign that your Suzyq setup is ok. 66 67--- 68## Setup CCD for FAFT 69 70These are the most generic instructions. 71 72There are other ways to open ccd that may be faster, but they don't work for all 73devices. You can see the other open methods in the ccd setup doc to find other 74ways if this way doesn't work for you. 75 76The entering dev mode instructions will be for clamshell devices. If your device 77is not a clamshell, check out the [full dev mode instructions]. 78 79#### Requirements 80 81* A [Type-C Servo V4]. FAFT needs the ethernet and usb key to run. You can't 82 run with suzyq. 83* A micro usb cable. 84* A chromeos PD charger. 85* A ChromeOS device that supports CCD. 86* Access to the AP console. 87* The device needs to be able to boot. 88* The GBB\_FLAG\_FORCE\_DEV\_SWITCH\_ON GBB flag is cleared. 89 90### Steps 91 92 931. **Charge your chromebook.** Servo V4 can charge your device, but it's good 94 to charge it before setting up ccd. Servo v4 may encounter different issues 95 if your device isn't charged. 96 972. **Connect the type A side of the micro usb cable to your workstation.** 98 993. **Connect the micro usb of your cable to "HOST" port of servo v4.** 100 1014. **Update Servo V4 from the chroot.** 102 103 chroot > sudo emerge servo-firmware 104 chroot > sudo servo_updater -b servo_v4 105 1065. **Connect the PD charger to the "DUT POWER" port of servo v4.** 107 1086. **Connect the type C part of the Servo V4 to your chromebook.** The DUT 109 should now be charging through servo v4. Check that the green light in 110 the corner of servo v4 lights up. 111 1127. **Verify the CCD device exists.** 113 114 * **Look for a device with the right vid:pid.** Cr50 vid:pid is 18d1:5014. 115 You can use lsusb to check that it shows up. 116 117 > lsusb -vd 18d1:5014 118 119 * **Debug connection issues**. 120 121 * **Port:** The DUT only supports CCD on one type C port. Try the 122 other port if CCD doesn't show up. 123 124 * **Orientation:** Orientation shouldn't matter with Servo V4. If it 125 does, please file a bug. 126 127 * **Charge State:** Make sure the the green light in the corner of 128 servo v4 is lit. 129 1308. **Connect to the Cr50 console**. After the CCD device shows up, the cr50, ec, 131 and ap consoles should show up in /dev/ttyUSB\* 132 133 * Search for console names. 134 135 > ls /dev/ttyUSB* 136 137 * If you run the `ls` command before and after connecting the Servo V4 138 type C cable to the DUT, then the new devices should be the CCD 139 consoles. The consoles are ordered. Cr50 should be the lowest ttyUSB 140 device, then AP, and EC should have the highest number. Running `ver` 141 on all of them could also let you know which one is which if you don't 142 want to remember the order. 143 **Servo V4 has it's own console. It might be useful to do this step to 144 find the device consoles** 145 146 * Open the console. 147 148 > minicom -D /dev/ttyUSB1 149 150 * Make sure `version` shows some version information. 151 1529. **Open CCD.** Here's the most generic way to open ccd. For the full open 153 options see [Setup CCD]. 154 155 * **[Enter dev mode](case_closed_debugging_gsc.md#enter-dev-mode).** 156 These are clamshell instructions for other types of chromeOS devices 157 refer to the full setup doc. 158 159 * Boot into recovery by pressing the power button, refresh, and 160 escape. 161 162 * At the recovery screen press Ctrl+D and enter. 163 164 * **Use gsctool to open Cr50 from the AP. Press the power button when 165 prompted.** This will take ~5 minutes. 166 167 AP > gsctool -a -o 168 16910. **Set all capabilities to Always** and confirm they're Always. 170 171 cr50 > ccd reset factory 172 cr50 > ccd 173 17411. **Enable Testlab Mode.** Tap the power button when prompted. This will 175 take a couple of seconds. 176 177 cr50 > ccd testlab enable 178 179 18012. **Start servod and make sure the EC console works.** 181 182 183 * enter chroot with `cros_sdk --no-ns-pid` 184 185 * start servod 186 187 chroot > sudo servod -b $BOARD 188 189 * Check EC uart works. 190 191 chroot > dut-control ec_board 192 19313. **Try running a test** Use autotest_dir, so you don't need to about what 194 autotest packages to emerge. firmware_ECHash is just a short test. If your 195 board doesn't have an EC, try something else. Use firmware_FAFTSetup to 196 verify the setup will work with faft-ec and faft-bios. 197 198 chroot > test_that $IP --autotest_dir \ 199 ~/trunk/src/third_party/autotest/files/ firmware_ECHash 200 20114. **Debug Setup** 202 203 204 * **Cr50 capabilities:** EC uart capability needs to always be accessible. 205 **Make sure UartGscTxECRx and all other capabilities are always.** 206 207 cr50 > ccd 208 209 * **Make sure servod started using the CCD device**. Verify the ccd 210 serialname has the right format. Cr50 serialname should have the 211 format [0-9a-f]{8}-[0-9a-f]{8} 212 213 chroot > dut-control ccd_serialname 214 215 If the control doesn't exist or the serianame is wrong try to find 216 ccd serialname and start servod explicitly selecting it. 217 218 find serialname and use it to restart servod. 219 220 chroot > lsusb -vd 18d1:5014 | grep iSerial 221 chroot > sudo servod -b $BOARD -s $SERIALNAME 222 223 224### Final Checks 225 226 * All capabilities are Always 227 228 cr50 > ccd 229 230 * Testlab mode is enabled 231 232 cr50 > ccd testlab 233 234 * EC uart works 235 236 chroot > dut-control ec_board 237--- 238## I Just Want to Disable HW Write Protect 239Cr50 has a couple of ways to remove HW write protect. The biggest difference in 240the process is whether or not you want to open the case and whether or not you 241need write protect disable to be permanent. 242 243**Opening CCD might require the AP can boot. If you're relying on CCD to recover 244a bricked machine, you may want to do the optional CCD setup steps before 245flashing RO firmware.** 246 247### Process if You're Okay Opening Case 248Cr50 will disable HW write protect if you remove the battery. 249 250#### Steps 251 2521. **Open the Case.** 253 2542. **Remove the battery.** Cr50 disables write protect when the battery is 255 disconnected. On chromeboxes you need to remove the write protect screw. 256 2573. (bob only) remove the write protect screw. Bob uses cr50 and a write protect 258 screw. Cr50 has to disable write protect and the screw has to be removed for 259 write protect to be disabled. 260 2614. (optional) Check write protect is disabled from the AP. 262 263 AP > crossystem wpsw_cur 264 2655. (optional) Reconnecting the battery will reenable write protect. You can 266 disable SW write protect if you want to be able to rewrite RO firmware 267 without needing to keep the battery disconnected. 268 269 AP > futility flash --wp-disable 270 2716. **(recommended) Run some basic commands to setup CCD.** It's really easy to 272 open cr50 with the battery removed. You might want to setup CCD while you 273 already have the case open and the battery is disconnected. Doing these 274 extra CCD setup steps may make it easier to recover a bricked device using 275 CCD. These will require SuzyQ. 276 277 * **Open Cr50** from the AP or Cr50 console. This will happen immediately. 278 279 280 AP > gsctool -a -o 281 282 or 283 284 Cr50 > ccd open 285 286 287 288 * **Setup capabilities.** This can only be done from the Cr50 console. 289 290 Enable flashing the AP/EC CCD open. 291 292 Cr50 > ccd set OverrideWP Always 293 Cr50 > ccd set FlashAP Always 294 Cr50 > ccd set FlashEC Always 295 296 Enable opening Cr50 without booting the AP. 297 298 Cr50 > ccd set OpenNoDevMode Always 299 Cr50 > ccd set OpenFromUSB Always 300 301### Process With Case Closed 302Full instructions are at [Setup CCD], but here are are the basic steps. If 303you're unsure about a step here you should take a look at the [Setup CCD] doc. 304It goes into a lot more detail. 305 306#### Requirements 307 308* A [SuzyQ]. Cr50 console access is required to disable write protect. 309* The device needs to be able to boot. 310* The GBB\_FLAG\_FORCE\_DEV\_SWITCH\_ON GBB flag is cleared. 311 312#### Steps 3131. **Open CCD.** Here's the most generic way to open ccd. For the full open 314 options see [Setup CCD]. 315 316 * **[Enter dev mode](case_closed_debugging_gsc.md#enter-dev-mode).** 317 These are clamshell instructions for other types of chromeOS devices 318 refer to the full setup doc. 319 320 * Boot into recovery by pressing the power button, refresh, and 321 escape. 322 323 * At the recovery screen press Ctrl+D and enter. 324 325 * **Use gsctool to open Cr50 from the AP.** Press the power button when 326 prompted. This will take ~5 minutes. 327 328 AP > gsctool -a -o 329 3302. **[Connect](#How-to-Use-SuzyQ) to the Cr50 console** using SuzyQ or servo 331 v4. 332 333 > minicom -D /dev/ttyUSB0 334 3353. **Disable write protect** using Cr50 [wp console command]. 336 337 cmd to disable until cr50 reboots: 338 339 cr50 > wp disable 340 341 cmd to disable it indefinitely: 342 343 cr50 > wp disable atboot 344 345 3464. (optional) Check HW WP is disabled. ccd open takes the AP out of dev 347 mode, so you can reenter dev mode and check the HW WP status from the AP. 348 349 From AP (after reentering dev mode): 350 351 AP > crossystem wpsw_cur 352 353 3545. **(recommended) Setup capabilities**, so you can flash the device or open 355 ccd without being able to boot the AP. 356 357 Make flashing the AP/EC accessible without opening CCD 358 359 Cr50 > ccd set OverrideWP Always 360 Cr50 > ccd set FlashAP Always 361 Cr50 > ccd set FlashEC Always 362 363 Enable opening Cr50 without booting the AP 364 365 Cr50 > ccd set OpenNoDevMode Always 366 Cr50 > ccd set OpenFromUSB Always 367 3686. **(recommended) [Disable SW WP]** to flash RO firmware if your board has 369 issues disabling HW WP with the AP off. 370 371 AP > futility flash --wp-disable 372 373[Disable SW WP]: ./case_closed_debugging_gsc.md#AP-Off 374[enter dev mode]: ./case_closed_debugging_gsc.md#enter-dev-mode 375[sparkfun]: https://www.sparkfun.com/products/14746 376[Setup CCD]: ./case_closed_debugging_gsc.md#CCD-Setup 377[SuzyQ]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/main/docs/ccd.md#suzyq-suzyqable 378[Type-C Servo V4]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/refs/heads/main/docs/servo_v4.md 379[wp console command]: ./case_closed_debugging_gsc.md#WP-control 380 381