Merge pull request #2060 from stefanrueger/bus-device

Ignore leading zeros in -P usb:<bus>:<device> numbers and improve `-P` documentation

Author: stefanrueger

src/avrdude.1

@@ -41,7 +41,7 @@
 .Op Fl i Ar delay
 .Op Fl l, \-logfile Ar logfile
 .Op Fl n, \-test-memory
-.Op Fl O, \-osccal 
+.Op Fl O, \-osccal
 .Op Fl P, \-port Ar port
 .Op Fl r, \-reconnect
 .Op Fl q, \-quell
@@ -607,6 +607,14 @@ or
 from the configuration file are used. If you need to use a different port,
 use this option to specify the alternate port name.
 .Pp
+USB-only programmers normally do not need the port option be specified as
+they are automatically identified via their vendor and product IDs from
+avrdude.conf or .avrduderc. Only when there are multiple programmers of
+the same type plugged into the host computer is the -P option needed, see
+below. Some -c programmers, however, ignore the -P option altogether, eg,
+teensy, ch341a or avrftdi; these cannot distinguish multiple plugged-in
+programmers.
+.Pp
 If
 .Nm
 has been configured with libserialport support, a serial port can be specified
@@ -663,20 +671,38 @@ The match is done after stripping any existing colons from the given
 serial number, and right-to-left, so only the least significant bytes
 from the serial number need to be given.
 .Pp
+avrdude -v -P usb:xyz -c jtag2 -p ... 2>&1 | grep ^Found
+.Pp
+lists all JTAG ICEs
+attached to USB, see the section
+.Em Example Command Line Invocations
+in the detailed pdf documentation.
+.Pp
 As the AVRISP mkII device can only be talked to over USB, the very
 same method of specifying the port is required there.
 .Pp
-For the USB programmer "AVR-Doper" running in HID mode, the port must
+For the USB programmer AVR-Doper running in HID mode, the port must
 be specified as
 .Ar avrdoper.
 Libhidapi support is required on Unix and Mac OS but not on Windows. For more
 information about AVR-Doper see https://www.obdev.at/products/vusb/avrdoper.html.
 .Pp
-For the USBtinyISP, which is a simplistic device not implementing
-serial numbers, multiple devices can be distinguished by their
-location in the USB hierarchy.  See the respective
+For the USBtinyISP, which is a simplistic device not implementing serial
+numbers, multiple devices can be distinguished by their location in the
+USB hierarchy using -P usb:<busdir>:<devicefile>.
+.Pp
+For USBasp, multiple devices can also be also distinguished using -P
+usb:<busdir>:<devicefile> or using the serial number -P usb:<serialno>.
+For examples, see the respective
 .Em Troubleshooting
-entry in the detailed documentation for examples.
+entry in the detailed pdf documentation.
+.Pp
+The -c pickit5 programmer allows overriding the product ID with a
+hexadecimal number <pid> using -P usb::<pid> and the vendor and product
+IDs with hexadecimal numbers <vid> and <pid> using -P usb:<vid>:<pid>. The
+form -P usb:<serialno> requests AVRDUDE select the PICkit5 programmer with
+a serial number that ends in <serialno> (and with vid/pid from the
+configuration files).
 .Pp
 For the XBee programmer the target MCU is to be programmed wirelessly over a
 ZigBee mesh using the XBeeBoot bootloader.  The ZigBee 64-bit address for the
@@ -968,10 +994,13 @@ The
 .Ar addr
 and
 .Ar len
-parameters of the dump, read, disasm, write, save and erase commands can be
-negative with the same syntax as substring computations in perl or python.
-The table below details their meaning with respect to an example memory of size
-sz=0x800 (2048 bytes).
+parameters of the dump, read, disasm, write, save and erase commands can
+be negative with the same syntax as substring computations in perl or
+python. The table below defines the effective memory interval
+.Ar [start ,
+.Ar end],
+given the memory size
+.Ar sz :
 .Pp
 .nf
 addr    len  Memory interval     Comment
@@ -982,13 +1011,31 @@ addr    len  Memory interval     Comment
                  sz+addr+len-1]
   neg   neg  [sz+addr, sz+len]   Combining above two cases
   any     0  empty set           No action
