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.
153