doc/usb_adapters/readme.txt

   1 # SPDX-License-Identifier: GPL-2.0-or-later OR GFDL-1.2-no-invariants-or-later
   2
   3 This folder contains a collection of dumps of USB descriptors, obtained through
   4 Linux lsusb command, of several USB adapters supported by OpenOCD.
   5 This collection should help maintaining adapter drivers even if the developer
   6 doesn't have access to all the devices supported by the driver.
   7
   8 To add a new file, run:
   9
  10         ./doc/usb_adapters/dump.sh ${vid} ${pid} \
  11                 > doc/usb_adapters/${driver}/${vid}_${pid}_${short_description}.txt
  12
  13 eventually edit the file to add some extra comment, then submit the file to
  14 OpenOCD gerrit, as explained in HACKING.
  15
  16 The dumps are organized in subfolders corresponding to OpenOCD drivers:
  17 - cmsis_dap;
  18 - ft232r;
  19 - ftdi;
  20 - icdi;
  21 - jlink;
  22 - kitprog;
  23 - nulink;
  24 - stlink;
  25 - xds110.
  26
  27 The script above assumes the user has granted access permissions to the USB
  28 device file in
  29         /dev/bus/usb/<n>/<m>
  30 This is usually the case when the device is listed in
  31         contrib/60-openocd.rules
  32 and this udev rules file is properly installed in the host machine.
  33 If the user has no proper access permissions, the script has to be run as
  34 root or through 'sudo'.
  35
  36 Old versions of 'lsusb -v' dump cryptic errors like:
  37         can't get device qualifier: Resource temporarily unavailable
  38         can't get debug descriptor: Resource temporarily unavailable
  39 when some optional descriptor is not present.
  40 This is fixed in usbutils v014.
  41 If you get such messages simply ignore them. They are printed on stderr, so
  42 will not be included in the generated file as the redirection '>' does only
  43 redirects stdout.