[PATCH 1/1] usb: doc: Update document for USB3 debug port usage
Update Documentation/driver-api/usb/usb3-debug-port.rst. This update includes the guide for using xHCI debug capability based TTY serial link. Cc: Mathias Nyman <mathias.ny...@linux.intel.com> Cc: Greg Kroah-Hartman <gre...@linuxfoundation.org> Signed-off-by: Lu Baolu <baolu...@linux.intel.com> --- Documentation/driver-api/usb/usb3-debug-port.rst | 52 1 file changed, 52 insertions(+) diff --git a/Documentation/driver-api/usb/usb3-debug-port.rst b/Documentation/driver-api/usb/usb3-debug-port.rst index feb1a36..b9fd131 100644 --- a/Documentation/driver-api/usb/usb3-debug-port.rst +++ b/Documentation/driver-api/usb/usb3-debug-port.rst @@ -98,3 +98,55 @@ you to check the sanity of the setup. cat /dev/ttyUSB0 done = end of bash scripts === + +Serial TTY +== + +The DbC support has been added to the xHCI driver. You can get a +debug device provided by the DbC at runtime. + +In order to use this, you need to make sure your kernel has been +configured to support USB_XHCI_DBGCAP. A sysfs attribute under +the xHCI device node is used to enable or disable DbC. By default, +DbC is disabled:: + + root@target:/sys/bus/pci/devices/:00:14.0# cat dbc + disabled + +Enable DbC with the following command:: + + root@target:/sys/bus/pci/devices/:00:14.0# echo enable > dbc + +You can check the DbC state at anytime:: + + root@target:/sys/bus/pci/devices/:00:14.0# cat dbc + enabled + +Connect the debug target to the debug host with a USB 3.0 super- +speed A-to-A debugging cable. You can see /dev/ttyDBC0 created +on the debug target. You will see below kernel message lines:: + + root@target: tail -f /var/log/kern.log + [ 182.730103] xhci_hcd :00:14.0: DbC connected + [ 191.169420] xhci_hcd :00:14.0: DbC configured + [ 191.169597] xhci_hcd :00:14.0: DbC now attached to /dev/ttyDBC0 + +Accordingly, the DbC state has been brought up to:: + + root@target:/sys/bus/pci/devices/:00:14.0# cat dbc + configured + +On the debug host, you will see the debug device has been enumerated. +You will see below kernel message lines:: + + root@host: tail -f /var/log/kern.log + [ 79.454780] usb 2-2.1: new SuperSpeed USB device number 3 using xhci_hcd + [ 79.475003] usb 2-2.1: LPM exit latency is zeroed, disabling LPM. + [ 79.475389] usb 2-2.1: New USB device found, idVendor=1d6b, idProduct=0010 + [ 79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 79.475391] usb 2-2.1: Product: Linux USB Debug Target + [ 79.475392] usb 2-2.1: Manufacturer: Linux Foundation + [ 79.475393] usb 2-2.1: SerialNumber: 0001 + +The debug device works now. You can use any communication or debugging +program to talk between the host and the target. -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v8 5/5] usb: doc: add document for USB3 debug port usage
Add Documentation/usb/usb3-debug-port.rst. This document includes the guide for using USB3 debug port. Cc: linux-doc@vger.kernel.org Signed-off-by: Lu Baolu <baolu...@linux.intel.com> --- Documentation/usb/usb3-debug-port.rst | 100 ++ 1 file changed, 100 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 000..feb1a36 --- /dev/null +++ b/Documentation/usb/usb3-debug-port.rst @@ -0,0 +1,100 @@ +=== +USB3 debug port +=== + +:Author: Lu Baolu <baolu...@linux.intel.com> +:Date: March 2017 + +GENERAL +=== + +This is a HOWTO for using the USB3 debug port on x86 systems. + +Before using any kernel debugging functionality based on USB3 +debug port, you need to:: + + 1) check whether any USB3 debug port is available in + your system; + 2) check which port is used for debugging purposes; + 3) have a USB 3.0 super-speed A-to-A debugging cable. + +INTRODUCTION + + +The xHCI debug capability (DbC) is an optional but standalone +functionality provided by the xHCI host controller. The xHCI +specification describes DbC in the section 7.6. + +When DbC is initialized and enabled, it will present a debug +device through the debug port (normally the first USB3 +super-speed port). The debug device is fully compliant with +the USB framework and provides the equivalent of a very high +performance full-duplex serial link between the debug target +(the system under debugging) and a debug host. + +EARLY PRINTK + + +DbC has been designed to log early printk messages. One use for +this feature is kernel debugging. For example, when your machine +crashes very early before the regular console code is initialized. +Other uses include simpler, lockless logging instead of a full- +blown printk console driver and klogd. + +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 your system, you can +append a host contoller index to this kernel parameter. This +index starts from 0. + +Current design doesn't support DbC runtime suspend/resume. As +the result, you'd better disable runtime power management for +USB subsystem by adding below kernel boot parameter:: + + "usbcore.autosuspend=-1" + +Before starting the debug target, you should connect the debug +port to a USB port (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 will be detected and +initialized. After initialization, the debug host should be able +to enumerate the debug device in debug target. The debug host +will then bind the debug device with the usb_debug driver module +and create the /dev/ttyUSB 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.02] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 1815.03] usb 4-3: Product: Remote GDB + [ 1815.04] usb 4-3: Manufacturer: Linux + [ 1815.05] 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 use any communication program, for example minicom, to +read and view the messages. Below simple bash scripts can help +you to check the sanity of the setup. + +.. code-block:: sh + + = start of bash scripts = + #!/bin/bash + + while true ; do + while [ ! -d /sys/class/tty/ttyUSB0 ] ; do + : + done + cat /dev/ttyUSB0 + done + = end of bash scripts === -- 2.1.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v7 5/5] usb: doc: add document for USB3 debug port usage
Hi, On 02/14/2017 02:13 PM, Peter Chen wrote: > >> On 02/14/2017 11:45 AM, Peter Chen wrote: >>> On Tue, Feb 14, 2017 at 10:27 AM, Lu Baolu <baolu...@linux.intel.com> wrote: >>> >>>> Add Documentation/usb/usb3-debug-port.rst. This document includes the >>>> user guide for USB3 debug port. >>>> >>>> Cc: linux-doc@vger.kernel.org >>>> Signed-off-by: Lu Baolu <baolu...@linux.intel.com> >>>> --- >>>> 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 000..9eddb3a >>>> --- /dev/null >>>> +++ b/Documentation/usb/usb3-debug-port.rst >>>> @@ -0,0 +1,98 @@ >>>> +=== >>>> +USB3 debug port >>>> +=== >>>> + >>>> +:Author: Lu Baolu <baolu...@linux.intel.com> >>>> +: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" >>>> + >>>> >>> Just curious, why autosuspend needs to be disabled for this function? >> This implementation doesn't support suspend/resume yet. > > Why host side needs to disable it too? If host side runtime suspend/resume is enabled, it might ask the debug device to suspend. This will cause the debug device dead. The suspend/resume of the debug device depends on xhci driver. I will make it happen in separated patches with more tests. It's in my TODO list. Best regards, Lu Baolu -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v7 5/5] usb: doc: add document for USB3 debug port usage
Hi, On 02/14/2017 11:45 AM, Peter Chen wrote: > On Tue, Feb 14, 2017 at 10:27 AM, Lu Baolu <baolu...@linux.intel.com> wrote: > >> Add Documentation/usb/usb3-debug-port.rst. This document includes >> the user guide for USB3 debug port. >> >> Cc: linux-doc@vger.kernel.org >> Signed-off-by: Lu Baolu <baolu...@linux.intel.com> >> --- >> 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 000..9eddb3a >> --- /dev/null >> +++ b/Documentation/usb/usb3-debug-port.rst >> @@ -0,0 +1,98 @@ >> +=== >> +USB3 debug port >> +=== >> + >> +:Author: Lu Baolu <baolu...@linux.intel.com> >> +: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" >> + >> > Just curious, why autosuspend needs to be disabled for this function? This implementation doesn't support suspend/resume yet. Best regards, Lu Baolu > > BR, > Peter Chen > -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v7 5/5] usb: doc: add document for USB3 debug port usage
Add Documentation/usb/usb3-debug-port.rst. This document includes the user guide for USB3 debug port. Cc: linux-doc@vger.kernel.org Signed-off-by: Lu Baolu <baolu...@linux.intel.com> --- 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 000..9eddb3a --- /dev/null +++ b/Documentation/usb/usb3-debug-port.rst @@ -0,0 +1,98 @@ +=== +USB3 debug port +=== + +:Author: Lu Baolu <baolu...@linux.intel.com> +: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.02] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 1815.03] usb 4-3: Product: Remote GDB + [ 1815.04] usb 4-3: Manufacturer: Linux + [ 1815.05] 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-...@vger.kernel.org> +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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v6 4/4] usb: doc: add document for USB3 debug port usage
Add Documentation/usb/usb3-debug-port.rst. This document includes the user guide for USB3 debug port. Cc: linux-doc@vger.kernel.org Signed-off-by: Lu Baolu <baolu...@linux.intel.com> --- 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 000..9eddb3a --- /dev/null +++ b/Documentation/usb/usb3-debug-port.rst @@ -0,0 +1,98 @@ +=== +USB3 debug port +=== + +:Author: Lu Baolu <baolu...@linux.intel.com> +: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.02] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 1815.03] usb 4-3: Product: Remote GDB + [ 1815.04] usb 4-3: Manufacturer: Linux + [ 1815.05] 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-...@vger.kernel.org> +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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v5 4/4] usb: doc: add document for USB3 debug port usage
Hi Ingo, On 01/19/2017 05:41 PM, Ingo Molnar wrote: > * Lu Baolu <baolu...@linux.intel.com> wrote: > >> Add Documentation/usb/usb3-debug-port.rst. This document includes >> the user guide for USB3 debug port. >> >> Cc: linux-doc@vger.kernel.org >> Signed-off-by: Lu Baolu <baolu...@linux.intel.com> >> --- >> Documentation/usb/usb3-debug-port.rst | 95 >> +++ >> 1 file changed, 95 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 000..70eabe4 >> --- /dev/null >> +++ b/Documentation/usb/usb3-debug-port.rst >> @@ -0,0 +1,95 @@ >> +=== >> +USB3 debug port >> +=== >> + >> +:Author: Lu Baolu <baolu...@linux.intel.com> >> +:Date: October 2016 >> + >> +GENERAL >> +=== >> + >> +This is a HOWTO for using USB3 debug port on x86 systems. >> + >> +Before using any kernel debugging functionalities based on USB3 > s/debugging functionalities > /debugging functionality > >> +debug port, you need to check 1) whether debug port is supported >> +by the xHCI host, 2) which port is used for debugging purpose > s/debugging purpose > /debugging purposes > >> +On debug target system, you need to customize a debugging kernel > s/On debug target system > On the debug target system > > (There are more typos/grammar errors in the document, please re-read it.) Sure. Thank you. Best regards, Lu Baolu -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v5 4/4] usb: doc: add document for USB3 debug port usage
Add Documentation/usb/usb3-debug-port.rst. This document includes the user guide for USB3 debug port. Cc: linux-doc@vger.kernel.org Signed-off-by: Lu Baolu <baolu...@linux.intel.com> --- Documentation/usb/usb3-debug-port.rst | 95 +++ 1 file changed, 95 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 000..70eabe4 --- /dev/null +++ b/Documentation/usb/usb3-debug-port.rst @@ -0,0 +1,95 @@ +=== +USB3 debug port +=== + +:Author: Lu Baolu <baolu...@linux.intel.com> +:Date: October 2016 + +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:: + + "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:: + + # 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.02] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 1815.03] usb 4-3: Product: Remote GDB + [ 1815.04] usb 4-3: Manufacturer: Linux + [ 1815.05] 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. + +.. 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-...@vger.kernel.org> +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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v4 4/4] usb: doc: add document for USB3 debug port usage
Add Documentation/usb/usb3-debug-port.rst. This document includes the user guide for USB3 debug port. Cc: linux-doc@vger.kernel.org Signed-off-by: Lu Baolu <baolu...@linux.intel.com> --- Documentation/usb/usb3-debug-port.rst | 95 +++ 1 file changed, 95 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 000..70eabe4 --- /dev/null +++ b/Documentation/usb/usb3-debug-port.rst @@ -0,0 +1,95 @@ +=== +USB3 debug port +=== + +:Author: Lu Baolu <baolu...@linux.intel.com> +:Date: October 2016 + +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:: + + "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:: + + # 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.02] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 1815.03] usb 4-3: Product: Remote GDB + [ 1815.04] usb 4-3: Manufacturer: Linux + [ 1815.05] 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. + +.. 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-...@vger.kernel.org> +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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RESEND PATCH v3 4/4] usb: doc: add document for USB3 debug port usage
Hi, On 10/25/2016 05:32 PM, Jani Nikula wrote: > On Tue, 25 Oct 2016, Lu Baolu <baolu...@linux.intel.com> wrote: >> Add Documentation/usb/usb3-debug-port.txt. This document includes >> the user guide for USB3 debug port. > It's in reStructuredText, please name it .rst. Sure. Best regards, Lu Baolu > > Thanks, > Jani. > >> Cc: linux-doc@vger.kernel.org >> Signed-off-by: Lu Baolu <baolu...@linux.intel.com> >> --- >> Documentation/usb/usb3-debug-port.txt | 89 >> +++ >> 1 file changed, 89 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 000..29ebbf4 >> --- /dev/null >> +++ b/Documentation/usb/usb3-debug-port.txt >> @@ -0,0 +1,89 @@ >> +=== >> +USB3 debug port >> +=== >> + >> +:Author: Lu Baolu <baolu...@linux.intel.com> >> +:Date: October 2016 >> + >> +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:: >> + >> +"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:: >> + >> +# 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.02] usb 4-3: New USB device strings: Mfr=1, Product=2, >> SerialNumber=3 >> +[ 1815.03] usb 4-3: Product: Remote GDB >> +[ 1815.04] usb 4-3: Manufacturer: Linux >> +[ 1815.05] 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. >> + >> +.. 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. -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RESEND PATCH v2 4/4] usb: doc: add document for USB3 debug port usage
Hi Jani, On 10/19/2016 03:48 PM, Jani Nikula wrote: > On Wed, 19 Oct 2016, Lu Baolu <baolu...@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? Best regards, Lu Baolu > > BR, > Jani. > >> Cc: linux-doc@vger.kernel.org >> Signed-off-by: Lu Baolu <baolu...@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 000..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...@linux.intel.com> > :Author: Lu Baolu <baolu...@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.02] usb 4-3: New USB device strings: Mfr=1, Product=2, >> SerialNumber=3 >> +[ 1815.999
[RESEND PATCH v2 4/4] usb: doc: add document for USB3 debug port usage
Add Documentation/usb/usb3-debug-port.txt. This document includes the user guide for USB3 debug port. Cc: linux-doc@vger.kernel.org Signed-off-by: Lu Baolu <baolu...@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 000..df5ce27 --- /dev/null +++ b/Documentation/usb/usb3-debug-port.txt @@ -0,0 +1,87 @@ + USB3 debug port + + Lu Baolu <baolu...@linux.intel.com> + + Last-updated: October 2016 + +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. + +"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. + +# 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.02] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 +[ 1815.03] usb 4-3: Product: Remote GDB +[ 1815.04] usb 4-3: Manufacturer: Linux +[ 1815.05] 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. + += 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. -- 2.1.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
