Add Documentation/usb/early-xdbc.txt. This document includes the user guide for USB3 debug port. Cc: linux-doc@xxxxxxxxxxxxxxx Signed-off-by: Lu Baolu <baolu.lu@xxxxxxxxxxxxxxx> --- Documentation/usb/early-xdbc.txt | 78 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 Documentation/usb/early-xdbc.txt diff --git a/Documentation/usb/early-xdbc.txt b/Documentation/usb/early-xdbc.txt new file mode 100644 index 0000000..2e2043d --- /dev/null +++ b/Documentation/usb/early-xdbc.txt @@ -0,0 +1,78 @@ +This is a HOWTO for using the earlyprintk=xdbc boot option with a +USB3 debug port on x86 systems. + +Before using any kernel functionalities based on DbC, users need to +check 1) whether debug port is supported by the xHCI host, 2) which +port is used for debug port (normally the first USB3 root port). +Users must have a USB 3.0 super-speed A-to-A debugging cable to +connect the debug cable with debug host. + +On debug target system, users need to custom a debugging kernel with +CONFIG_EARLY_PRINTK_XDBC enabled. + +Users also need to add below kernel parameter: + + "earlyprintk=xdbc" + +If there are multiple xHCI controllers in the system, user can append +a host contoller index to this kernel parameter. The index is started +from 0. + +On some platforms, such as Intel Sunrise Point, you need to disable usb +subsystem runtime power management on debug host when you are debugging +with DbC. + +#echo on | tee /sys/bus/usb/devices/*/power/control +#echo on > /sys/bus/pci/devices/<xhci_pci_bus_name>/power/control + +Before starting the debug target, user could connect the debug port +on debug target with a root port or port of 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 debug target, DbC hardware gets initialized. Debug +host should be able to enuerate debug target as a debug device. Debug +host will bind the debug device with usb_debug driver module and create +the /dev/ttyUSB0 device. + +If things go smoothly, users should be able to see below kernel message +on 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 debug host before the usb debug device +gets enumerated. + +===== start of bash scripts ============= +#!/bin/bash +echo on > /sys/bus/pci/devices/0000:00:14.0/power/control +echo on | tee /sys/bus/usb/devices/*/power/control + +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. + +Early printk through DbC has been verified to work with Intel Sunrise Point +chip with below limitations: + +1. Users need to disable runtime power management of the USB subsystem on +debug host. Otherwise, the debug device will fail to be enuerated. + +2. After several restarts of debug target, debug host might fail to read +the device descriptor of debug device. Users need to restart the debug host. -- 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
