Merge pull request #2260 from jimklimov/issue-2259

Help users about `nutdrv_qx` and similar drivers built for serial-only support but used for USB devices

NEWS.adoc

@@ -111,6 +111,15 @@ https://github.com/networkupstools/nut/milestone/10
      up in the link:https://pypi.org/project/PyNUTClient[PyPI repository].
      [#2158]
 
+ - main driver core codebase:
+   * Help users of drivers that can be built to support optionally USB and
+     other media (like `nutdrv_qx` built for serial-only support), and built
+     in fact without USB support but used for USB devices, with some more
+     information to make troubleshooting easier. [#2259]
+   * Driver programs with debug tracing support via `-D` CLI option and/or
+     the `NUT_DEBUG_LEVEL` environment variable now check those earlier in
+     their life-time, so that initialization routine can be debugged. [#2259]
+
  - powerpanel text driver now handles status responses in any format and should
    support most devices [#2156]
 

drivers/libusb0.c

@@ -95,6 +95,8 @@ void nut_usb_addvars(void)
 	addvar(VAR_VALUE, "usb_set_altinterface", "Force redundant call to usb_set_altinterface() (value=bAlternateSetting; default=0)");
 
 	dstate_setinfo("driver.version.usb", "libusb-0.1 (or compat)");
+
+	upsdebugx(1, "Using USB implementation: %s", dstate_getinfo("driver.version.usb"));
 }
 
 /* From usbutils: workaround libusb (0.1) API goofs:

drivers/libusb1.c

@@ -93,6 +93,8 @@ void nut_usb_addvars(void)
 #else  /* no LIBUSB_API_VERSION */
 	dstate_setinfo("driver.version.usb", "libusb-%u.%u.%u", v->major, v->minor, v->micro);
 #endif /* LIBUSB_API_VERSION */
+
+	upsdebugx(1, "Using USB implementation: %s", dstate_getinfo("driver.version.usb"));
 }
 
 /* invoke matcher against device */

drivers/main.c

@@ -351,6 +351,31 @@ void storeval(const char *var, char *val)
 	printf("Look in the man page or call this driver with -h for a list of\n");
 	printf("valid variable names and flags.\n");
 
+	if (!strcmp(progname, "nutdrv_qx")) {
+		/* First many entries are from nut_usb_addvars() implementations;
+		 * the latter two (about langid) are from nutdrv_qx.c
+		 */
+		if (!strcmp(var, "vendor")
+		||  !strcmp(var, "product")
+		||  !strcmp(var, "serial")
+		||  !strcmp(var, "vendorid")
+		||  !strcmp(var, "productid")
+		||  !strcmp(var, "bus")
+		||  !strcmp(var, "device")
+		||  !strcmp(var, "busport")
+		||  !strcmp(var, "usb_set_altinterface")
+		||  !strcmp(var, "allow_duplicates")
+		||  !strcmp(var, "langid_fix")
+		||  !strcmp(var, "noscanlangid")
+		) {
+			printf("\nNOTE: for driver '%s', options like '%s' are only available\n"
+				"if it was built with USB support. If you are running a custom build of NUT,\n"
+				"please check results of the `configure` checks, and consider an explicit\n"
+				"`--with-usb` option. Also make sure that both libusb library and headers\n"
+				"are installed in your build environment.\n\n", progname, var);
+		}
+	}
+
 	exit(EXIT_SUCCESS);
 }
 
@@ -1616,9 +1641,64 @@ int main(int argc, char **argv)
 	const char * cmd = NULL;
 #endif
 
+	const char optstring[] = "+a:s:kDFBd:hx:Lqr:u:g:Vi:c:"
+#ifndef WIN32
+		"P:"
+#endif
+		;
+
 	/* init verbosity from default in common.c (0 probably) */
 	nut_debug_level_args = nut_debug_level;
 
+	/* handle CLI-driven debug level in advance, to trace initialization if needed */
+	while ((i = getopt(argc, argv, optstring)) != -1) {
+		switch (i) {
+			case 'D':
+				/* bump right here, may impact reporting of other CLI args */
+				nut_debug_level++;
+				nut_debug_level_args++;
+				break;
+		}
+	}
+	/* Reset the index, read argv[1] next time (loop below)
+	 * https://pubs.opengroup.org/onlinepubs/9699919799/functions/getopt.html
+	 */
+	optind = 1;
+
+	if (foreground < 0) {
+		/* Guess a default */
+		/* Note: only care about CLI-requested debug verbosity here */
+		if (nut_debug_level > 0 || dump_data) {
+			/* Only flop from default - stay foreground with debug on */
+			foreground = 1;
+		} else {
+			/* Legacy default - stay background and quiet */
+			foreground = 0;
+		}
+	} else {
+		/* Follow explicit user -F/-B request */
+		upsdebugx (0,
+			"Debug level is %d, dump data count is %s, "
+			"but backgrounding mode requested as %s",
+			nut_debug_level,
+			dump_data ? "on" : "off",
+			foreground ? "off" : "on"
+			);
+	}
+
+	{ /* scoping */
+		char *s = getenv("NUT_DEBUG_LEVEL");
+		int l;
+		if (s && str_to_int(s, &l, 10)) {
+			if (l > 0 && nut_debug_level_args < 1) {
+				upslogx(LOG_INFO, "Defaulting debug verbosity to NUT_DEBUG_LEVEL=%d "
+					"since none was requested by command-line options", l);
+				nut_debug_level = l;
+				nut_debug_level_args = l;
+			}	/* else follow -D settings */
+		}	/* else nothing to bother about */
+	}
+
 	dstate_setinfo("driver.state", "init.starting");
 
 	atexit(exit_cleanup);
@@ -1660,11 +1740,7 @@ int main(int argc, char **argv)
 	/* build the driver's extra (-x) variable table */
 	upsdrv_makevartable();
 
-	while ((i = getopt(argc, argv, "+a:s:kFBDd:hx:Lqr:u:g:Vi:c:"
-#ifndef WIN32
-		"P:"
-#endif
-	)) != -1) {
+	while ((i = getopt(argc, argv, optstring)) != -1) {
 		switch (i) {
 			case 'a':
 				if (upsname)
@@ -1699,9 +1775,7 @@ int main(int argc, char **argv)
 				foreground = 0;
 				break;
 			case 'D':
-				/* bump right here, may impact reporting of other CLI args */
-				nut_debug_level++;
-				nut_debug_level_args++;
+				/* Processed above */
 				break;
 			case 'd':
 				dump_data = atoi(optarg);
@@ -1828,40 +1902,6 @@ int main(int argc, char **argv)
 		}
 	}
 
-	if (foreground < 0) {
-		/* Guess a default */
-		/* Note: only care about CLI-requested debug verbosity here */
-		if (nut_debug_level > 0 || dump_data) {
-			/* Only flop from default - stay foreground with debug on */
-			foreground = 1;
-		} else {
-			/* Legacy default - stay background and quiet */
-			foreground = 0;
-		}
-	} else {
-		/* Follow explicit user -F/-B request */
-		upsdebugx (0,
-			"Debug level is %d, dump data count is %s, "
-			"but backgrounding mode requested as %s",
-			nut_debug_level,
-			dump_data ? "on" : "off",
-			foreground ? "off" : "on"
-			);
-	}
-
-	{ /* scoping */
-		char *s = getenv("NUT_DEBUG_LEVEL");
-		int l;
-		if (s && str_to_int(s, &l, 10)) {
-			if (l > 0 && nut_debug_level_args < 1) {
-				upslogx(LOG_INFO, "Defaulting debug verbosity to NUT_DEBUG_LEVEL=%d "
-					"since none was requested by command-line options", l);
-				nut_debug_level = l;
-				nut_debug_level_args = l;
-			}	/* else follow -D settings */
-		}	/* else nothing to bother about */
-	}
-
 	/* Since debug mode dumps from drivers are often posted to mailing list
 	 * or issue tracker, as well as viewed locally, it can help to know the
 	 * build options involved when troubleshooting (especially when needed