David Hubbard has uploaded this change for review.
Migrate https://www.coreboot.org/EHCI_Debug_Port to docs
The coreboot documentation about the EHCI Debug Port appears to be the
most comprehensive resource on the net on the topic. Updated to at least
mention the XHCI Debug cable as well, without committing to coreboot
support.
This also cleans up the organization a bit and adds two new links
in the "External Resources" section.
This does not include images of the Ajays NET20DC or AMIDebug Rx
because they have disappeared even from the secondhand market.
Change-Id: Ifaef2a6bd770a8888015bedb1c818b53e1c4391f
Signed-off-by: David Hubbard <david.c.hubbard@gmail.com>
---
M Documentation/external_docs.md
A Documentation/lib/usb_debug_port.md
2 files changed, 261 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/56/72956/1
diff --git a/Documentation/external_docs.md b/Documentation/external_docs.md
index 2f34bf6..37109d2 100644
--- a/Documentation/external_docs.md
+++ b/Documentation/external_docs.md
@@ -24,6 +24,7 @@
* [OS Dev](https://wiki.osdev.org/Categorized_Main_Page)
* [Interface BUS](http://www.interfacebus.com/)
+* [EHCI Debug Port](lib/usb_debug_port.md)
## OpenSecurityTraining2
diff --git a/Documentation/lib/usb_debug_port.md b/Documentation/lib/usb_debug_port.md
new file mode 100644
index 0000000..15083b4
--- /dev/null
+++ b/Documentation/lib/usb_debug_port.md
@@ -0,0 +1,239 @@
+# USB Debug Ports
+
+# USB Debug Port
+
+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 that sometimes works is to use one special
+USB port set up in the board hardware that can work in a similar way.
+
+coreboot has some ability to send logs over the USB Debug Port.
+
+## USB 2.0 (EHCI)
+
+All USB2 host controllers are EHCI controllers. The **EHCI Debug Port**
+is an optional capability of EHCI controllers which can be used for that
+purpose. In linux the EHCI controller's capabilities can
+[be listed](#Finding-the-USB-debug-port) using `lspci` (as root).
+
+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 the debug port is wired to just a single physical
+**port**. A Debug Class compliant device is the only supported USB function
+that can talk to the port when used this way, because the port is no longer
+acting as a normal USB host would.
+
+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.
+
+## USB 3.0 (XHCI)
+
+The USB 3.0 protocol introduced new hardware and a new method for communicating.
+Here is an external site with a brief intro:
+
+https://docs.kernel.org/driver-api/usb/usb3-debug-port.html
+
+## Supported chipsets
+
+The following southbridges have USB debug support in coreboot. If your
+southbridge is not listed, please add support for it. Please also check
+the list after the table for the specific controller ID.
+
+Vendor |Southbridge |Status |Comments
+--------|------------|---------|--------
+AMD |SB600 |OK |Tested by Uwe Hermann (coreboot user "Uwe").
+AMD |SB700 |WIP |Probably won't work.
+AMD |SB900 |OK |Tested on HP Pavilion m6 1035dx.
+AMD |A85X (Hudson D4) | OK |Tested by Tobias Diedrich (coreboot user "Ranma") on ASUS F2A85M-LE.
+Intel |82801GX (ICH7) | OK |Tested by Sven Schnelle (coreboot user "SvenS") 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).
+
+### 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)
+
+## 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](http://www.coreboot.org/pipermail/coreboot/2008-September/038618.html)
+[a script](http://www.coreboot.org/pipermail/coreboot/attachments/20080909/ae11c291/attachment.sh)
+which can help finding that port. An
+[updated script](http://www.coreboot.org/pipermail/coreboot/attachments/20140530/245547f8/attachment.sh)
+was posted
+[here](http://www.coreboot.org/pipermail/coreboot/2014-May/078022.html)
+on May 30 2014.
+
+The Debug Port is optional, please check if EHCI controllers near you
+support it: `lspci -v | grep USB`. If you get any result try `lspci -v` and
+locate the entry.
+
+This is a slightly improved script that might not work but you can try it:
+
+```
+$ for i in $(lspci|grep USB|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 USB|cut -f1 -d' ') ; do
+$ lspci -ns $i
+$ done
+00:1d.7 0c03: 8086:265c (rev 03)
+```
+
+If your controller's ID isn't already listed above then please add it
+
+## 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 enter
+the index under **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).
+
+## Receiving PC
+
+### Commercial Devices/Dongles (No longer available)
+
+There were two commercial devices sold, neither of which appears to be available
+anymore, which can talk to the EHCI Debug Port.
+
+**AMIDebug Rx**
+
+This device was expensive compared to the other devices on this page. The
+main advantage of this product was that it came with an 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](http://web.archive.org/web/20080219120613/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 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).
+
+The host PC needs to be a Linux system with the **usb_debug** kernel
+module. When you attach the Ajays Net20DC device to the receiving 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).
+
+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.
+
+## External Resources
+
+* [EHCI 1.0 spec](http://www.intel.com/technology/usb/download/ehci-r10.pdf)
+ (PDF) — The Debug Port is described in Appendix C.
+* [Debug Class functional spec](http://developer.intel.com/technology/usb/download/DebugDeviceSpec_R090.pdf)
+ (PDF) — This is what has to be connected to the EHCI controller.
+* [Intel Developer UPDATE Magazine on USB debugging](https://web.archive.org/web/20050826153054/http://www.intel.com/technology/magazine/computing/it09021.pdf)
+ (archive.org PDF)
+* [Linux x86_64 early USB Debug Port support](http://lkml.org/lkml/2006/12/4/3)
+* 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](https://web.archive.org/web/20060716095513/http://www.usb.org/developers/presentations/pres0602/john_keys.pdf)
+* [Linux early USB Debug Port support finally commited](http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=5c05917e7fe313a187ad6ebb94c1c6cf42862a0b)
+* [early printk support in Linux](http://www.kernel.org/doc/Documentation/x86/earlyprintk.txt)
+* Raspberry Pi connected to debug port:
+ * https://github.com/raspberrypi/linux/issues/1907
+ * https://eramons.github.io/techblog/post/debug_coreboot/
+ * http://www.spinics.net/lists/linux-usb/msg32912.html
+* http://cs.usfca.edu/~cruse/cs698s10/ - various EHCI debug port and Ajays resources
+* https://github.com/avivgr/teensy_debugdev - partially working implementation for a Teensy ATMEGA32U4
To view, visit change 72956. To unsubscribe, or for help writing mail filters, visit settings.