Add Documentation/usb/usb3-debug-port.rst. This document includes the user guide for USB3 debug port. Cc: linux-doc@xxxxxxxxxxxxxxx Signed-off-by: Lu Baolu <baolu.lu@xxxxxxxxxxxxxxx> --- Documentation/usb/usb3-debug-port.rst | 98 +++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 Documentation/usb/usb3-debug-port.rst diff --git a/Documentation/usb/usb3-debug-port.rst b/Documentation/usb/usb3-debug-port.rst new file mode 100644 index 0000000..9eddb3a --- /dev/null +++ b/Documentation/usb/usb3-debug-port.rst @@ -0,0 +1,98 @@ +=============== +USB3 debug port +=============== + +:Author: Lu Baolu <baolu.lu@xxxxxxxxxxxxxxx> +:Date: January 2017 + +GENERAL +======= + +This is a HOWTO for using USB3 debug port on x86 systems. + +Before using any kernel debugging functionality based on USB3 +debug port, you need to check 1) whether debug port is supported +by the xHCI host; 2) which port is used for debugging purposes +(normally the first USB3 root port). You must have a USB 3.0 +super-speed A-to-A debugging cable to connect the debug target +with a debug host. In this document, "debug target" stands for +the system under debugging, and "debug host" stands for a +stand-alone system that is able to talk to the debugging target +through the USB3 debug port. + +EARLY PRINTK +============ + +On the debug target system, you need to customize a debugging +kernel with CONFIG_EARLY_PRINTK_USB_XDBC enabled. And, add +below kernel boot parameter:: + + "earlyprintk=xdbc" + +If there are multiple xHCI controllers in the system, you can +append a host contoller index to this kernel parameter. This +index starts from 0. + +If you are going to use the "keep" option defined by the +early printk framework to keep the boot console alive after +early boot, you'd better add below kernel boot parameter:: + + "usbcore.autosuspend=-1" + +On the debug host side, you don't need to customize the kernel, +but you'd better disable usb subsystem runtime power management +by adding below kernel boot parameter:: + + "usbcore.autosuspend=-1" + +Before starting the debug target, you should connect the debug +port on the debug target with a root port or port of any external +hub on the debug host. The cable used to connect these two ports +should be a USB 3.0 super-speed A-to-A debugging cable. + +During early boot of the debug target, DbC (xHCI debug engine for +USB3 debug port) hardware will be detected and initialized. After +initialization, the debug host should be able to enumerate the +debug target as a debug device. The debug host will then bind the +debug device with the usb_debug driver module and create the +/dev/ttyUSB0 device. + +If the debug device enumeration goes smoothly, you should be able +to see below kernel messages on the debug host:: + + # tail -f /var/log/kern.log + [ 1815.983374] usb 4-3: new SuperSpeed USB device number 4 using xhci_hcd + [ 1815.999595] usb 4-3: LPM exit latency is zeroed, disabling LPM. + [ 1815.999899] usb 4-3: New USB device found, idVendor=1d6b, idProduct=0004 + [ 1815.999902] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 1815.999903] usb 4-3: Product: Remote GDB + [ 1815.999904] usb 4-3: Manufacturer: Linux + [ 1815.999905] usb 4-3: SerialNumber: 0001 + [ 1816.000240] usb_debug 4-3:1.0: xhci_dbc converter detected + [ 1816.000360] usb 4-3: xhci_dbc converter now attached to ttyUSB0 + +You can run below bash scripts on the debug host to read the kernel +log sent from debug target. + +.. code-block:: sh + + ===== start of bash scripts ============= + #!/bin/bash + + while true ; do + while [ ! -d /sys/class/tty/ttyUSB0 ] ; do + : + done + cat /dev/ttyUSB0 >> xdbc.log + done + ===== end of bash scripts =============== + +You should be able to see the early boot message in xdbc.log. + +If it doesn't work, please ask it on the <linux-usb@xxxxxxxxxxxxxxx> +mailing list. + +Below USB hosts have been verified to work:: + + Intel Corporation Sunrise Point-H USB 3.0 xHCI Controller + Intel Corporation Wildcat Point-LP USB xHCI Controller -- 2.1.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
