descriptionxHCI debug capability driver Library
ownerAdrian-Ken Rueegsegger
last changeFri, 27 Oct 2017 12:19:15 +0000 (14:19 +0200)

Libxhcidbg - xHCI Debug Capability library


This libxhcidbg library implements support for the xHCI debug capability as specified in eXtensible Host Controller Interface for Universal Serial Bus (xHCI), revision 1.1, section 7.6. Libxhcidbg advertises the debug capability with vendor-id:device-id ffff:dbc1 and device revision 00.01. Descriptor strings are set as follows:

Product: HW.DbC
Manufacturer: secunet
SerialNumber: 1

Usage with Linux host

The usb-debug driver of Linux can be used to interact with the xHCI debug capability. To work with HW.DbC, one has to specify the vendor-id:device-id tuple after driver loading:

$ modprobe usb-debug
$ echo ffff dbc1 >/sys/bus/usb-serial/drivers/debug/new_id

When the USB debugging cable is cold plugged, the host usually turns the port into idle state and will not detect a remote debug capability coming up. To prevent that, one has to disable automatic power management. For an Intel xHCI host the following should do the trick:

$ echo on | tee /sys/devices/pci0000\:00/0000\:00\:14.0/usb?/power/control

The debug capability should be visible as: /dev/serial/by-id/usb-secunet_HW.DbC_1-if00-port0

For convenience, the xhcidbc-log shell script in the misc/ directory can be used to gather debug output from the device. It uses the inotifywait utility (part of inotify-tools) to wait for the device to be created and then display the output using cat. Either execute the script as root or make sure the user has the necessary access rights, e.g. is member of the dialout group.

If there is no visible console output despite the serial device being present, the tty setting may be incorrect. Issue the following command to adjust the parameters:

$ stty -F /dev/serial/by-id/usb-secunet_HW.DbC_1-if00-port0 raw -echo

stty is part of the coreutils software collection.

BIOS considerations

On hardware platforms that provide USB port-switching, e.g. Intel Haswell or Broadwell, the BIOS option USB 3.0 Mode must be set to Enabled. Otherwise the USB ports may not be routed to the xHCI controller and thus no connected device will be recognized during initialization.

ModemManager considerations

The ModemManager service may interact with the USB serial device created by the debugging capability. To avoid any interference, the service should be stopped:

$ sudo systemctl stop ModemManager.service
2017-10-27 Adrian-Ken... Remove TODO item devel master
2017-10-27 Adrian-Ken... Disable GNATprove warning for Transfer_Info.Dump_Stats
2017-10-27 Adrian-Ken... Tighten representation of DbC context type
2017-10-27 Adrian-Ken... Initialize all HW.DbC.State
2017-10-27 Adrian-Ken... Add Null_String_Desc constant
2017-10-27 Adrian-Ken... Minor: Adjust indentation in DbC body
2017-10-27 Adrian-Ken... Initialize Transfer_Rings.State
2017-10-27 Adrian-Ken... Add Null_TP constant
2017-10-27 Adrian-Ken... Disable "no effect" warning for busy loop
2017-10-27 Adrian-Ken... Disable SPARK for Copy_DMA_[In|Out] body
2017-10-27 Adrian-Ken... Use Word32 modular type for stats counters
2017-10-27 Adrian-Ken... Simplify Walk_Finished procedure
2017-10-27 Adrian-Ken... Fix SPARK warning regarding global and non-volatile...
2017-10-27 Adrian-Ken... Fix SPARK warning regarding interfering context
2017-10-27 Adrian-Ken... Fix SPARK warning regarding nonvolatile functions
2017-10-27 Adrian-Ken... Drop unneeded use type clauses
7 days ago muen
13 months ago muen-test
5 years ago devel
5 years ago master