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

[Lu Baolu <baolu.lu@linux.intel.com>]

Hi,

On 10/20/2016 04:30 PM, Jani Nikula wrote:
> On Thu, 20 Oct 2016, Lu Baolu <baolu.lu@linux.intel.com> wrote:
>> Hi Jani,
>>
>> On 10/19/2016 03:48 PM, Jani Nikula wrote:
>>> On Wed, 19 Oct 2016, Lu Baolu <baolu.lu@linux.intel.com> 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?
> Read Documentation/kernel-documentation.rxt. Install Sphinx. Run 'make
> htmldocs'.

Got it. Thank you.

Best regards,
Lu Baolu

>
> BR,
> Jani.
>
>
>> Best regards,
>> Lu Baolu
>>
>>> BR,
>>> Jani.
>>>
>>>> Cc: linux-doc@vger.kernel.org
>>>> Signed-off-by: Lu Baolu <baolu.lu@linux.intel.com>
>>>> ---
>>>>  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@linux.intel.com>
>>> :Author: Lu Baolu <baolu.lu@linux.intel.com>
>>>
>>> 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.