USB-capable drivers: introduce warn_if_bad_usb_port_filename()

drivers/bcmxcp_usb.c

@@ -499,6 +499,7 @@ usb_dev_handle *nutusb_open(const char *port)
 	int            ret = 0;
 
 	upsdebugx(1, "entering nutusb_open()");
+	warn_if_bad_usb_port_filename(device_path);
 
 	/* Initialize Libusb */
 #if WITH_LIBUSB_1_0

drivers/blazer_usb.c

@@ -584,9 +584,10 @@ void upsdrv_initups(void)
 	int	ret, langid;
 	char	tbuf[255]; /* Some devices choke on size > 255 */
 	char	*regex_array[7];
-
 	char	*subdrv = getval("subdriver");
 
+	warn_if_bad_usb_port_filename(device_path);
+
 	regex_array[0] = getval("vendorid");
 	regex_array[1] = getval("productid");
 	regex_array[2] = getval("vendor");

drivers/nutdrv_qx.c

@@ -2945,6 +2945,8 @@ void	upsdrv_initups(void)
 /* USB */
 #ifdef QX_USB
 
+	warn_if_bad_usb_port_filename(device_path);
+
 	#ifndef TESTING
 		int	ret, langid;
 		char	tbuf[255];	/* Some devices choke on size > 255 */

drivers/richcomm_usb.c

@@ -571,6 +571,8 @@ void upsdrv_initups(void)
 	char	reply[REPLY_PACKETSIZE];
 	int	i;
 
+	warn_if_bad_usb_port_filename(device_path);
+
 	for (i = 0; usb_device_open(&udev, &usbdevice, &device_matcher, &driver_callback) < 0; i++) {
 
 		if ((i < 32) && (sleep(5) == 0)) {

drivers/riello_usb.c

@@ -846,6 +846,8 @@ void upsdrv_initups(void)
 
 	char	*subdrv = getval("subdriver");
 
+	warn_if_bad_usb_port_filename(device_path);
+
 	regex_array[0] = getval("vendorid");
 	regex_array[1] = getval("productid");
 	regex_array[2] = getval("vendor");

drivers/tripplite_usb.c

@@ -1566,6 +1566,8 @@ void upsdrv_initups(void)
 	char *value;
 	int r;
 
+	warn_if_bad_usb_port_filename(device_path);
+
 	/* process the UPS selection options */
 	regex_array[0] = NULL; /* handled by USB IDs device table */
 	regex_array[1] = getval("productid");

drivers/usb-common.c

@@ -462,3 +462,38 @@ void USBFreeRegexMatcher(USBDeviceMatcher_t *matcher)
 	free(data);
 	free(matcher);
 }
+
+void warn_if_bad_usb_port_filename(const char *fn) {
+	/* USB drivers ignore the 'port' setting - log a notice
+	 * if it is not "auto". Note: per se, ignoring the port
+	 * (or internally the device_path variable from main.c)
+	 * is currently not a bug and is actually documented at
+	 * docs/config-notes.txt; however it is not something
+	 * evident to users during troubleshooting a device.
+	 * Documentation and common practice recommend port=auto
+	 * so here we warn during driver start if it has some
+	 * other value and users might think it is honoured.
+	 */
+
+	if (!fn) {
+		upslogx(LOG_WARNING,
+			"WARNING: %s(): port argument was not "
+			"specified to the driver",
+			__func__);
+		return;
+	}
+
+	if (!strcmp(fn, "auto"))
+		return;
+
+	upslogx(LOG_WARNING,
+		"WARNING: %s(): port argument specified to\n"
+		"  the driver is \"%s\" but USB drivers do "
+		"not use it and rely on\n"
+		"  libusb walking all devices and matching "
+		"their identification metadata.\n"
+		"  NUT documentation recommends port=\"auto\" "
+		"for USB devices to avoid confusion.",
+		__func__, fn);
+	return;
+}

drivers/usb-common.h

@@ -513,4 +513,9 @@ int is_usb_device_supported(usb_device_id_t *usb_device_id_list,
 
 void nut_usb_addvars(void);
 
+/* Tell the users that port="auto" should be used for USB,
+ * and other values are quietly ignored. Implemented once
+ * here, to use in several USB-capable drivers. */
+void warn_if_bad_usb_port_filename(const char *fn);
+
 #endif /* NUT_USB_COMMON_H */

drivers/usbhid-ups.c

@@ -1017,6 +1017,7 @@ void upsdrv_initups(void)
 	char *regex_array[7];
 
 	upsdebugx(1, "upsdrv_initups (non-SHUT)...");
+	warn_if_bad_usb_port_filename(device_path);
 
 	subdriver_matcher = &subdriver_matcher_struct;