1# Case Closed Debugging (CCD) 2 3Case closed debugging is a feature of the EC codebase that can bridge UART 4consoles and SPI buses from a DUT (Device Under Test) to the host machine via 5USB. This allows the host to access and update much of the DUT's state. Use 6cases include automated hardware testing as well as simplified debug console 7access and firmware flashing for kernel and system developers. 8 9[TOC] 10 11## Prerequisites 12 13### Supported Devices 14 15We have added CCD support for two chip families: stm32 and gchips. Ryu, 16[`servo_micro`], and [`servo_v4`] use the stm32 support. Cr50 uses gchips 17support. All boards with Cr50 have support for case closed debugging. 18 19### Suzy-Q 20 21[Suzy-Q] is a Type-C dongle that exposes USB2.0/3.0 on a Type-A socket, case 22closed debugging over SBU1/2 on a micro Type-B socket, and charging over a 23Type-C socket. You will need one to access the case closed debugging USB 24interface. Full details, including where to buy and how to make your own are in 25the [Suzy-Q docs][Suzy-Q]. 26 27### Chromium OS flashrom 28 29The functionality to flash the AP firmware image over case closed debugging is 30currently only supported by the ChromiumOS version of flashrom, so you will need 31to have that built. The easiest way to do so is to just setup the Chromium OS 32SDK. 33 34### Udev rules file 35 36There is a udev rules file, `extra/usb_serial/51-google-serial.rules` that 37should be installed in `/etc/udev/rules.d/` and udev should be told to reread 38its rules. This rules file can be installed using the `extra/usb_serial/install` 39script. 40 41### Kernel module 42 43A trivial Linux kernel module that identifies case closed debug capable USB 44interfaces can be found in `extra/usb_serial`. This module is also built and 45installed using the `extra/usb_serial/install` script. 46 47### Chromium OS chroot 48 49This is really only a requirement for using flashrom. If you only need access to 50the serial consoles then a checkout of the EC firmware repository should be 51sufficient. 52 53## Setup 54 55### Device Under Test (DUT) 56 57If the DUT doesn't have a new enough PD firmware you will need to update the 58firmware using a Servo, `ectool`, or MCU specific DFU mode, all of which are 59outside the scope of this document. 60 61Make sure your DUT is charged up, because while using [Suzy-Q] you can't 62currently charge the device. 63 64### Suzy-Q 65 66[Suzy-Q] should be connected to the DUT using the Type-C cable and connector 67integrated into [Suzy-Q]. This connector may need to be flipped to make case 68closed debugging work because the SBU lines that are used to expose the PD MCU's 69USB interface are not orientation invariant. Only one port on the DUT will 70support CCD. Try using the other port if the CCD device doesn't appear. [Suzy-Q] 71should be connected to the Host with a Type-A (Host) to Micro Type-B ([Suzy-Q]) 72cable. Look for the device [`vendor:product ID`](#Troubleshooting) to your host 73sees the CCD device. 74 75### Host 76 77Depending on your kernel version the consoles may exist at `/dev/ttyUSB*`. If 78using those works for you, you don't need to install any drivers or Udev rules. 79 80If you want your host to generate useful symlinks for the different CCD 81consoles, install the Udev rule. It will generate symlinks in 82`/dev/google/<device name>/serial/<console name>` for each serial console that a 83device exports. It will also mark the DUT as incompatible with ModemManager. 84This last part ensures that ModemManager doesn't attempt to open and manipulate 85the various serial consoles exported by the device. 86 87The kernel module in `extra/usb_serial` should be compiled and installed in the 88running kernel. It just adds an entry into the `usbserial` module's driver table 89that causes `usbserial` to recognize any case closed debugging serial console as 90a simple USB serial device. This addition has already made its way into the 91upstream kernel (v3.19), so eventually this module can be removed. The 92`extra/usb_serial/install` script will build and install the kernel module as 93well as install the udev rules file. 94 95If for some reason you can't or don't want to use the kernel module the install 96script provides a `--fallback` option that will install a udev rules file and 97helper script instead that will add each new CCD capable device that is attached 98to the host to the list of devices that usbserial will handle. The disadvantage 99of this method is that it will generate `/dev/ttyUSB*` entries for any USB 100interface on the device that has an IN/OUT pair of bulk endpoints. This results 101in extra `/dev/ttyUSB*` entries that should not be used because they are 102actually I2C or SPI bridges. 103 104The raiden module solves this by identifying a CCD serial port by the subclass 105and protocol numbers of the USB device interface. This means that there does not 106need to be a list of CCD capable device IDs anywhere. 107 108## Basic CCD 109 110Here's the basic information for how to use CCD. Cr50 restricts debugging 111features to try and ensure only the device owner can use CCD. For information on 112how to get access to Cr50 CCD see the [Cr50 specific CCD doc][Cr50 CCD]. 113 114### Consoles 115 116The serial consoles exposed by case closed debugging can be found in 117`/dev/ttyUSB*` or `/dev/google/<device name>/serial/<console name>` if you 118installed the Udev rules. The consoles can be opened with any program that you 119would normally use to open a TTY character device such as minicom or screen. 120 121If you installed the Udev rules, the console path will be determined based on 122the device and USB bus. The `<device name>` field is generated from the DUT's 123USB descriptor `iProduct` field as well as the USB bus index and device path on 124that bus (the list of port numbers for the hub connections between the Host and 125DUT). As such it is unique to a particular setup and won't change across reboots 126of either the Host or the DUT. The `<console name>` field is just the 127`iInterface` USB descriptor field from the particular USB interface that is 128associated with this console device. This allows a single DUT to expose multiple 129serial consoles in a discoverable and consistent manner. 130 131If you're using the consoles at `/dev/ttyUSB*`, you can just check which console 132it is by running a few commands like `version`. 133 134### Flash AP 135 136Programming the AP SPI flash with a new firmware image can be done with flashrom 137using the command: 138 139```bash 140(chroot) $ sudo /usr/sbin/flashrom -p raiden_debug_spi -w /build/<board>/firmware/image.bin 141``` 142 143If there are more than one case closed debug capable devices connected to the 144host you will have to disambiguate the DUT with additional programmer 145parameters. Flashrom will list all DUTs that are found along with programmer 146parameters that can be used to identify the intended DUT. Flashrom programmer 147added to the programmer name (the `-p` argument) by appending a colon and then a 148colon and then a comma separated list of `key=value` pairs. The `serial` 149parameter is best for this. 150 151```bash 152(chroot) $ sudo /usr/sbin/flashrom -p raiden_debug_spi:serial=${SERIAL} -w /build/<board>/firmware/image.bin 153``` 154 155Cr50 can be used to flash the AP or EC. You will need to specify the AP as the 156target device, so cr50 knows to flash the AP. 157 158```bash 159(chroot) $ sudo flashrom -p raiden_debug_spi:target=AP -w image.bin 160``` 161 162### Flash EC 163 164You can use `util/flash_ec` to flash the EC. Steps for flashing the EC are more 165complex and board specific than flashing the AP. This script will handle all the 166board specific setup. 167 168## Known Issues 169 1701. Charge and the use of the Type-A port on [Suzy-Q] do not work, so for now if 171 you need to attach a flash drive, or use Fastboot/adb you'll need to swap 172 cables. 173 1742. Ryu implementation: software sync of the EC/PD processor and the jump from 175 RO to RW versions will cause the case closed debugging USB device to 176 disconnect and reconnect. This can be prevented by disabling software sync. 177 This is done by setting the `GBB_FLAG_DISABLE_EC_SOFTWARE_SYNC` and 178 `GBB_FLAG_DISABLE_PD_SOFTWARE_SYNC` flags with`gbb_utility. 179 180## Troubleshooting 181 182Check for the CCD device using the following `vendor:product` IDs 183 184Device | VID:PID 185--------------- | ----------- 186[`servo_micro`] | `18d1:501a` 187[`servo_v4`] | `18d1:501b` 188[`servo_v2`] | `18d1:5002` 189`ryu` | `18d1:500f` 190`cr50` | `18d1:5014` 191 192See the [`SERVO_PID_DEFAULTS`] in the servo code for all values. 193 194### Can't see the CCD device on the host 195 1961. Type-C cable from [Suzy-Q] to the DUT may be upside down. The SBU lines used 197 for case closed debugging are not orientation invariant. 1981. You may be using the wrong device port. Try using the other port. 1991. The device may not be charged enough to boot. [Suzy-Q] can't charge the 200 device or supply enough power for the DUT to boot. Make sure the device is 201 somewhat charged. 202 203### No console interfaces are available in the "/dev/google/<name>" directory 204 2051. Kernel module may not be loaded. 2061. Udev rules file might not be installed correctly. 2071. PD firmware version may be too old. 2081. Type-C cable from [Suzy-Q] to the DUT may be upside down. The SBU lines used 209 for case closed debugging are not orientation invariant. 210 211### Garbage messages (AT command set) show up on one or more consoles 212 2131. ModemManager has claimed the interface, Udev rules file may not be installed 214 correctly. 215 216### Console interfaces appear and then quickly disappear 217 2181. Software sync from the AP has replaced the PD firmware with a version that 219 is not compatible with case closed debugging. 220 221[`servo_v4`]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/main/docs/servo_v4.md 222[`servo_v2`]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/main/docs/servo_v2.md 223[`servo_micro`]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/main/docs/servo_micro.md 224[Cr50 CCD]: ./case_closed_debugging_gsc.md 225[Suzy-Q]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/main/docs/ccd.md#suzyq-suzyqable 226[`SERVO_PID_DEFAULTS`]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/ff8e96686ef3d9ad2e26125ca8268cb7f7666f6c/servo/interface/ftdi_common.py#28 227