mirror of
https://github.com/Telecominfraproject/OpenCellular.git
synced 2026-01-08 16:41:55 +00:00
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>
This commit is contained in:
Anton Staaf
committed by
ChromeOS Commit Bot
ChromeOS Commit Bot
parent
9bdffe0513
commit
f8a8f0bbfd
143
docs/case_closed_debugging.md
Normal file
143
docs/case_closed_debugging.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user