linux-kernel - [PATCH v3 3/3] usb: doc: Update document for USB3 debug port usage

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <1504576740-11689-4-git-send-email-baolu.lu@linux.intel.com>
Date:   Tue,  5 Sep 2017 09:59:00 +0800
From:   Lu Baolu <baolu.lu@...ux.intel.com>
To:     Mathias Nyman <mathias.nyman@...ux.intel.com>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>
Cc:     linux-usb@...r.kernel.org, linux-kernel@...r.kernel.org,
        Lu Baolu <baolu.lu@...ux.intel.com>
Subject: [PATCH v3 3/3] 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.

Signed-off-by: Lu Baolu <baolu.lu@...ux.intel.com>
---
 Documentation/driver-api/usb/usb3-debug-port.rst | 68 ++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/Documentation/driver-api/usb/usb3-debug-port.rst b/Documentation/driver-api/usb/usb3-debug-port.rst
index feb1a36..4ad4787 100644
--- a/Documentation/driver-api/usb/usb3-debug-port.rst
+++ b/Documentation/driver-api/usb/usb3-debug-port.rst
@@ -98,3 +98,71 @@ you to check the sanity of the setup.
 	cat /dev/ttyUSB0
 	done
 	===== end of bash scripts ===============
+
+Serial TTY
+==========
+
+DbC has also been designed for a serial TTY device at runtime.
+One use of this is running a login service on the debug target.
+Hence it can be remote accessed by the debug host. Another use
+can probably be found in servers. It provides a peer-to-peer USB
+link between two host-only machines. This provides a reasonable
+out-of-band communication method between two servers.
+
+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@...get:/sys/bus/pci/devices/0000:00:14.0# cat dbc
+	disabled
+
+Enable DbC with the following command::
+
+	root@...get:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc
+
+You can check the DbC state at anytime::
+
+	root@...get:/sys/bus/pci/devices/0000: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 the /dev/ttyDBC0 created
+on the debug target. You will see below kernel message lines::
+
+	root@...get: tail -f /var/log/kern.log
+	[  182.730103] xhci_hcd 0000:00:14.0: DbC connected
+	[  191.169420] xhci_hcd 0000:00:14.0: DbC configured
+	[  191.169597] xhci_hcd 0000:00:14.0: DbC now attached to /dev/ttyDBC0
+
+Accordingly, the DbC state has been brought up to::
+
+	root@...t:/sys/bus/pci/devices/0000: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@...t: 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=0004
+	[   79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
+	[   79.475391] usb 2-2.1: Product: Remote GDB
+	[   79.475392] usb 2-2.1: Manufacturer: Linux
+	[   79.475393] usb 2-2.1: SerialNumber: 0001
+	[   79.660368] usb_debug 2-2.1:1.0: xhci_dbc converter detected
+	[   79.660439] usb 2-2.1: xhci_dbc converter now attached to ttyUSB0
+
+You can simply verify whether it works by::
+
+	# On target side
+	root@...get: echo "Hello world" > /dev/ttyDBC0
+
+	# On host side
+	root@...t: cat /dev/ttyUSB0
+	Hello world
+
+	# vice versa
+
+You have a workable serial link over USB now.
-- 
2.7.4