Lu Baolu | 1b32627 | 2017-03-21 16:01:33 +0800 | [diff] [blame] | 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 =============== |