EHCI Debug Port

The wiki is being retired!

Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!

Ajays (now bankcrupt) NET20DC 2.0 EHCI controller debug device.

Serial ports have been the primary means of early debugging of new coreboot ports. New hardware doesn't always have a serial port and another method for early debugging is needed.

The EHCI Debug Port is an optional capability of EHCI controllers which can be used for that purpose.

All USB2 host controllers are EHCI controllers. The debug port provides a mode of operation that requires neither RAM nor a full USB stack. A handful of registers in the EHCI controller PCI configuration and BAR address space are used for all communication. All three transfer types are supported (OUT/SETUP/IN) but transfers can only be a maximum of 8 bytes and only one specific physical USB port can be used. A Debug Class compliant device is the only supported USB function that can be communicated with.

While the Debug Class functional spec describes a device communicating over USB also with the debugging host (aka remote) it would be very possible to make a Debug Class device with a regular serial port on the other end. One thing to watch out for is that such a device might not be able to handle the same throughput as the debug port itself and hence may lose data unless it can do some buffering.

Supported chipsets

The following southbridges have USB debug support in coreboot:

Vendor Southbridge Status Comments
AMD SB600 OK Tested by Uwe Hermann.
AMD SB700 WIP Probably won't work, a patch is being prepared.
AMD SB900 OK Tested on HP Pavilion m6 1035dx
AMD A85X (Hudson D4) OKhttps://www.coreboot.org/BeagleBone_Black_-_screwdriver Tested by Tobias Diedrich on ASUS F2A85M-LE.
Intel 82801GX (ICH7) OK Tested by Sven Schnelle on Lenovo Thinkpad X60/T60.
NVIDIA MCP55 OK Tested by Uwe Hermann. Any physical USB port will work, as the code tries all ports until the one with the attached USB Debug device is found.
SiS SiS966 Untested Note: It's unclear if the chipset actually has EHCI Debug Port functionality, and (if yes), whether the current coreboot code supports it properly (or whether it's just copy-pasted code from another chipset).

Finding the USB debug port

Generally, each EHCI controller can offer at most one debug port. That port corresponds to a fixed physical USB port. Locating that physical port without software is rather difficult because you need to look at lots of information. 

     *-usb:1
          description: USB controller
          product: MCP55 USB Controller
          vendor: NVIDIA Corporation
          physical id: 2.1
          bus info: pci@0000:00:02.1
          version: a2
          width: 32 bits
          clock: 66MHz
          capabilities: debug pm ehci bus_master cap_list
          configuration: driver=ehci_hcd latency=0 maxlatency=1 mingnt=3
          resources: irq:22 memory:ee204000-ee2040ff

Using the EHCI debug port

usb_debug kernel module and minicom

To get a USB debug console, enable both CONFIG_USBDEBUG and CONFIG_CONSOLE_USB (menu option USB 2.0 EHCI debug dongle support) in coreboot's kconfig.

In case your system has more than one debug-capable EHCI, you can select the index as CONFIG_USBDEBUG_HCD_INDEX, with a southbridge-specific value (on AMD Hudson, 0 and 1 both indicate the first port, 2 is the second port).

On your "host PC" you need a Linux system which is recent enough to provide the usb_debug kernel module. When you attach the Ajays Net20DC device to your host PC, it will create a /dev/ttyUSB0 device to which you can connect as usual using any serial terminal program, e.g. minicom (115200, 8n1).

TODO: Is the Baud rate actually configurable somewhere?

You must connect the NET20DC to a special USB port on your coreboot target board (not all of the USB ports will work!), often this is USB port 1. If in doubt, try all available ports to check which one works on your board.

Then you can power up your coreboot target board and you should see the usual coreboot bootlog in minicom on your host PC.

usb_debug_io.c

As an alternative, you can also use this small libusb-based user-space program on the host PC to retrieve the coreboot logs.

Hardware capability

The Debug Port is optional, please check if EHCI controllers near you support it: lspci -v | grep ehci. If you get any result try lspci -v and locate the entry.


This might not work for your system but you can also try: 

$ for i in $(lspci|grep EHCI|cut -f1 -d' ') ; do
$       lspci -vs $i
$ done
00:1d.7 USB Controller: Intel Corporation 82801FB/FBM/FR/FW/FRW (ICH6 Family) USB2 EHCI Controller (rev 03) (prog-if 20 [EHCI])
Subsystem: IBM Unknown device 0566
Flags: bus master, medium devsel, latency 0, IRQ 5
Memory at b0000000 (32-bit, non-prefetchable) [size=1K]
Capabilities: [50] Power Management version 2
Capabilities: [58] Debug port

Look for a line like the last one above. Please include the PCI device ID too: 

$ for i in $(lspci|grep EHCI|cut -f1 -d' ') ; do
$       lspci -ns $i
$ done
00:1d.7 0c03: 8086:265c (rev 03)

If your controller isn't already listed below then please add it or send an email to the mailing list if you don't have a wiki account yet and want one, or want us to add your controller to the page.

Controllers verified to have the debug port capability

Controllers verified to lack the debug port capability

Debug devices

Debug software

A prebuilt Linux distribution called 'screwdriver' exists: "A tool for coreboot/libreboot/flashrom developers and users. The firmware itself is based on vanilla OpenWrt Chaos Calmer(15.04) with some modifications. This firmware is mainly intended for BeagleBone Black (BBB)." See BeagleBone_Black_-_screwdriver.

DIY / BeagleBone Black

EHCI Debug gadget driver

If you have a device running GNU/Linux that has an usb device port, you could then try to use the EHCI Gadget Debug. Note that it's not guaranteed to work on old kernels, and may be dependant on the usb device/otg controller driver.

You can make your own usb debug dongle, see DIY EHCI debug dongle.

A BeagleBone Black with a 5v power supply can achieve this. [1] (John Lewis)

Commercial Devices/Dongles

To be able to use the debug port it needs to be connected to a compatible device. There are two commercial devices available which can use the EHCI Debug Port, the AMIDebug Rx and Ajays NET20DC.

AMIDebug Rx

AMI Debug Rx USB 2.0 EHCI controller device.

This device is expensive compared to the other devices on this page. The main advantage of this product is that it comes with LCD.

"Interested parties may contact AMI for pricing and purchasing information" - AMI. point of contact: www.ami.com, phone number 1-800-828-9264.

Ajays NET20DC

Disclaimer:Ajays is bankcrupt so their product line is end of life (EOL). Symmetry Electronics and other companies have disengaged as a supplier of the Ajays Technology product line. This limits the number of available units on the market.

The device can be used in both directions, but only one side provides power for the circuit. Make sure to connect the front port (see picture at the top) to your host device and the rear port to the DUT. On the host side it doesn't matter which USB port to use, on the DUT side use the DEBUG port. Under GNU/Linux the device shows up as a regular serial USB device (ttyUSBx).

More information