1 =============== 2 USB3 debug port 3 =============== 4 5 :Author: Lu Baolu <baolu.lu@linux.intel.com> 6 :Date: March 2017 7 8 GENERAL 9 ======= 10 11 This is a HOWTO for using the USB3 debug port on x86 systems. 12 13 Before using any kernel debugging functionality based on USB3 14 debug 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 21 INTRODUCTION 22 ============ 23 24 The xHCI debug capability (DbC) is an optional but standalone 25 functionality provided by the xHCI host controller. The xHCI 26 specification describes DbC in the section 7.6. 27 28 When DbC is initialized and enabled, it will present a debug 29 device through the debug port (normally the first USB3 30 super-speed port). The debug device is fully compliant with 31 the USB framework and provides the equivalent of a very high 32 performance full-duplex serial link between the debug target 33 (the system under debugging) and a debug host. 34 35 EARLY PRINTK 36 ============ 37 38 DbC has been designed to log early printk messages. One use for 39 this feature is kernel debugging. For example, when your machine 40 crashes very early before the regular console code is initialized. 41 Other uses include simpler, lockless logging instead of a full- 42 blown printk console driver and klogd. 43 44 On the debug target system, you need to customize a debugging 45 kernel with CONFIG_EARLY_PRINTK_USB_XDBC enabled. And, add below 46 kernel boot parameter:: 47 48 "earlyprintk=xdbc" 49 50 If there are multiple xHCI controllers in your system, you can 51 append a host controller index to this kernel parameter. This 52 index starts from 0. 53 54 Current design doesn't support DbC runtime suspend/resume. As 55 the result, you'd better disable runtime power management for 56 USB subsystem by adding below kernel boot parameter:: 57 58 "usbcore.autosuspend=-1" 59 60 Before starting the debug target, you should connect the debug 61 port to a USB port (root port or port of any external hub) on 62 the debug host. The cable used to connect these two ports 63 should be a USB 3.0 super-speed A-to-A debugging cable. 64 65 During early boot of the debug target, DbC will be detected and 66 initialized. After initialization, the debug host should be able 67 to enumerate the debug device in debug target. The debug host 68 will then bind the debug device with the usb_debug driver module 69 and create the /dev/ttyUSB device. 70 71 If the debug device enumeration goes smoothly, you should be able 72 to 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 85 You can use any communication program, for example minicom, to 86 read and view the messages. Below simple bash scripts can help 87 you 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 102 Serial TTY 103 ========== 104 105 The DbC support has been added to the xHCI driver. You can get a 106 debug device provided by the DbC at runtime. 107 108 In order to use this, you need to make sure your kernel has been 109 configured to support USB_XHCI_DBGCAP. A sysfs attribute under 110 the xHCI device node is used to enable or disable DbC. By default, 111 DbC is disabled:: 112 113 root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc 114 disabled 115 116 Enable DbC with the following command:: 117 118 root@target:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc 119 120 You can check the DbC state at anytime:: 121 122 root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc 123 enabled 124 125 Connect the debug target to the debug host with a USB 3.0 super- 126 speed A-to-A debugging cable. You can see /dev/ttyDBC0 created 127 on 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 134 Accordingly, 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 139 On the debug host, you will see the debug device has been enumerated. 140 You 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 151 The debug device works now. You can use any communication or debugging 152 program to talk between the host and the target.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.