usb: early: add support for early printk through USB3 debug port

drivers/usb/early/xhci-dbc.c new file +100 -0

+
+	xdbc_handle_events();
+
+	/* Check completion of the previous request. */
+	while (xdbc.flags & XDBC_FLAGS_OUT_PROCESS) {
+		if (timeout > 1000000)
+			break;
+
+		spin_unlock_irqrestore(&xdbc.lock, flags);
+		xdbc_delay(100);
+		spin_lock_irqsave(&xdbc.lock, flags);
+		timeout += 100;
+
+		xdbc_handle_events();
+	}
+
+	if (xdbc.flags & XDBC_FLAGS_OUT_PROCESS) {
+		spin_unlock_irqrestore(&xdbc.lock, flags);
+
+		/*
+		 * Oops, hardware wasn't able to complete the
+		 * previous transfer.
+		 */
+		xdbc_trace("oops: previous transfer not completed yet\n");
+
+		return -ETIMEDOUT;
+	}
+
+	ret = xdbc_bulk_transfer((void *)bytes, size, false);
+
+	spin_unlock_irqrestore(&xdbc.lock, flags);
+
+	return ret;
+}
+
+static void early_xdbc_write(struct console *con, const char *str, u32 n)
+{
+	int chunk, ret;
+	static char buf[XDBC_MAX_PACKET];
+	int use_cr = 0;
+
+	if (!xdbc.xdbc_reg)
+		return;
+	memset(buf, 0, XDBC_MAX_PACKET);
+	while (n > 0) {
+		for (chunk = 0; chunk < XDBC_MAX_PACKET && n > 0;
+				str++, chunk++, n--) {
+			if (!use_cr && *str == '\n') {
+				use_cr = 1;
+				buf[chunk] = '\r';
+				str--;
+				n++;
+				continue;
+			}
+			if (use_cr)
+				use_cr = 0;
+			buf[chunk] = *str;
+		}
+		if (chunk > 0) {
+			ret = xdbc_bulk_write(buf, chunk);
+			if (ret < 0)
+				break;
+		}
+	}
+}
+
+static struct console early_xdbc_console = {
+	.name =		"earlyxdbc",
+	.write =	early_xdbc_write,
+	.flags =	CON_PRINTBUFFER,
+	.index =	-1,
+};
+
+void __init early_xdbc_register_console(void)
+{
+	if (early_console)
+		return;
+
+	early_console = &early_xdbc_console;
+	if (early_console_keep)
+		early_console->flags &= ~CON_BOOT;
+	else
+		early_console->flags |= CON_BOOT;
+	register_console(early_console);
+}
+
+static void xdbc_scrub_function(struct work_struct *work)
+{
+	unsigned long flags;
+
+	spin_lock_irqsave(&xdbc.lock, flags);
+
+	/*
+	 * DbC is running, check the event ring and
+	 * handle the events.
+	 */
+	if (readl(&xdbc.xdbc_reg->control) & CTRL_DRC)
+		xdbc_handle_events();
+
+	/*

drivers/usb/early/xhci-dbc.c line 930

Quoted 7 lines · Lu Baolu

+++ b/drivers/usb/early/xhci-dbc.c

drivers/usb/early/xhci-dbc.c new file +6 -0

+static int xdbc_bulk_write(const char *bytes, int size)
+{
+	unsigned long flags;
+	int ret, timeout = 0;
+
+	spin_lock_irqsave(&xdbc.lock, flags);

Yikes!!

So how is this supposed to work from NMI context and the like?

(also, at the very least, that should be a raw_spinlock_t)

What do you need the spinlock for? Afaict this is a 'simple' polling event handling loop on MMIO, right?

All we really need to guarantee is that there's only a single CPU trying to do that at any one time.

Wouldn't something like:

https://marc.info/?l=linux-kernel&m=147681099108509&w=2

already take care of that? Then you can drop the lock and things will work 'nested'.

Quoted 104 lines

drivers/usb/early/xhci-dbc.c new file +104 -0

+
+	xdbc_handle_events();
+
+	/* Check completion of the previous request. */
+	while (xdbc.flags & XDBC_FLAGS_OUT_PROCESS) {
+		if (timeout > 1000000)
+			break;
+
+		spin_unlock_irqrestore(&xdbc.lock, flags);
+		xdbc_delay(100);
+		spin_lock_irqsave(&xdbc.lock, flags);
+		timeout += 100;
+
+		xdbc_handle_events();
+	}
+
+	if (xdbc.flags & XDBC_FLAGS_OUT_PROCESS) {
+		spin_unlock_irqrestore(&xdbc.lock, flags);
+
+		/*
+		 * Oops, hardware wasn't able to complete the
+		 * previous transfer.
+		 */
+		xdbc_trace("oops: previous transfer not completed yet\n");
+
+		return -ETIMEDOUT;
+	}
+
+	ret = xdbc_bulk_transfer((void *)bytes, size, false);
+
+	spin_unlock_irqrestore(&xdbc.lock, flags);
+
+	return ret;
+}
+
+static void early_xdbc_write(struct console *con, const char *str, u32 n)
+{
+	int chunk, ret;
+	static char buf[XDBC_MAX_PACKET];
+	int use_cr = 0;
+
+	if (!xdbc.xdbc_reg)
+		return;
+	memset(buf, 0, XDBC_MAX_PACKET);
+	while (n > 0) {
+		for (chunk = 0; chunk < XDBC_MAX_PACKET && n > 0;
+				str++, chunk++, n--) {
+			if (!use_cr && *str == '\n') {
+				use_cr = 1;
+				buf[chunk] = '\r';
+				str--;
+				n++;
+				continue;
+			}
+			if (use_cr)
+				use_cr = 0;
+			buf[chunk] = *str;
+		}
+		if (chunk > 0) {
+			ret = xdbc_bulk_write(buf, chunk);
+			if (ret < 0)
+				break;
+		}
+	}
+}
+
+static struct console early_xdbc_console = {
+	.name =		"earlyxdbc",
+	.write =	early_xdbc_write,
+	.flags =	CON_PRINTBUFFER,
+	.index =	-1,
+};
+
+void __init early_xdbc_register_console(void)
+{
+	if (early_console)
+		return;
+
+	early_console = &early_xdbc_console;
+	if (early_console_keep)
+		early_console->flags &= ~CON_BOOT;
+	else
+		early_console->flags |= CON_BOOT;
+	register_console(early_console);
+}
+
+static void xdbc_scrub_function(struct work_struct *work)
+{
+	unsigned long flags;
+
+	spin_lock_irqsave(&xdbc.lock, flags);
+
+	/*
+	 * DbC is running, check the event ring and
+	 * handle the events.
+	 */
+	if (readl(&xdbc.xdbc_reg->control) & CTRL_DRC)
+		xdbc_handle_events();
+
+	/*
+	 * External reset happened. Need to restart the
+	 * debugging hardware.
+	 */
+	if (unlikely(!(readl(&xdbc.xdbc_reg->control) & CTRL_DCE)))

drivers/usb/early/xhci-dbc.c line 1040

Quoted 6 lines

drivers/usb/early/xhci-dbc.c new file +6 -0

+		xdbc_handle_external_reset();
+
+	spin_unlock_irqrestore(&xdbc.lock, flags);
+
+	queue_delayed_work(xdbc_wq, &xdbc.scrub, usecs_to_jiffies(100));
+}

