^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) USB3 debug port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) :Author: Lu Baolu <baolu.lu@linux.intel.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) :Date: March 2017
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) GENERAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) This is a HOWTO for using the USB3 debug port on x86 systems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) Before using any kernel debugging functionality based on USB3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) debug port, you need to::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) 1) check whether any USB3 debug port is available in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) your system;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) 2) check which port is used for debugging purposes;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) 3) have a USB 3.0 super-speed A-to-A debugging cable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) INTRODUCTION
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) The xHCI debug capability (DbC) is an optional but standalone
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) functionality provided by the xHCI host controller. The xHCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) specification describes DbC in the section 7.6.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) When DbC is initialized and enabled, it will present a debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) device through the debug port (normally the first USB3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) super-speed port). The debug device is fully compliant with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) the USB framework and provides the equivalent of a very high
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) performance full-duplex serial link between the debug target
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) (the system under debugging) and a debug host.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) EARLY PRINTK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) DbC has been designed to log early printk messages. One use for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) this feature is kernel debugging. For example, when your machine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) crashes very early before the regular console code is initialized.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) Other uses include simpler, lockless logging instead of a full-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) blown printk console driver and klogd.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) On the debug target system, you need to customize a debugging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) kernel with CONFIG_EARLY_PRINTK_USB_XDBC enabled. And, add below
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) kernel boot parameter::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) "earlyprintk=xdbc"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) If there are multiple xHCI controllers in your system, you can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) append a host contoller index to this kernel parameter. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) index starts from 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) Current design doesn't support DbC runtime suspend/resume. As
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) the result, you'd better disable runtime power management for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) USB subsystem by adding below kernel boot parameter::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) "usbcore.autosuspend=-1"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) Before starting the debug target, you should connect the debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) port to a USB port (root port or port of any external hub) on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) the debug host. The cable used to connect these two ports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) should be a USB 3.0 super-speed A-to-A debugging cable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) During early boot of the debug target, DbC will be detected and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) initialized. After initialization, the debug host should be able
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) to enumerate the debug device in debug target. The debug host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) will then bind the debug device with the usb_debug driver module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) and create the /dev/ttyUSB device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) If the debug device enumeration goes smoothly, you should be able
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) to see below kernel messages on the debug host::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) # tail -f /var/log/kern.log
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) [ 1815.983374] usb 4-3: new SuperSpeed USB device number 4 using xhci_hcd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) [ 1815.999595] usb 4-3: LPM exit latency is zeroed, disabling LPM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) [ 1815.999899] usb 4-3: New USB device found, idVendor=1d6b, idProduct=0004
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) [ 1815.999902] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) [ 1815.999903] usb 4-3: Product: Remote GDB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) [ 1815.999904] usb 4-3: Manufacturer: Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) [ 1815.999905] usb 4-3: SerialNumber: 0001
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) [ 1816.000240] usb_debug 4-3:1.0: xhci_dbc converter detected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) [ 1816.000360] usb 4-3: xhci_dbc converter now attached to ttyUSB0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) You can use any communication program, for example minicom, to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) read and view the messages. Below simple bash scripts can help
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) you to check the sanity of the setup.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) .. code-block:: sh
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) ===== start of bash scripts =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) #!/bin/bash
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) while true ; do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) while [ ! -d /sys/class/tty/ttyUSB0 ] ; do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) :
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) cat /dev/ttyUSB0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) ===== end of bash scripts ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) Serial TTY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) The DbC support has been added to the xHCI driver. You can get a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) debug device provided by the DbC at runtime.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) In order to use this, you need to make sure your kernel has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) configured to support USB_XHCI_DBGCAP. A sysfs attribute under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) the xHCI device node is used to enable or disable DbC. By default,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) DbC is disabled::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) disabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) Enable DbC with the following command::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) root@target:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) You can check the DbC state at anytime::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) Connect the debug target to the debug host with a USB 3.0 super-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) speed A-to-A debugging cable. You can see /dev/ttyDBC0 created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) on the debug target. You will see below kernel message lines::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) root@target: tail -f /var/log/kern.log
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) [ 182.730103] xhci_hcd 0000:00:14.0: DbC connected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) [ 191.169420] xhci_hcd 0000:00:14.0: DbC configured
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) [ 191.169597] xhci_hcd 0000:00:14.0: DbC now attached to /dev/ttyDBC0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) Accordingly, the DbC state has been brought up to::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) configured
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) On the debug host, you will see the debug device has been enumerated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) You will see below kernel message lines::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) root@host: tail -f /var/log/kern.log
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) [ 79.454780] usb 2-2.1: new SuperSpeed USB device number 3 using xhci_hcd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) [ 79.475003] usb 2-2.1: LPM exit latency is zeroed, disabling LPM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) [ 79.475389] usb 2-2.1: New USB device found, idVendor=1d6b, idProduct=0010
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) [ 79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) [ 79.475391] usb 2-2.1: Product: Linux USB Debug Target
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) [ 79.475392] usb 2-2.1: Manufacturer: Linux Foundation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) [ 79.475393] usb 2-2.1: SerialNumber: 0001
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) The debug device works now. You can use any communication or debugging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) program to talk between the host and the target.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags