docs/new-drivers.txt: document addvar, getval and testvar, and nut_usb_addvars (and planned ser/modbus siblings) [networkupstools#2419, networkupstools#2748]

Documentation addition triggered by discussion in networkupstools#3181

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>

Author: jimklimov

docs/new-drivers.txt

@@ -181,6 +181,87 @@ for eventual `exit(EXIT_FAILURE)` and `EF_EXIT_SUCCESS` (`-2`) for
 `exit(EXIT_SUCCESS)`, which would be handled in the standard driver
 loop or in `forceshutdown()` method of `main.c`.
 
+addvar, getval and testvar
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+NUT drivers can be configured at run-time with optional settings, which
+can be passed on command line or via the linkman:ups.conf[5] file.
+Such settings broadly fall into two categories: "values" which convey
+some specific value (e.g. `port` or `desc` strings), and "flags" which
+can be seen as a sort of booleans which are `true` if mentioned and
+`false` if not (any assigned value would be ignored, if not rejected
+by configuration parser).
+
+Some options are common to all drivers and are handled in `drivers/main.c`
+(which also defines and implements most of the methods in this area), while
+others may be specific to individual drivers or even their sub-drivers.
+
+The `addvar()` method allows to specify a certain option name, with its
+type and a help message string:
+
+	addvar(VAR_VALUE, "sdtype", "Specify simple shutdown method (0-6)");
+
+	addvar(VAR_FLAG,  "wait",   "Wait for AC power");
+
+In driver code, these calls should comprise the `upsdrv_makevartable()`
+method.
+
+The `getval()` method allows to get the user-provided string value (or
+`NULL` -- but it is hard to tell apart if the option was not specified
+or no value was assigned).  The `testvar()` method allows to check if
+the option name was specified (even if without a value), so is better
+suited for flags.  Internally there is no difference between "values"
+and "flags", so historically some flags were "promoted" to values with
+boolean-ish strings handled explicitly, in addition to some new features.
+
+NOTE: Internally, the values can also be marked as reloadable (so that a
+running driver program may change them when re-reading the configuration
+file due to a signal).  The implementation may be currently limited to
+common options handled by `main.c` itself.  In code base this is exposed
+with the `addvar_reloadable()` and several `test*_reloadable()` methods.
+
+Since these methods involve a data structure walk to locate (or not) the
+entry for each option, they should not be used in data processing loops.
+Instead, the driver initialization methods such as `upsdrv_initups()`
+should consider all values and flags that can impact the set-up of the
+driver, and save them into C variables (typically strings, booleans, or
+processed and range/value-checked number types) which are then directly
+used in the driver program code.
+
+nut_usb_addvars
+~~~~~~~~~~~~~~~
+
+For consistency between USB-capable NUT drivers, a set of `addvar()`
+options related to USB media setup and expected by `nut_libusb_open()`
+can be defined by calling the `nut_usb_addvars()` method, which can be
+seen in `drivers/libusb{0,1}.c`.
+
+Like `addvar()`, a call to this method belongs in `upsdrv_makevartable()`
+(see existing drivers for examples).
+
+
+nut_ser_addvars
+~~~~~~~~~~~~~~~
+
+WARNING: NOT CURRENTLY IMPLEMENTED.
+
+Issue https://github.com/networkupstools/nut/issues/2748 tracks the idea
+to standardize the set and names of options involved in the serial driver
+connection set-up (speed, parity, stop-bits, etc.) similarly to the
+precedent of `nut_usb_addvars()`.  One problem is that many drivers
+released during the past decades reinvented this wheel with different
+option names.
+
+nut_modbus_addvars
+~~~~~~~~~~~~~~~~~~
+
+WARNING: NOT CURRENTLY IMPLEMENTED.
+
+Issue https://github.com/networkupstools/nut/issues/2419 tracks a similar
+idea for Modbus-capable drivers (which may involve or not Serial and/or
+USB link and option support, and uniquely TCP/IP RTU support, for example).
+
+
 Data types
 ----------
 

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3577 utf-8
+personal_ws-1.1 en 3582 utf-8
 AAC
 AAS
 ABI
@@ -1546,6 +1546,7 @@ additionalSOLibSearchPath
 addons
 addr
 addrange
+addvar
 addvars
 adelsystem
 adkorte
@@ -1707,6 +1708,7 @@ bmake
 bn
 bool
 boolean
+booleans
 bootable
 bootenv
 bootfs
@@ -2151,6 +2153,7 @@ getopt
 getproctag
 gettext
 gettextize
+getval
 getvar
 gh
 gif
@@ -2953,6 +2956,7 @@ regtype
 relatime
 releasekeyring
 relicensing
+reloadable
 relogtime
 remoteip
 renderer
@@ -3263,6 +3267,7 @@ termios
 testime
 testtime
 testuser
+testvar
 textproc
 tgcware
 tgt