Excuse my total lack of USB knowledge, but WTH does this do and what do we need it for?

Hi Peter,

Thanks for your comments.

Quoted 10 lines · Peter Zijlstra

drivers/usb/early/xhci-dbc.c line 930

Quoted 7 lines · Lu Baolu

+++ b/drivers/usb/early/xhci-dbc.c

drivers/usb/early/xhci-dbc.c new file +6 -0

+static int xdbc_bulk_write(const char *bytes, int size)
+{
+	unsigned long flags;
+	int ret, timeout = 0;
+
+	spin_lock_irqsave(&xdbc.lock, flags);

Yikes!!

Quoted 3 lines

So how is this supposed to work from NMI context and the like?

(also, at the very least, that should be a raw_spinlock_t)

Totally agree. We should put it as a raw_spinlock_t().

Quoted 2 lines

What do you need the spinlock for? Afaict this is a 'simple' polling event handling loop on MMIO, right?

Not only for polling registers in MMIO, but also for handling the events in the event ring. The event ring is a memory block, which is allocated during hardware initialization and saved in a register in MMIO.

There is a single event ring for all events (read completion, write completion, port status change and transfer errors etc). The debugging hardware doesn't support interrupt, so software has to poll the event ring whenever it needs to.

Event ring polling happens at least in write interface (to make sure the previous transfer has been completed), and a worker (to check the read events and other things). That's the reason why I need a spin_lock here.

Quoted 18 lines

Quoted 18 lines

drivers/usb/early/xhci-dbc.c new file +18 -0

+static void xdbc_scrub_function(struct work_struct *work)
+{
+	unsigned long flags;
+
+	spin_lock_irqsave(&xdbc.lock, flags);
+
+	/*
+	 * DbC is running, check the event ring and
+	 * handle the events.
+	 */
+	if (readl(&xdbc.xdbc_reg->control) & CTRL_DRC)
+		xdbc_handle_events();
+
+	/*
+	 * External reset happened. Need to restart the
+	 * debugging hardware.
+	 */
+	if (unlikely(!(readl(&xdbc.xdbc_reg->control) & CTRL_DCE)))

Quoted 9 lines

drivers/usb/early/xhci-dbc.c line 1040

Quoted 6 lines

drivers/usb/early/xhci-dbc.c new file +6 -0

+		xdbc_handle_external_reset();
+
+	spin_unlock_irqrestore(&xdbc.lock, flags);
+
+	queue_delayed_work(xdbc_wq, &xdbc.scrub, usecs_to_jiffies(100));
+}

Excuse my total lack of USB knowledge, but WTH does this do and what do we need it for?

As I said above, I need a worker to check the read completion events and other hardware situations.

One hardware situation that needs to check regularly is that it might be aborted by the host controller itself. The xhci spec allows the debug hardware to share some logics with the host controller (to reduce cost?). As the result, when host controller driver resets the host (always happens in driver probe or resume) the debug hardware resets as well. Software needs to re-initialize and bring it back.

Early printk doesn't need to read anything from debug host. But if we use it for kernel debugging with kgdb (it's in my work queue), we need a read interface. We need to check the event ring regularly for read completion events.

