usb3-debug-port.rst (5398B)
1=============== 2USB3 debug port 3=============== 4 5:Author: Lu Baolu <baolu.lu@linux.intel.com> 6:Date: March 2017 7 8GENERAL 9======= 10 11This is a HOWTO for using the USB3 debug port on x86 systems. 12 13Before using any kernel debugging functionality based on USB3 14debug port, you need to:: 15 16 1) check whether any USB3 debug port is available in 17 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 21INTRODUCTION 22============ 23 24The xHCI debug capability (DbC) is an optional but standalone 25functionality provided by the xHCI host controller. The xHCI 26specification describes DbC in the section 7.6. 27 28When DbC is initialized and enabled, it will present a debug 29device through the debug port (normally the first USB3 30super-speed port). The debug device is fully compliant with 31the USB framework and provides the equivalent of a very high 32performance full-duplex serial link between the debug target 33(the system under debugging) and a debug host. 34 35EARLY PRINTK 36============ 37 38DbC has been designed to log early printk messages. One use for 39this feature is kernel debugging. For example, when your machine 40crashes 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 debugging 45kernel with CONFIG_EARLY_PRINTK_USB_XDBC enabled. And, add below 46kernel boot parameter:: 47 48 "earlyprintk=xdbc" 49 50If there are multiple xHCI controllers in your system, you can 51append a host contoller index to this kernel parameter. This 52index starts from 0. 53 54Current design doesn't support DbC runtime suspend/resume. As 55the result, you'd better disable runtime power management for 56USB subsystem by adding below kernel boot parameter:: 57 58 "usbcore.autosuspend=-1" 59 60Before starting the debug target, you should connect the debug 61port to a USB port (root port or port of any external hub) on 62the debug host. The cable used to connect these two ports 63should be a USB 3.0 super-speed A-to-A debugging cable. 64 65During early boot of the debug target, DbC will be detected and 66initialized. After initialization, the debug host should be able 67to enumerate the debug device in debug target. The debug host 68will then bind the debug device with the usb_debug driver module 69and create the /dev/ttyUSB device. 70 71If the debug device enumeration goes smoothly, you should be able 72to see below kernel messages on the debug host:: 73 74 # tail -f /var/log/kern.log 75 [ 1815.983374] usb 4-3: new SuperSpeed USB device number 4 using xhci_hcd 76 [ 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=0004 78 [ 1815.999902] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 79 [ 1815.999903] usb 4-3: Product: Remote GDB 80 [ 1815.999904] usb 4-3: Manufacturer: Linux 81 [ 1815.999905] usb 4-3: SerialNumber: 0001 82 [ 1816.000240] usb_debug 4-3:1.0: xhci_dbc converter detected 83 [ 1816.000360] usb 4-3: xhci_dbc converter now attached to ttyUSB0 84 85You can use any communication program, for example minicom, to 86read and view the messages. Below simple bash scripts can help 87you to check the sanity of the setup. 88 89.. code-block:: sh 90 91 ===== start of bash scripts ============= 92 #!/bin/bash 93 94 while true ; do 95 while [ ! -d /sys/class/tty/ttyUSB0 ] ; do 96 : 97 done 98 cat /dev/ttyUSB0 99 done 100 ===== end of bash scripts =============== 101 102Serial TTY 103========== 104 105The DbC support has been added to the xHCI driver. You can get a 106debug device provided by the DbC at runtime. 107 108In order to use this, you need to make sure your kernel has been 109configured to support USB_XHCI_DBGCAP. A sysfs attribute under 110the 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 dbc 114 disabled 115 116Enable DbC with the following command:: 117 118 root@target:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc 119 120You can check the DbC state at anytime:: 121 122 root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc 123 enabled 124 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 created 127on the debug target. You will see below kernel message lines:: 128 129 root@target: tail -f /var/log/kern.log 130 [ 182.730103] xhci_hcd 0000:00:14.0: DbC connected 131 [ 191.169420] xhci_hcd 0000:00:14.0: DbC configured 132 [ 191.169597] xhci_hcd 0000:00:14.0: DbC now attached to /dev/ttyDBC0 133 134Accordingly, the DbC state has been brought up to:: 135 136 root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc 137 configured 138 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.log 143 [ 79.454780] usb 2-2.1: new SuperSpeed USB device number 3 using xhci_hcd 144 [ 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=0010 146 [ 79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3 147 [ 79.475391] usb 2-2.1: Product: Linux USB Debug Target 148 [ 79.475392] usb 2-2.1: Manufacturer: Linux Foundation 149 [ 79.475393] usb 2-2.1: SerialNumber: 0001 150 151The debug device works now. You can use any communication or debugging 152program to talk between the host and the target.