Re: [RESEND PATCH v2 4/4] usb: doc: add document for USB3 debug port usage

[Jani Nikula]

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.

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.

-- 
Jani Nikula, Intel Open Source Technology Center