0001 ===============
0002 USB3 debug port
0003 ===============
0004
0005 :Author: Lu Baolu <baolu.lu@linux.intel.com>
0006 :Date: March 2017
0007
0008 GENERAL
0009 =======
0010
0011 This is a HOWTO for using the USB3 debug port on x86 systems.
0012
0013 Before using any kernel debugging functionality based on USB3
0014 debug port, you need to::
0015
0016 1) check whether any USB3 debug port is available in
0017 your system;
0018 2) check which port is used for debugging purposes;
0019 3) have a USB 3.0 super-speed A-to-A debugging cable.
0020
0021 INTRODUCTION
0022 ============
0023
0024 The xHCI debug capability (DbC) is an optional but standalone
0025 functionality provided by the xHCI host controller. The xHCI
0026 specification describes DbC in the section 7.6.
0027
0028 When DbC is initialized and enabled, it will present a debug
0029 device through the debug port (normally the first USB3
0030 super-speed port). The debug device is fully compliant with
0031 the USB framework and provides the equivalent of a very high
0032 performance full-duplex serial link between the debug target
0033 (the system under debugging) and a debug host.
0034
0035 EARLY PRINTK
0036 ============
0037
0038 DbC has been designed to log early printk messages. One use for
0039 this feature is kernel debugging. For example, when your machine
0040 crashes very early before the regular console code is initialized.
0041 Other uses include simpler, lockless logging instead of a full-
0042 blown printk console driver and klogd.
0043
0044 On the debug target system, you need to customize a debugging
0045 kernel with CONFIG_EARLY_PRINTK_USB_XDBC enabled. And, add below
0046 kernel boot parameter::
0047
0048 "earlyprintk=xdbc"
0049
0050 If there are multiple xHCI controllers in your system, you can
0051 append a host contoller index to this kernel parameter. This
0052 index starts from 0.
0053
0054 Current design doesn't support DbC runtime suspend/resume. As
0055 the result, you'd better disable runtime power management for
0056 USB subsystem by adding below kernel boot parameter::
0057
0058 "usbcore.autosuspend=-1"
0059
0060 Before starting the debug target, you should connect the debug
0061 port to a USB port (root port or port of any external hub) on
0062 the debug host. The cable used to connect these two ports
0063 should be a USB 3.0 super-speed A-to-A debugging cable.
0064
0065 During early boot of the debug target, DbC will be detected and
0066 initialized. After initialization, the debug host should be able
0067 to enumerate the debug device in debug target. The debug host
0068 will then bind the debug device with the usb_debug driver module
0069 and create the /dev/ttyUSB device.
0070
0071 If the debug device enumeration goes smoothly, you should be able
0072 to see below kernel messages on the debug host::
0073
0074 # tail -f /var/log/kern.log
0075 [ 1815.983374] usb 4-3: new SuperSpeed USB device number 4 using xhci_hcd
0076 [ 1815.999595] usb 4-3: LPM exit latency is zeroed, disabling LPM.
0077 [ 1815.999899] usb 4-3: New USB device found, idVendor=1d6b, idProduct=0004
0078 [ 1815.999902] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
0079 [ 1815.999903] usb 4-3: Product: Remote GDB
0080 [ 1815.999904] usb 4-3: Manufacturer: Linux
0081 [ 1815.999905] usb 4-3: SerialNumber: 0001
0082 [ 1816.000240] usb_debug 4-3:1.0: xhci_dbc converter detected
0083 [ 1816.000360] usb 4-3: xhci_dbc converter now attached to ttyUSB0
0084
0085 You can use any communication program, for example minicom, to
0086 read and view the messages. Below simple bash scripts can help
0087 you to check the sanity of the setup.
0088
0089 .. code-block:: sh
0090
0091 ===== start of bash scripts =============
0092 #!/bin/bash
0093
0094 while true ; do
0095 while [ ! -d /sys/class/tty/ttyUSB0 ] ; do
0096 :
0097 done
0098 cat /dev/ttyUSB0
0099 done
0100 ===== end of bash scripts ===============
0101
0102 Serial TTY
0103 ==========
0104
0105 The DbC support has been added to the xHCI driver. You can get a
0106 debug device provided by the DbC at runtime.
0107
0108 In order to use this, you need to make sure your kernel has been
0109 configured to support USB_XHCI_DBGCAP. A sysfs attribute under
0110 the xHCI device node is used to enable or disable DbC. By default,
0111 DbC is disabled::
0112
0113 root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
0114 disabled
0115
0116 Enable DbC with the following command::
0117
0118 root@target:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc
0119
0120 You can check the DbC state at anytime::
0121
0122 root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
0123 enabled
0124
0125 Connect the debug target to the debug host with a USB 3.0 super-
0126 speed A-to-A debugging cable. You can see /dev/ttyDBC0 created
0127 on the debug target. You will see below kernel message lines::
0128
0129 root@target: tail -f /var/log/kern.log
0130 [ 182.730103] xhci_hcd 0000:00:14.0: DbC connected
0131 [ 191.169420] xhci_hcd 0000:00:14.0: DbC configured
0132 [ 191.169597] xhci_hcd 0000:00:14.0: DbC now attached to /dev/ttyDBC0
0133
0134 Accordingly, the DbC state has been brought up to::
0135
0136 root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
0137 configured
0138
0139 On the debug host, you will see the debug device has been enumerated.
0140 You will see below kernel message lines::
0141
0142 root@host: tail -f /var/log/kern.log
0143 [ 79.454780] usb 2-2.1: new SuperSpeed USB device number 3 using xhci_hcd
0144 [ 79.475003] usb 2-2.1: LPM exit latency is zeroed, disabling LPM.
0145 [ 79.475389] usb 2-2.1: New USB device found, idVendor=1d6b, idProduct=0010
0146 [ 79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
0147 [ 79.475391] usb 2-2.1: Product: Linux USB Debug Target
0148 [ 79.475392] usb 2-2.1: Manufacturer: Linux Foundation
0149 [ 79.475393] usb 2-2.1: SerialNumber: 0001
0150
0151 The debug device works now. You can use any communication or debugging
0152 program to talk between the host and the target.
