new upstream 2.8.0

docs/hid-subdrivers.txt

@@ -9,9 +9,9 @@ different classes (audio, imaging, mass storage etc). Almost all UPS
 devices belong to the "HID" class, which means "Human Interface
 Device", and also includes things like keyboards and mice. What HID
 devices have in common is a particular (and very flexible) interface
-for reading and writing information (such as x/y coordinates and
-button states, in case of a mouse, or voltages and status information,
-in case of a UPS).
+for reading and writing information (such as X/Y coordinates and
+button states, in the case of a mouse, or voltages and status information,
+in the case of a UPS).
 
 The NUT "usbhid-ups" driver is a meta-driver that handles all HID UPS
 devices. It consists of a core driver that handles most of the work of
@@ -20,13 +20,14 @@ specific UPS manufacturers (MGE, APC, and Belkin are currently
 supported).  Adding support for a new HID UPS device is easy, because
 it requires only the creation of a new sub-driver.
 
-There are a few USB UPS devices that are not HID devices. These
+There are a few USB UPS devices that are not true HID devices. These
 devices typically implement some version of the manufacturer's serial
 protocol over USB (which is a really dumb idea, by the way). An
-example is the Tripplite USB. Such devices are *not* supported by the
-usbhid-ups driver, and are not covered in this document. If you need to
-add support for such a device, read new-drivers.txt and see the
-tripplite_usb driver for inspiration.
+example is the original Tripplite USB interface (USB idProduct = 0001). Its HID
+descriptor is only 52 bytes long (compared to several hundred bytes for a true
+PDC HID UPS).  Such devices are *not* supported by the usbhid-ups driver, and
+are not covered in this document. If you need to add support for such a device,
+read new-drivers.txt and see the "tripplite_usb" driver for inspiration.
 
 HID Usage Tree
 ~~~~~~~~~~~~~~
@@ -115,7 +116,7 @@ example Belkin defines `00860040` = ConfigVoltage (which is incidentally
 a violation of the USB PDC specification, as `00860040` is reserved for
 future use).
 
-Thus, subdrivers generally need to provide: 
+Thus, subdrivers generally need to provide:
 
 - manufacturer-specific usage definitions,
 - a mapping of HID variables to NUT variables.
@@ -126,26 +127,58 @@ shutdown.restart), and conversions of manufacturer specific data
 formats.
 
 
