Hi Jani, On 10/19/2016 03:48 PM, Jani Nikula wrote: > On Wed, 19 Oct 2016, Lu Baolu <baolu.lu@xxxxxxxxxxxxxxx> wrote: >> Add Documentation/usb/usb3-debug-port.txt. This document includes >> the user guide for USB3 debug port. > If you're adding completely new files, please at least consider writing > them in reStructuredText, so we can easily bolt them to the Sphinx > build. Just a few tweaks would be required, comments inline below. Thanks for your comments. I will refactor my document according to your comments. By the way, are there any tools that I can use to check the document format? Best regards, Lu Baolu > > BR, > Jani. > >> Cc: linux-doc@xxxxxxxxxxxxxxx >> Signed-off-by: Lu Baolu <baolu.lu@xxxxxxxxxxxxxxx> >> --- >> Documentation/usb/usb3-debug-port.txt | 87 +++++++++++++++++++++++++++++++++++ >> 1 file changed, 87 insertions(+) >> create mode 100644 Documentation/usb/usb3-debug-port.txt >> >> diff --git a/Documentation/usb/usb3-debug-port.txt b/Documentation/usb/usb3-debug-port.txt >> new file mode 100644 >> index 0000000..df5ce27 >> --- /dev/null >> +++ b/Documentation/usb/usb3-debug-port.txt >> @@ -0,0 +1,87 @@ >> + USB3 debug port > Make that a title with > > =============== > USB3 debug port > =============== > >> + >> + Lu Baolu <baolu.lu@xxxxxxxxxxxxxxx> > :Author: Lu Baolu <baolu.lu@xxxxxxxxxxxxxxx> > > Although git blame will give a more accurate idea after the file's been > edited by others. > >> + >> + Last-updated: October 2016 > :Date: October 2016 > > Again, this is what git does. > >> + >> +GENERAL >> +======= >> + >> +This is a HOWTO for using USB3 debug port on x86 systems. >> + >> +Before using any kernel debugging functionalities 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 purpose >> +(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, a debug target stands for >> +the system under debugging; while, a 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 debug target system, you need to customize a debugging kernel >> +with CONFIG_EARLY_PRINTK_XDBC enabled. And add below kernel boot >> +parameter. > Add :: at the end of previous line to make the below indented block > preformatted text. Ditto for the others. > >> + >> + "earlyprintk=xdbc" >> + >> +If there are multiple xHCI controllers in the system, you can >> +append a host contoller index to this kernel parameter. This >> +index is started from 0. >> + >> +If you are going to leverage 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 debug host side, you don't need to customize the kernel, but >> +you need to 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 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 debug target, DbC (the debug engine for USB3 >> +debug port) hardware gets initialized. Debug host should be able >> +to enumerate the debug target as a debug device. Debug host will >> +then bind the debug device with the usb_debug driver module and >> +create the /dev/ttyUSB0 device. >> + >> +If device enumeration goes smoothly, you should be able to see >> +below kernel messages on debug host. > Again, add :: and indent the below lines by some spaces. > >> + >> +# 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 to read the kernel >> +log sent from debug target. > Same here. Alternatively, if you do > > .. code-block:: sh > > and indent the block, you'll get syntax highlighting in the output. > >> + >> +===== 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. -- 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
