EHCI Debug Port

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.

• sudo lshw can be used to find EHCI cabpable USB ports. It may yield something like:

     *-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

• As dmesg are part of the core system it can be used from Live distributions that often protect the filesystem from file execution which means that scripts cannot be used. The easiest way to locate the physical USB port that has EHCI debug support can be verified by doing the following:
  • sudo dmesg -c
  • Plug a USB flash memory
  • dmesg | tail -22 | grep ehci
• Carl-Daniel Hailfinger has written a script which can help finding that port. An updated script was posted here on May 30 2014.

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

• 10b9:5239 ALi Corporation USB 2.0 (USB PCI card)
• 8086:24cd Intel ICH4/ICH4-M
• 8086:24dd Intel ICH5
• 8086:265c Intel ICH6
• 8086:268c Intel 631xESB/632xESB/3100 Chipset (rev 09) (in Dell PE 1950)
• 8086:27cc Intel ICH7
• 8086:2836 Intel ICH8
• 8086:283a Intel ICH8
• 8086:293a Intel ICH9 (rev 2)
• 8086:3a3a Intel ICH10
• 8086:3a3c Intel ICH10
• 10de:0088 NVIDIA MCP2A (rev a2)
• 10de:005b NVIDIA CK804 (rev a3)
• 10de:026e NVIDIA MCP51 (rev a3)
• 10de:036d NVIDIA MCP55 (rev a2)
• 10de:03f2 NVIDIA MCP61 (rev a3)
• 1002:4386 ATI/AMD SB600
• 1002:4396 ATI/AMD SB700
• 1022:7808 AMD A85X
• 1106:3104 VIA VX800 (rev 90)

Controllers verified to lack the debug port capability

• 1033:00e0 NEC Corporation EHCI (rev 02) (Compaq part)
• 1106:3104 VIA Technologies EHCI (rev 82, rev 63, rev 86)
• 1002:4373 ATI Technologies Inc IXP SB400 USB2 Host Controller (rev 80)
• 1022:2095 Advanced Micro Devices [AMD] CS5536 [Geode companion] EHCI (rev 02)
• 8086:24cd Intel Corporation 82801DB/DBM (ICH4/ICH4-M) EHCI (rev 01)
• 1039:7002 SiS EHCI (rev 00)

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.

• http://www.ami.com/products/bios-uefi-tools-and-utilities/amidebug-rx/

"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.

• http://www.plxtech.com/products/NET2000/NET20DC/default.asp (archive.org)

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

• EHCI 1.0 spec (PDF) — The Debug Port is described in Appendix C.
• Debug Class functional spec (PDF) — This is what has to be connected to the EHCI controller.
• Intel Developer UPDATE Magazine on USB debugging (PDF) — dead URL (copy at archive.org)
• libusb host program for PLX NET20DC debug device
• Linux x86_64 early USB Debug Port support
• http://coreboot.org/pipermail/coreboot/2006-December/thread.html#17480
• http://lkml.org/lkml/2006/12/1/214
• http://www.usb.org/developers/presentations/pres0602/john_keys.pdf
• Linux early USB Debug Port support finally commited
• early printk support in Linux
• http://www.spinics.net/lists/linux-usb/msg32912.html (Linux USB EHCI Debug Port device gadget)
• http://cs.usfca.edu/~cruse/cs698s10/ - various EHCI debug port and Ajays resources