I'm already only using early_printk() because regular printk() is an unfixable piece of crap, and now you're making early_printk() useless too.

Quoted 3 lines · Peter Zijlstra

I'm already only using early_printk() because regular printk() is an unfixable piece of crap, and now you're making early_printk() useless too.

Note that the existing USB debug port stuff doesn't seem to have a single lock in. Its just polling on readl and doing writel without any serialization what so ever.

Not that I've ever actually used it (lack of the magic cable), but it at least looks like it should mostly work.

Add Documentation/usb/usb3-debug-port.txt. This document includes the user guide for USB3 debug port.

Cc [email protected]

Signed-off-by Lu Baolu <[email protected]>

---
 Documentation/usb/usb3-debug-port.txt | 87 +++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 Documentation/usb/usb3-debug-port.txt

Documentation/usb/usb3-debug-port.txt new file +0 -0

new file mode 100644
index 0000000..df5ce27

Documentation/usb/usb3-debug-port.txt new file +12 -0

+
+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

Documentation/usb/usb3-debug-port.txt new file +22 -0

+
+    "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

Documentation/usb/usb3-debug-port.txt new file +5 -0

+
+# 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.

Documentation/usb/usb3-debug-port.txt new file +13 -0

+
+===== 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.

Quoted 2 lines · Lu Baolu

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.

Quoted 13 lines

Cc [email protected]

Signed-off-by Lu Baolu <[email protected]>

---
 Documentation/usb/usb3-debug-port.txt | 87 +++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 Documentation/usb/usb3-debug-port.txt

Documentation/usb/usb3-debug-port.txt new file +0 -0

new file mode 100644
index 0000000..df5ce27

Documentation/usb/usb3-debug-port.txt line 1

Quoted 1 line

Documentation/usb/usb3-debug-port.txt new file +1 -0

@@ -0,0 +1,87 @@
+                  USB3 debug port

Make that a title with

===============
USB3 debug port
===============

Documentation/usb/usb3-debug-port.txt line 3

Quoted 2 lines

Documentation/usb/usb3-debug-port.txt new file +2 -0

+
+         Lu Baolu <[email protected]>

:Author: Lu Baolu <[email protected]>

Although git blame will give a more accurate idea after the file's been edited by others.

Documentation/usb/usb3-debug-port.txt line 5

Quoted 2 lines

Documentation/usb/usb3-debug-port.txt new file +2 -0

+
+              Last-updated: October 2016

:Date: October 2016

Again, this is what git does.

Quoted 12 lines

Documentation/usb/usb3-debug-port.txt new file +12 -0

+
+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

Documentation/usb/usb3-debug-port.txt line 27

Quoted 10 lines

Documentation/usb/usb3-debug-port.txt new file +10 -0

+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.

Quoted 22 lines

Documentation/usb/usb3-debug-port.txt new file +22 -0

+
+    "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

Documentation/usb/usb3-debug-port.txt line 59

Quoted 10 lines

Documentation/usb/usb3-debug-port.txt new file +10 -0

+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.

Quoted 5 lines

Documentation/usb/usb3-debug-port.txt new file +5 -0

+
+# 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.

Documentation/usb/usb3-debug-port.txt line 74

Quoted 10 lines

Documentation/usb/usb3-debug-port.txt new file +10 -0