+.fi
+.Pp
+Note that addr must be in the range [-sz, sz-1]. After computing the memory interval
+[start, end] as per above table, the effective length end-start + 1 must not be negative; if
+the effective length is zero then no action is carried out. End may be beyond the available
+memory for the dump, read or disasm commands, in which case the operation wraps around
+the memory end, but the effective length is always limited to the memory size.
+.Pp
+Here some examples for a memory with size sz of 0x800 (2048) bytes:
+.Pp
+.nf
+addr    len  Memory interval     Comment
+------------------------------------------------------------------------
 0x700    12  [0x700, 0x70b]      Conventional use
  1024  -257  [0x400, 0x6ff]      Size of memory is 2048 or 0x800
  -512   512  [0x600, 0x7ff]      Last 512 bytes
  -256    -1  [0x700, 0x7ff]      Last 256 bytes
     0    49  [0, 48]             First 49 bytes
     0   -49  [0, 1999]           All but the last 48 = |len+1| bytes
     0    -1  [0, 0x7ff]          All memory without knowing its size
+ 2046     4  [0x7fe, 0x801]      Wrap around for read but error for write
+ 2046  4096  [0x7fe, 0x17fe]     Read wrap around stops at 0x7fd
+   -1    -1  [0x7ff, 0x7ff]      One byte at 0x7ff is addressed
+   -1    -2  [0x7ff, 0x7fe]      No action: effective length is zero
+   -1    -3  [0x7ff, 0x7fd]      Error: effective length is negative
 .fi
 .Pp
 The following commands are implemented for all programmers:
@@ -1639,7 +1686,7 @@ to the target. If there is already a valid voltage applied to the VTG Pin,
 this setting will be ignored. When AVRDUDE detects an external voltage outside
 of this range, it will terminate the operation. You can disable this check by
 setting the voltage to 0 V. If an XMEGA part was selected, a requested voltage
-above 3.49 V will lead to an abort of operation. 
+above 3.49 V will lead to an abort of operation.
 .It Ar hvupdi
 High-voltage UPDI programming is used to enable a UPDI pin that has previously
 been set to RESET or GPIO mode. Use -x hvupdi to enable high-voltage UPDI

src/avrftdi.c

