Documentation/driver-api/usb/usb3-debug-port.rst

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