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