CCD: Add documentation

This document is a user HOWTO for Case Closed Debugging in
Markdown format.  It can be converted to HTML using pandoc
if desired.

Signed-off-by: Anton Staaf <robotboy@chromium.org>

BRANCH=None
BUG=None
TEST=pandoc case_closed_debugging.pm > case_closed_debugging.html
     RTFM

Change-Id: I66870894309d20c4cc8e5139b7f4e4aed0b1d9f6
Reviewed-on: https://chromium-review.googlesource.com/269744
Reviewed-by: Bill Richardson <wfrichar@chromium.org>
Commit-Queue: Anton Staaf <robotboy@chromium.org>
Trybot-Ready: Anton Staaf <robotboy@chromium.org>
Tested-by: Anton Staaf <robotboy@chromium.org>

1 files changed, 143 insertions, 0 deletions

diff --git a/docs/case_closed_debugging.md b/docs/case_closed_debugging.md
new file mode 100644
index 0000000000..2bd0d9727b
--- /dev/null
+++ b/docs/case_closed_debugging.md
@@ -0,0 +1,143 @@
+Case Closed Debugging
+=====================
+
+Case closed debugging is a feature of the EC codebase that can bridge UART
+consoles and SPI busses 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.
+
+Prerequisites
+-------------
+
+### Ryu
+Currently only Ryu has support for case closed debugging.  The first version of
+Ryu that supported case closed debugging was P3.
+
+### 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.
+
+### ChromiumOS 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
+ChromiumOS 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.
+
+### Kernel module
+A trivial Linux kernel module that identifies case closed debug capable USB
+interfaces can be found in `extra/usb_serial`.
+
+### ChromiumOS 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, ec-tool, 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.  Suzy-Q should be connected
+to the Host with a Type-A (Host) to Micro Type-B (Suzy-Q) cable.
+
+### Host
+The Udev rule file should be installed, it will generate useful 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 `Makefile` in the `extra/usb_serial` directory will build the kernel module
+against the current running kernel, and `insmod raiden.ko` will install it.
+If installation fails due to missing dependencies you need to
+`modprobe usbserial` first.
+
+An alternative to using this module is to install `usbserial` with
+`modprobe usbserial vendor=<VID> product=<PID>`.  The disadvantage of this method
+is that it only works for an exact VID:PID match, and the module above does a
+more detailed match of the USB descriptors to find interfaces that export the
+Google simple serial vendor specific subclass.
+
+Use
+---
+
+The serial consoles exposed by case closed debugging can be found in
+`/dev/google/<device name>/serial/<console name>` and can be opened with any
+program that you would normally use to open a TTY character device such as
+minicom or screen.  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.
+
+Programming the AP SPI flash with a new firmware image can be done with flashrom
+using the command:
+
+`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 parameters are
+added to the programmer name (the -p argument) by appending a colon and then a
+comma separated list of key=value pairs.
+
+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. 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
+---------------
+
+1. No console interfaces are avaiable in the `/dev/google/<name>` directory.
+
+	1. Kernel module may not be loaded.
+	2. Udev rules file might not be installed correctly.
+	3. PD firmware version may be too old.
+	4. 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.
+
+2. 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.
+
+3. 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.