From 2c191ef1da1f7f4dd38606c9936948a958aece20 Mon Sep 17 00:00:00 2001
From: Antonio Borneo <borneo.antonio@gmail.com>
Date: Sat, 22 Oct 2022 18:12:16 +0200
Subject: [PATCH] doc: usb_adapters: add container for lsusb dump of adapters

When extending an existing adapter driver, developer has to
carefully avoid to break backward compatibility.
But not all developers have access to many adapters for testing.

Prepare a folder aimed at containing 'lsusb -v' dumps of adapters
to be used as reference.
Add documentation and a simple dump script.

Change-Id: Ia3a9132d65ec8869734721f9605cebcebcf33608
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/7296
Tested-by: jenkins
---
 doc/usb_adapters/dump.sh    | 24 ++++++++++++++++++++++++
 doc/usb_adapters/readme.txt | 43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100755 doc/usb_adapters/dump.sh
 create mode 100644 doc/usb_adapters/readme.txt

diff --git a/doc/usb_adapters/dump.sh b/doc/usb_adapters/dump.sh
new file mode 100755
index 000000000..1ecfb40f0
--- /dev/null
+++ b/doc/usb_adapters/dump.sh
@@ -0,0 +1,24 @@
+#!/bin/sh
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+devs=$(lsusb -d $1:$2 | wc -l)
+case "$devs" in
+	0 )
+		echo "Error: USB device $1:$2 not found" > /dev/stderr
+		exit 1
+		;;
+	1 )
+		echo "Dumping $(lsusb -d $1:$2)" > /dev/stderr
+		;;
+	* )
+		echo "Error: Multiple matches for 'lsusb -d $1:$2'" > /dev/stderr
+		exit 1
+		;;
+esac
+
+# break SPDX tag to hide it to checkpatch
+echo '# SPDX-''License-Identifier: GPL-2.0-or-later OR GFDL-1.2-no-invariants-or-later'
+echo ''
+echo '# Optional comment'
+
+lsusb -v -d $1:$2 | sed 's/ *$//'
diff --git a/doc/usb_adapters/readme.txt b/doc/usb_adapters/readme.txt
new file mode 100644
index 000000000..1d995e99f
--- /dev/null
+++ b/doc/usb_adapters/readme.txt
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: GPL-2.0-or-later OR GFDL-1.2-no-invariants-or-later
+
+This folder contains a collection of dumps of USB descriptors, obtained through
+Linux lsusb command, of several USB adapters supported by OpenOCD.
+This collection should help maintaining adapter drivers even if the developer
+doesn't have access to all the devices supported by the driver.
+
+To add a new file, run:
+
+	./doc/usb_adapters/dump.sh ${vid} ${pid} \
+		> doc/usb_adapters/${driver}/${vid}_${pid}_${short_description}.txt
+
+eventually edit the file to add some extra comment, then submit the file to
+OpenOCD gerrit, as explained in HACKING.
+
+The dumps are organized in subfolders corresponding to OpenOCD drivers:
+- cmsis_dap;
+- ft232r;
+- ftdi;
+- icdi;
+- jlink;
+- kitprog;
+- nulink;
+- stlink;
+- xds110.
+
+The script above assumes the user has granted access permissions to the USB
+device file in
+	/dev/bus/usb/<n>/<m>
+This is usually the case when the device is listed in
+	contrib/60-openocd.rules
+and this udev rules file is properly installed in the host machine.
+If the user has no proper access permissions, the script has to be run as
+root or through 'sudo'.
+
+Old versions of 'lsusb -v' dump cryptic errors like:
+	can't get device qualifier: Resource temporarily unavailable
+	can't get debug descriptor: Resource temporarily unavailable
+when some optional descriptor is not present.
+This is fixed in usbutils v014.
+If you get such messages simply ignore them. They are printed on stderr, so
+will not be included in the generated file as the redirection '>' does only
+redirects stdout.
-- 
2.11.4.GIT