Use Word32 modular type for stats counters
[libxhcidbg.git] / README.md
1 # Libxhcidbg - xHCI Debug Capability library
2
3 ## Introduction
4
5 This **libxhcidbg** library implements support for the xHCI debug
6 capability as specified in [*eXtensible Host Controller Interface for
7 Universal Serial Bus (xHCI)*, revision 1.1, section 7.6][1]. Libxhcidbg
8 advertises the debug capability with vendor-id:device-id ffff:dbc1 and
9 device revision 00.01. Descriptor strings are set as follows:
10
11     Product: HW.DbC
12     Manufacturer: secunet
13     SerialNumber: 1
14
15 ## Usage with Linux host
16
17 The `usb-debug` driver of Linux can be used to interact with the xHCI
18 debug capability. To work with HW.DbC, one has to specify the
19 vendor-id:device-id tuple after driver loading:
20
21     $ modprobe usb-debug
22     $ echo ffff dbc1 >/sys/bus/usb-serial/drivers/debug/new_id
23
24 When the USB debugging cable is cold plugged, the host usually turns the
25 port into idle state and will not detect a remote debug capability
26 coming up. To prevent that, one has to disable automatic power
27 management. For an Intel xHCI host the following should do the trick:
28
29     $ echo on | tee /sys/devices/pci0000\:00/0000\:00\:14.0/usb?/power/control
30
31 The debug capability should be visible as:
32 `/dev/serial/by-id/usb-secunet_HW.DbC_1-if00-port0`
33
34 For convenience, the `xhcidbc-log` shell script in the `misc/` directory
35 can be used to gather debug output from the device. It uses the
36 `inotifywait` utility (part of [*inotify-tools*][2]) to wait for the
37 device to be created and then display the output using `cat`. Either
38 execute the script as root or make sure the user has the necessary
39 access rights, e.g. is member of the `dialout` group.
40
41 If there is no visible console output despite the serial device being present,
42 the tty setting may be incorrect. Issue the following command to adjust the
43 parameters:
44
45     $ stty -F /dev/serial/by-id/usb-secunet_HW.DbC_1-if00-port0 raw -echo
46
47 `stty` is part of the [*coreutils* software collection][3].
48
49 ## BIOS considerations
50
51 On hardware platforms that provide USB port-switching, e.g. Intel Haswell
52 or Broadwell, the BIOS option *USB 3.0 Mode* **must** be set to
53 *Enabled*. Otherwise the USB ports may not be routed to the xHCI
54 controller and thus no connected device will be recognized during
55 initialization.
56
57 If your BIOS has a "USB charging mode" configuration option, it is recommended
58 to turn this feature off.
59
60 ## ModemManager considerations
61
62 The ModemManager service may interact with the USB serial device created by the
63 debugging capability. To avoid any interference, the service should be stopped:
64
65     $ sudo systemctl stop ModemManager.service
66
67 [1]: https://www-ssl.intel.com/content/www/us/en/io/universal-serial-bus/extensible-host-controler-interface-usb-xhci.html
68 [2]: https://github.com/rvoicilas/inotify-tools/wiki
69 [3]: https://www.gnu.org/software/coreutils/