@@ -641,6 +641,10 @@ static int avrftdi_open(PROGRAMMER *pgm, const char *port) {
 
   Avrftdi_data *pdata = to_pdata(pgm);
 
+  pmsg_debug("%s(\"%s\")\n", __func__, port);
+  if(!str_eq(port, "usb"))
+    pmsg_warning("option -P %s ignored\n", port);
+
   // Parameter validation
 
   // Use vid/pid in following priority: config, defaults cmd-line is currently not supported

src/ch341a.c

@@ -201,7 +201,9 @@ static int ch341a_open(PROGRAMMER *pgm, const char *port) {
   int errorCode = USB_ERROR_NOTFOUND;
   libusb_device_handle *handle = NULL;
 
-  pmsg_trace("ch341a_open(\"%s\")\n", port);
+  pmsg_debug("%s(\"%s\")\n", __func__, port);
+  if(!str_eq(port, "usb"))
+    pmsg_warning("option -P %s ignored\n", port);
 
   if(!my.USB_init) {
     my.USB_init = 1;

src/dfu.c

@@ -92,25 +92,26 @@ static char *get_usb_string(usb_dev_handle *dev_handle, int index);
 
 struct dfu_dev *dfu_open(const char *port_spec) {
   struct dfu_dev *dfu;
-  char *bus_name = NULL;
-  char *dev_name = NULL;
+  char *bus_name = NULL, *dev_name = NULL;
 
-  /* The following USB device spec parsing code was copied from usbtiny.c. The
-   * expected format is "usb:BUS:DEV" where BUS and DEV are the bus and device
-   * names. We stash these away in the dfu_dev structure for the dfu_init()
-   * function, where we actually open the device.
+  /*
+   * The following USB device spec parsing code was copied from usbtiny.c.
+   * The expected format is "usb:<busdir>:<devicefile>". We stash these
+   * away in the dfu_dev structure for the dfu_init() function, where we
+   * actually open the device.
    */
 
-  if(!str_starts(port_spec, "usb")) {
-    pmsg_error("invalid port specification %s for USB device\n", port_spec);
+  pmsg_debug("%s(\"%s\")\n", __func__, port_spec);
+
+  if(!str_starts(port_spec, "usb:") && !str_eq(port_spec, "usb")) {
+    pmsg_error("invalid -P %s; drop this option or use -P usb:<busdir>:<devicefile>\n", port_spec);
     return NULL;
   }
 
   if(':' == port_spec[3]) {
     bus_name = mmt_strdup(port_spec + 3 + 1);
 
-    dev_name = strchr(bus_name, ':');
-    if(NULL != dev_name)
+    if((dev_name = strchr(bus_name, ':')))
       *dev_name++ = '\0';
   }
 
@@ -138,17 +139,19 @@ int dfu_init(struct dfu_dev *dfu, unsigned short vid, unsigned short pid) {
   struct usb_device *dev;
   struct usb_bus *bus;
 
-  /* At last, we reach out through the USB bus to the part. There are three
-   * ways to specify the part: by USB address, by USB vendor and product id,
-   * and by part name. To specify the part by USB address, the user specifies
-   * a port parameter in the form "usb:BUS:DEV" (see dfu_open()). To specify
-   * the part by vendor and product, the user must specify a usbvid and usbpid
-   * in the configuration file. Finally, if the user specifies the part only,
-   * we use the default vendor and product id.
+  /*
+   * At last, we reach out through the USB bus to the part. There are
+   * three ways to specify the part: by USB address, by USB vendor and
+   * product id, and by part name. To specify the part by USB address, the
+   * user specifies a port parameter in the form usb:<busdir>:<devicefile>
+   * (see dfu_open()). To specify the part by vendor and product, the user
+   * must specify a usbvid and usbpid in the configuration file. Finally,
+   * if the user specifies the part only, we use the default vendor and
+   * product id.
    */
 
   if(pid == 0 && dfu->dev_name == NULL) {
-    pmsg_error("no DFU support for part; specify PID in config or USB address (via -P) to override\n");
+    pmsg_error("no DFU support for part; specify <pid> in config or USB address via -P usb:<busdir>:<devicefile>\n");
     return -1;
   }
 
@@ -164,10 +167,14 @@ int dfu_init(struct dfu_dev *dfu, unsigned short vid, unsigned short pid) {
 
   for(bus = usb_busses; !found && bus != NULL; bus = bus->next) {
     for(dev = bus->devices; !found && dev != NULL; dev = dev->next) {
-      if(dfu->bus_name != NULL && !str_eq(bus->dirname, dfu->bus_name))
+       if(vid == dev->descriptor.idVendor && pid == dev->descriptor.idProduct)
+          pmsg_notice("found device with vendorID=0x%04x and productID=0x%04x, busdir:devicefile = %s:%s\n",
+            vid, pid, bus->dirname, dev->filename);
+
+      if(dfu->bus_name && !str_busdev_eq(bus->dirname, dfu->bus_name))
         continue;
-      if(dfu->dev_name != NULL) {
-        if(!str_eq(dev->filename, dfu->dev_name))
+      if(dfu->dev_name) {
+        if(!str_busdev_eq(dev->filename, dfu->dev_name))
           continue;
       } else if(vid != dev->descriptor.idVendor)
         continue;
@@ -187,7 +194,7 @@ int dfu_init(struct dfu_dev *dfu, unsigned short vid, unsigned short pid) {
     return -1;
   }
 
-  pmsg_notice2("found VID=0x%04x PID=0x%04x at %s:%s\n",
+  pmsg_notice2("using VID=0x%04x PID=0x%04x at %s:%s\n",
     found->descriptor.idVendor, found->descriptor.idProduct, found->bus->dirname, found->filename);
 
   dfu->dev_handle = usb_open(found);
@@ -223,14 +230,10 @@ int dfu_init(struct dfu_dev *dfu, unsigned short vid, unsigned short pid) {
 void dfu_close(struct dfu_dev *dfu) {
   if(dfu->dev_handle != NULL)
     usb_close(dfu->dev_handle);
-  if(dfu->bus_name != NULL)
-    mmt_free(dfu->bus_name);
-  if(dfu->manf_str != NULL)
-    mmt_free(dfu->manf_str);
-  if(dfu->prod_str != NULL)
-    mmt_free(dfu->prod_str);
-  if(dfu->serno_str != NULL)
-    mmt_free(dfu->serno_str);
+  mmt_free(dfu->bus_name);
+  mmt_free(dfu->manf_str);
+  mmt_free(dfu->prod_str);
+  mmt_free(dfu->serno_str);
 }
 
 int dfu_getstatus(struct dfu_dev *dfu, struct dfu_status *status) {