Commit | Line | Data |
---|---|---|
1b326277 LB |
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 | |
7852fe3a | 51 | append a host controller index to this kernel parameter. This |
1b326277 LB |
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 =============== | |
90b2a01e LB |
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. |