+Usage macros in drivers/hidtypes.h
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `drivers/hidtypes.h` header provides a number of macro names
+for entries in the standard usage tables for Power Device
+`USAGE_POW_<SOMETHING>` and Battery System `USAGE_BAT_<SOMETHING>`
+data pages.
+
+If NUT codebase would ever need to refresh those macros, here is
+some background information (based on NUT issue #1189 and PR #1290):
+
+These data were parsed from (a very slightly updated version of)
+https://github.com/abend0c1/hidrdd/blob/master/rd.conf file, which
+incorporates the complete USB-IF usage definitions for Power Device
+and Battery System pages (among many others), so we didn't have to
+extract the names and values from the USB-IF standards documents
+(did check it all by eye though).
+
+The file was processed with the following chain of commands:
+
+------
+:; grep -e '^0084' -e '^0085' rd.conf \
+   | sed 's/,.*$//;s/ *$//' \
+   | sed 's/ /_/g;s/_/ /' \
+   | tr '[:lower:]' '[:upper:]' \
+   | sed 's/\(0085.... \)/\1USAGE_BAT_/;s/\(0084.... \)/\1USAGE_POW_/;s/\([A-Z_]*\)_PAGE/PAGE_\1/' \
+   | awk '{print "#define "$2" 0x"$1}'
+------
+
+
 Writing a subdriver
 ~~~~~~~~~~~~~~~~~~~
 
 In preparation for writing a subdriver for a device that is currently
 unsupported, run usbhid-ups with the following command line:
 
- drivers/usbhid-ups -DD -u root -x explore -x vendorid=XXXX auto
+	drivers/usbhid-ups -DD -u root -x explore -x vendorid=XXXX -x port=auto -s ups
 
-(substitute your device's 4-digit VendorID instead of "XXXX"). 
-This will produce a bunch of debugging information, including a number 
-of lines starting with "Path:" that describe the device's usage tree. 
-This information forms the initial basis for a new subdriver. 
+(substitute your device's 4-digit VendorID instead of "XXXX").
+This will produce a bunch of debugging information, including a number
+of lines starting with "Path:" that describe the device's usage tree.
+This information forms the initial basis for a new subdriver.
 
-You should save this information to a file, e.g. 
- drivers/usbhid-ups -DD -u root -x explore -x vendorid=XXXX auto >& /tmp/info
+You should save this information to a file, e.g.:
+
+	drivers/usbhid-ups -DD -u root -x explore -x vendorid=XXXX \
+		-x port=auto -s ups 2>&1 | tee /tmp/info
 
 You can create an initial "stub" subdriver for your device by using
 script scripts/subdriver/gen-usbhid-subdriver.sh. Note: this only creates
-a "stub" and needs to be futher customized to be useful (see
-CUSTOMIZATION below).
+a "stub" and needs to be further customized to be useful (see
+"Customization" below).
 
 Use the script as follows:
 
@@ -160,14 +193,18 @@ and digits, and use natural capitalization such as "Belkin" (not
 information.
 
 You should put the generated files into the drivers/ subdirectory, and
-update usbhid-ups.c by adding the appropriate #include line and by
-updating the definition of subdriver_list in usbhid-ups.c. You must
-also add the subdriver to USBHID_UPS_SUBDRIVERS in drivers/Makefile.am
-and call "autoreconf" and/or "./configure" from the top level NUT directory.
-You can then recompile usbhid-ups, and start experimenting with the new
+update `usbhid-ups.c` by adding the appropriate `#include` line and by
+updating the definition of `subdriver_list` in `usbhid-ups.c`. You must
+also add the subdriver to USBHID_UPS_SUBDRIVERS in `drivers/Makefile.am`
+and call `autoreconf` and/or `./configure` from the top-level NUT directory.
+You can then recompile `usbhid-ups`, and start experimenting with the new
 subdriver.
 
-CUSTOMIZATION: The initially generated subdriver code is only a stub,
+
+Customization
+~~~~~~~~~~~~~
+
+The initially generated subdriver code is only a stub,
 and will not implement any useful functionality (in particular, it
 will be unable to shut down the UPS). In the beginning, it simply
 attempts to monitor some UPS variables. To make this driver useful,
@@ -175,7 +212,7 @@ you must examine the NUT variables of the form "unmapped.*" in the
 hid_info_t data structure, and map them to actual NUT variables and
 instant commands. There are currently no step-by-step instructions for
 how to do this. Please look at the files to see how the currently implemented
-subdrivers are written.:
+subdrivers are written:
 
 - apc-hid.c/h
 - belkin-hid.c/h
@@ -188,10 +225,29 @@ subdrivers are written.:
 - tripplite-hid.c/h
 
 
+Fixing report descriptors
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is a fact of life that fellow developers make mistakes, and firmware
+authors do too. In some cases there are inconsistencies about bytes seen
+on the wire vs. their logical values, such value range and signedness if
+interpreting them according to standard.
+
+NUT drivers now include a way to detect and fix up known issues in such
+flawed USB report descriptors, side-stepping the standard similarly where
+deemed needed. A pointer to such hook method is part of the `subdriver_t`
+structure detailing each `usbhid-ups` subdriver nuances, defaulting to
+a `fix_report_desc()` trivial implementation.
+
+For some practical examples, see e.g. `apc_fix_report_desc()` method in the
+`drivers/apc-hid.c` file, and `cps_fix_report_desc()` in `drivers/cps-hid.c`
+file.
+
+
 Shutting down the UPS
 ~~~~~~~~~~~~~~~~~~~~~
 
-It is desireable to support shutting down the UPS. Usually (for
+It is desirable to support shutting down the UPS. Usually (for
 devices that follow the HID Power Device Class specification), this
 requires sending the UPS two commands. One for shutting down the UPS
 (with an 'offdelay') and one for restarting it (with an 'ondelay'),