doc: usb_adapters: update the script for unavailable reports

When Linux HID driver binds the USB endpoints of the adapter,
'lsusb' fails to read all the reports and prints
	** UNAVAILABLE **

Detect this case and alert the user, providing also the proper
command to unbind the driver before running the script again.
Put this test at the end of the output, so user can easily see it.

Change-Id: Iaca00040e666b62ceebe4b842a24932799bde56a
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reported-by: Tomas Vanek <vanekt@fbl.cz>
Reviewed-on: https://review.openocd.org/c/openocd/+/8046
Tested-by: jenkins
Reviewed-by: Tomas Vanek <vanekt@fbl.cz>

doc/usb_adapters/dump.sh

@@ -1,6 +1,22 @@
 #!/bin/sh
 # SPDX-License-Identifier: GPL-2.0-or-later
 
+hid_unavailable_report() {
+	a=$(echo $1 | tr '[:lower:]' '[:upper:]')
+	b=$(basename $(dirname $(ls -d /sys/bus/usb/drivers/usbhid/*/*:$a.*)))
+
+	echo ""
+	echo "ATTENTION!"
+	echo "Unable to read completely the USB descriptors."
+	echo "Please run the following command(s) and then run this script again"
+	for i in $b; do
+		echo "    sudo sh -c \"echo -n $i > /sys/bus/usb/drivers/usbhid/unbind\""
+	done
+	echo ""
+	echo "Please notice that the USB device will not function after the above"
+	echo "operations; you should unplug and replug it to get it working again."
+}
+
 devs=$(lsusb -d $1:$2 | wc -l)
 case "$devs" in
 	0 )
@@ -22,3 +38,5 @@ echo ''
 echo '# Optional comment'
 
 lsusb -v -d $1:$2 | sed 's/ *$//'
+
+lsusb -v -d $1:$2 2>&1 | grep -Fq '** UNAVAILABLE **' && (hid_unavailable_report $1:$2 > /dev/stderr)