Chromium OS‎ > ‎

Closed Case Debugging (CCD)

Introduction

In order to get access to the AP and EC consoles or reprogram the firmware without using the AP, older devices required people to open them up to get to a debug header via something called Servo. To make matters worse, these headers are frequently unpopulated on production units.

Newer devices have a secure microcontroller in them which runs an embedded OS called Cr50. Among other capabilities, this chip allows developers to securely debug the whole device.

The current capabilities allow read/write access to a UART on the AP and read only UART access to the EC. More interfaces will be exposed in the future (it’s eventually meant to replace all capabilities of Servo).

Communicating with Cr50

The Cr50 code uses the microcontroller’s USB interface to expose its debugging functionality. This interface can be reached via a special USB Type-C cable on one of the system’s ports.

To get Cr50 into debug mode, the cable has to present itself as a Debug Accessory (see Chapter B of the USB Type-C Specification). When this cable is detected the system will connect the Cr50 full-speed USB2.0 interface to the SBU pins of the Type-C connector. Note that this prevents use of the DisplayPort alternate-mode (which also uses the SBU pins) but preserves regular USB operation on the port.

Once the debug cable is connected, Cr50 makes several USB endpoints available to the host to communicate with the consoles, to program firmware, etc. More details about these CCD software interfaces can be found in the documentation section of the EC codebase.

Making your own cable

One needs a USB Type-C Male breakout board, and some way of connecting the other end to a computer’s USB port (like a Type A Male port).

 Type C Male  Other host (Type A Male)
 A8 (SBU 1)  D+
 B8 (SBU 2)  D-
 A4, A9, B4, B9 (VBUS)  VBUS, 5V
 A5 (CC1)  22 kΩ resistor to VBUS
 B5 (CC2)  56 kΩ resistor to VBUS
 A1, A12, B1, B12 (GND)  GND

SuzyQ / SuzyQable

Because this cable is pretty handy, there are finished manufactured versions of them. This version includes a USB hub in the cable, which allows the host computer to access both the debug interface (on the SBU pins) and any gadget-mode interfaces exposed by the device-under-test (for example an ADB interface for debugging Android applications). Reference schematics are available for this cable.

This cable is available for sale from Sparkfun: https://www.sparkfun.com/products/14746.

Servo v4

Servo v4 also has CCD capabilities (routing SBU lines to the USB host, signaling on the CC lines debug accessory mode). During debugging, Servo v4 will normally allow the device-under-test to act as a USB host, providing it with an Ethernet interface and USB flash device that may be used for a recovery image. Servo v4 allows USB Type-C connection automation (both data and charging).

Using CCD

To use most of the features of CCD, on your Linux workstation you need to build Chromium OS and create a chroot environment. It’s possible to use a subset of CCD without all that hassle too, skip to the Raw Access section.

The hdctools (Chrome OS Hardware Debug & Control Tools) package contains several tools needed to work with servod. Make sure the latest version is installed in your chroot:

sudo emerge hdctools

On your workstation, servod must also be running to communicate with cr50:
sudo servod -b $BOARD &

CPU/AP UART can be accessed by running:
miniterm.py --lf `dut-control cpu_uart_pty|cut -d ":" -f 2`

Note that on a normal install of Chrome OS the UART is not normally used. One has to be in dev mode (or a custom OS).
On most x86 production images the UART drivers are also disabled for performance reasons, but they can be added back in with a custom AP firmware.

EC UART:
miniterm.py --lf `dut-control ec_uart_pty|cut -d ":" -f 2`

For now this console is read only. One can see various debug prints from charging, keyboard scanning, power state. 

Cr50 itself has a console available, but most commands are locked for security:
miniterm.py --lf `dut-control cr50_uart_pty|cut -d ":" -f 2`

Future planned features:

  • Control of firmware write protect (for now removing the battery is enough)
  • Flashing of the AP and EC firmware
  • EC RW console access
  • Read I2C INA219 current sensors (though most production boards do not have them populated)

Raw Access

A subset of these features (ex: uart lines) can be accessed without a cros_sdk chroot.
Once the SuzyQ is plugged in, 3 /dev/ttyUSB devices will enumerate:
  1. Cr50 console
  2. CPU/AP console (RW)
  3. EC console (RO only)

Device Support

Referring to the Chrome OS device list all boards with base board coral, eve, reef + bob. Note the "Closed Case Debugging" column.

If the device is ARM, the CPU/AP UART works by default in dev mode (you should see a login prompt). x86 devices disable it for performance / power reasons, but UART can be re-enabled with a custom firmware.

Port / Orientation Note

The cable will generally only work in one port and one orientation. If it doesn't work try the other port, or rotate the connector. Check the device list for more details.

To see if it worked, one can check the presence of /dev/ttyUSB* devices, or monitor lsusb for cr50 device enumerating:
watch -n 1 "lsusb | grep 18d1:5014"
Ċ
Alexandru Stan,
Jul 10, 2018, 2:39 PM
Comments