+[ 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.

Quoted 13 lines

Documentation/usb/usb3-debug-port.txt new file +13 -0

+
+===== 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.

Hi Jani,

Quoted 6 lines · Jani Nikula

Quoted 2 lines · Lu Baolu

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

Quoted 130 lines

BR,
Jani.

Quoted 13 lines

Cc [email protected]

Signed-off-by Lu Baolu <[email protected]>

---
 Documentation/usb/usb3-debug-port.txt | 87 +++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 Documentation/usb/usb3-debug-port.txt

Documentation/usb/usb3-debug-port.txt new file +0 -0

new file mode 100644
index 0000000..df5ce27

Documentation/usb/usb3-debug-port.txt line 1

Quoted 1 line

Documentation/usb/usb3-debug-port.txt new file +1 -0

@@ -0,0 +1,87 @@
+                  USB3 debug port

Make that a title with

===============
USB3 debug port
===============

Documentation/usb/usb3-debug-port.txt line 3

Quoted 2 lines

Documentation/usb/usb3-debug-port.txt new file +2 -0

+
+         Lu Baolu <[email protected]>

:Author: Lu Baolu <[email protected]>

Although git blame will give a more accurate idea after the file's been edited by others.

Documentation/usb/usb3-debug-port.txt line 5

Quoted 2 lines

Documentation/usb/usb3-debug-port.txt new file +2 -0

+
+              Last-updated: October 2016

:Date: October 2016

Again, this is what git does.

Quoted 12 lines

Documentation/usb/usb3-debug-port.txt new file +12 -0

+
+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

Documentation/usb/usb3-debug-port.txt line 27

Quoted 10 lines

Documentation/usb/usb3-debug-port.txt new file +10 -0

+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.

Quoted 22 lines

Documentation/usb/usb3-debug-port.txt new file +22 -0

+
+    "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

Documentation/usb/usb3-debug-port.txt line 59

Quoted 10 lines

Documentation/usb/usb3-debug-port.txt new file +10 -0

+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.

Quoted 5 lines

Documentation/usb/usb3-debug-port.txt new file +5 -0

+
+# 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.

Documentation/usb/usb3-debug-port.txt line 74

Quoted 10 lines

Documentation/usb/usb3-debug-port.txt new file +10 -0

+[ 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.

Quoted 13 lines

Documentation/usb/usb3-debug-port.txt new file +13 -0

+
+===== 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.

Quoted 9 lines · Lu Baolu

Hi Jani,

Quoted 6 lines · Jani Nikula

Quoted 2 lines · Lu Baolu

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.

Quoted 5 lines

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'.

BR,
Jani.

Quoted 132 lines

Best regards,
Lu Baolu

Quoted 129 lines

BR,
Jani.

Quoted 13 lines

Cc [email protected]

Signed-off-by Lu Baolu <[email protected]>

---
 Documentation/usb/usb3-debug-port.txt | 87 +++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 Documentation/usb/usb3-debug-port.txt

Documentation/usb/usb3-debug-port.txt new file +0 -0

new file mode 100644
index 0000000..df5ce27

Documentation/usb/usb3-debug-port.txt line 1

Quoted 1 line

Documentation/usb/usb3-debug-port.txt new file +1 -0

@@ -0,0 +1,87 @@
+                  USB3 debug port

Make that a title with

===============
USB3 debug port
===============

Documentation/usb/usb3-debug-port.txt line 3

Quoted 2 lines

Documentation/usb/usb3-debug-port.txt new file +2 -0

+
+         Lu Baolu <[email protected]>

:Author: Lu Baolu <[email protected]>

Although git blame will give a more accurate idea after the file's been edited by others.

Documentation/usb/usb3-debug-port.txt line 5

Quoted 2 lines

Documentation/usb/usb3-debug-port.txt new file +2 -0

+
+              Last-updated: October 2016

:Date: October 2016

Again, this is what git does.

Quoted 12 lines

Documentation/usb/usb3-debug-port.txt new file +12 -0

+
+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

Documentation/usb/usb3-debug-port.txt line 27

Quoted 10 lines

Documentation/usb/usb3-debug-port.txt new file +10 -0

+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.

Quoted 22 lines

Documentation/usb/usb3-debug-port.txt new file +22 -0

+
+    "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

Documentation/usb/usb3-debug-port.txt line 59

Quoted 10 lines

Documentation/usb/usb3-debug-port.txt new file +10 -0

+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.

Quoted 5 lines

Documentation/usb/usb3-debug-port.txt new file +5 -0

+
+# 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.

Documentation/usb/usb3-debug-port.txt line 74

Quoted 10 lines

Documentation/usb/usb3-debug-port.txt new file +10 -0

+[ 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.

Quoted 13 lines

Documentation/usb/usb3-debug-port.txt new file +13 -0

+
+===== 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.