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