153 lines · plain
1===============2USB3 debug port3===============4 5:Author: Lu Baolu <baolu.lu@linux.intel.com>6:Date: March 20177 8GENERAL9=======10 11This is a HOWTO for using the USB3 debug port on x86 systems.12 13Before using any kernel debugging functionality based on USB314debug port, you need to::15 16 1) check whether any USB3 debug port is available in17 your system;18 2) check which port is used for debugging purposes;19 3) have a USB 3.0 super-speed A-to-A debugging cable.20 21INTRODUCTION22============23 24The xHCI debug capability (DbC) is an optional but standalone25functionality provided by the xHCI host controller. The xHCI26specification describes DbC in the section 7.6.27 28When DbC is initialized and enabled, it will present a debug29device through the debug port (normally the first USB330super-speed port). The debug device is fully compliant with31the USB framework and provides the equivalent of a very high32performance full-duplex serial link between the debug target33(the system under debugging) and a debug host.34 35EARLY PRINTK36============37 38DbC has been designed to log early printk messages. One use for39this feature is kernel debugging. For example, when your machine40crashes very early before the regular console code is initialized.41Other uses include simpler, lockless logging instead of a full-42blown printk console driver and klogd.43 44On the debug target system, you need to customize a debugging45kernel with CONFIG_EARLY_PRINTK_USB_XDBC enabled. And, add below46kernel boot parameter::47 48 "earlyprintk=xdbc"49 50If there are multiple xHCI controllers in your system, you can51append a host controller index to this kernel parameter. This52index starts from 0.53 54Current design doesn't support DbC runtime suspend/resume. As55the result, you'd better disable runtime power management for56USB subsystem by adding below kernel boot parameter::57 58 "usbcore.autosuspend=-1"59 60Before starting the debug target, you should connect the debug61port to a USB port (root port or port of any external hub) on62the debug host. The cable used to connect these two ports63should be a USB 3.0 super-speed A-to-A debugging cable.64 65During early boot of the debug target, DbC will be detected and66initialized. After initialization, the debug host should be able67to enumerate the debug device in debug target. The debug host68will then bind the debug device with the usb_debug driver module69and create the /dev/ttyUSB device.70 71If the debug device enumeration goes smoothly, you should be able72to see below kernel messages on the debug host::73 74 # tail -f /var/log/kern.log75 [ 1815.983374] usb 4-3: new SuperSpeed USB device number 4 using xhci_hcd76 [ 1815.999595] usb 4-3: LPM exit latency is zeroed, disabling LPM.77 [ 1815.999899] usb 4-3: New USB device found, idVendor=1d6b, idProduct=000478 [ 1815.999902] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=379 [ 1815.999903] usb 4-3: Product: Remote GDB80 [ 1815.999904] usb 4-3: Manufacturer: Linux81 [ 1815.999905] usb 4-3: SerialNumber: 000182 [ 1816.000240] usb_debug 4-3:1.0: xhci_dbc converter detected83 [ 1816.000360] usb 4-3: xhci_dbc converter now attached to ttyUSB084 85You can use any communication program, for example minicom, to86read and view the messages. Below simple bash scripts can help87you to check the sanity of the setup.88 89.. code-block:: sh90 91 ===== start of bash scripts =============92 #!/bin/bash93 94 while true ; do95 while [ ! -d /sys/class/tty/ttyUSB0 ] ; do96 :97 done98 cat /dev/ttyUSB099 done100 ===== end of bash scripts ===============101 102Serial TTY103==========104 105The DbC support has been added to the xHCI driver. You can get a106debug device provided by the DbC at runtime.107 108In order to use this, you need to make sure your kernel has been109configured to support USB_XHCI_DBGCAP. A sysfs attribute under110the xHCI device node is used to enable or disable DbC. By default,111DbC is disabled::112 113 root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc114 disabled115 116Enable DbC with the following command::117 118 root@target:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc119 120You can check the DbC state at anytime::121 122 root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc123 enabled124 125Connect the debug target to the debug host with a USB 3.0 super-126speed A-to-A debugging cable. You can see /dev/ttyDBC0 created127on the debug target. You will see below kernel message lines::128 129 root@target: tail -f /var/log/kern.log130 [ 182.730103] xhci_hcd 0000:00:14.0: DbC connected131 [ 191.169420] xhci_hcd 0000:00:14.0: DbC configured132 [ 191.169597] xhci_hcd 0000:00:14.0: DbC now attached to /dev/ttyDBC0133 134Accordingly, the DbC state has been brought up to::135 136 root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc137 configured138 139On the debug host, you will see the debug device has been enumerated.140You will see below kernel message lines::141 142 root@host: tail -f /var/log/kern.log143 [ 79.454780] usb 2-2.1: new SuperSpeed USB device number 3 using xhci_hcd144 [ 79.475003] usb 2-2.1: LPM exit latency is zeroed, disabling LPM.145 [ 79.475389] usb 2-2.1: New USB device found, idVendor=1d6b, idProduct=0010146 [ 79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3147 [ 79.475391] usb 2-2.1: Product: Linux USB Debug Target148 [ 79.475392] usb 2-2.1: Manufacturer: Linux Foundation149 [ 79.475393] usb 2-2.1: SerialNumber: 0001150 151The debug device works now. You can use any communication or debugging152program to talk between the host and the target.153