Introduce an allow_duplicates flag for common USB matching options

[jimklimov]

Closes: #1756

Initially also addressed #1767 (seen in "screenshots" below) but that change was offloaded to PR #1771

Also does minor codebase maintenance, and partially follows up from recent work in PRs:

• Update USB matching options in man pages #1766
• Fix common USB matching options for riello_usb (richcomm and nutdrv_atcl too, but reverted) #1763

May help in situations raised in issues such as:

• riello_usb multiple identical ups USB issue #1744
• The problem is working with several UPS at the same time, connected via USB (Instructions, Setup, Logs) #1754
• Duplicate USB devices don't connect in 2.8.0 #1414
• Proper solution for UPSes without unique serials #1273
• nutdrv_qx multiple identical ups USB issue #1174

Note that use of USB device matching by a unique combination of fields is much more preferable to allow_duplicates (if possible).

---

Example with use of the new feature (while the driver is running as another process):

# NUT_STATEPATH=/tmp NUT_CONFPATH=/etc/nut ./drivers/usbhid-ups -DDDDDD -a eco650 -u nut -x allow_duplicates
Network UPS Tools - Generic HID driver 0.49 (2.8.0-Windows-299-g5e8e40cca)
USB communication driver (libusb 1.0) 0.43
   0.000000     [D3] main_arg: var='driver' val='usbhid-ups'
   0.000015     [D3] main_arg: var='port' val='auto'
   0.000022     [D5] send_to_all: SETINFO driver.parameter.port "auto"
   0.000027     [D3] main_arg: var='vendorid' val='0463'
   0.000033     [D5] send_to_all: SETINFO driver.parameter.vendorid "0463"
   0.000037     [D3] main_arg: var='productid' val='FFFF'
   0.000041     [D5] send_to_all: SETINFO driver.parameter.productid "FFFF"
   0.000046     [D3] main_arg: var='product' val='Ellipse ECO'
   0.000050     [D5] send_to_all: SETINFO driver.parameter.product "Ellipse ECO"
   0.000055     [D3] main_arg: var='desc' val='Eaton Ellipse ECO 650'
   0.000059     [D3] main_arg: var='serial' val='000000000'
   0.000064     [D5] send_to_all: SETINFO driver.parameter.serial "000000000"
   0.000068     [D3] main_arg: var='vendor' val='EATON'
   0.000075     [D5] send_to_all: SETINFO driver.parameter.vendor "EATON"
   0.000079     [D3] main_arg: var='bus' val='003'
   0.000083     [D5] send_to_all: SETINFO driver.parameter.bus "003"
   0.000092     [D1] Built-in default or configured user for drivers 'nobody' was ignored due to 'nut' specified on command line
   0.000098     [D3] main_arg: var='allow_duplicates' val='<null>'
   0.000104     [D5] send_to_all: SETINFO driver.flag.allow_duplicates "enabled"
   0.000107     [D1] debug level is '6'
   0.000653     [D1] Succeeded to become_user(nut): now UID=77 GID=77
   0.000668     [D5] send_to_all: SETINFO device.type "ups"
   0.000672     [D5] send_to_all: SETINFO driver.state "init.device"
   0.000677     [D2] Initializing an USB-connected UPS with library libusb-1.0.24 (API: 0x1000108) (NUT subdriver name='USB communication driver (libusb 1.0)' ver='0.43')
   0.000685     [D1] upsdrv_initups (non-SHUT)...
   0.003570     [D2] Checking device 1 of 9 (1D6B/0003)
   0.003591     [D1] Failed to open device (1D6B/0003), skipping: Access denied (insufficient permissions)
   0.003596     [D2] Checking device 2 of 9 (03F0/0D4A)
   0.003605     [D1] Failed to open device (03F0/0D4A), skipping: Access denied (insufficient permissions)
   0.003609     [D2] Checking device 3 of 9 (1D6B/0002)
   0.003617     [D1] Failed to open device (1D6B/0002), skipping: Access denied (insufficient permissions)
   0.003620     [D2] Checking device 4 of 9 (1D6B/0003)
   0.003627     [D1] Failed to open device (1D6B/0003), skipping: Access denied (insufficient permissions)
   0.003630     [D2] Checking device 5 of 9 (0463/FFFF)
   0.425238     [D2] - VendorID: 0463
   0.425247     [D2] - ProductID: ffff
   0.425252     [D2] - Manufacturer: EATON
   0.425258     [D2] - Product: Ellipse ECO
   0.425262     [D2] - Serial Number: 000000000
   0.425265     [D2] - Bus: 003
   0.425268     [D2] - Device: unknown
   0.425272     [D2] - Device release number: 0100
   0.425275     [D2] Trying to match device
   0.425279     [D2] match_function_subdriver (non-SHUT mode): matching a device...
   0.425285     [D3] match_function_regex: matching a device...
   0.425357     [D2] Device matches
   0.425364     [D2] Reading first configuration descriptor
   0.425373     [D3] libusb_kernel_driver_active() returned 0
   0.425378     [D2] failed to claim USB device: Resource busy
   0.425382     [D2] Configured to allow_duplicates so looking for another similar device
   0.425392     [D2] Checking device 6 of 9 (1D6B/0002)
   0.425406     [D1] Failed to open device (1D6B/0002), skipping: Access denied (insufficient permissions)
   0.425410     [D2] Checking device 7 of 9 (1D6B/0003)
   0.425418     [D1] Failed to open device (1D6B/0003), skipping: Access denied (insufficient permissions)
   0.425422     [D2] Checking device 8 of 9 (048D/5702)
   0.425428     [D1] Failed to open device (048D/5702), skipping: Access denied (insufficient permissions)
   0.425432     [D2] Checking device 9 of 9 (1D6B/0002)
   0.425437     [D1] Failed to open device (1D6B/0002), skipping: Access denied (insufficient permissions)
   0.425442     [D2] libusb1: No appropriate HID device found
   0.425446     libusb1: Could not open any HID devices: insufficient permissions on everything
   0.425449     No matching HID UPS found
   0.425455     [D5] send_to_all: SETINFO driver.state "cleanup.exit"

Example without:

# NUT_STATEPATH=/tmp NUT_CONFPATH=/etc/nut ./drivers/usbhid-ups -DDDDDD -a eco650 -u nut
...
   0.004130     [D2] Checking device 5 of 9 (0463/FFFF)
   0.428824     [D2] - VendorID: 0463
   0.428834     [D2] - ProductID: ffff
   0.428840     [D2] - Manufacturer: EATON
   0.428846     [D2] - Product: Ellipse ECO
   0.428849     [D2] - Serial Number: 000000000
   0.428853     [D2] - Bus: 003
   0.428857     [D2] - Device: unknown
   0.428859     [D2] - Device release number: 0100
   0.428865     [D2] Trying to match device
   0.428869     [D2] match_function_subdriver (non-SHUT mode): matching a device...
   0.428875     [D3] match_function_regex: matching a device...
   0.428945     [D2] Device matches
   0.428949     [D2] Reading first configuration descriptor
   0.428958     [D3] libusb_kernel_driver_active() returned 0
   0.428963     [D2] failed to claim USB device: Resource busy
   0.428968     [D2] Kernel driver already detached
   0.428971     [D2] failed to claim USB device: Resource busy
   0.428975     [D2] Kernel driver already detached
   0.428978     [D2] failed to claim USB device: Resource busy
   0.428982     [D2] Kernel driver already detached
   0.428985     [D2] failed to claim USB device: Resource busy
   0.428990     [D2] Kernel driver already detached
   0.428995     Can't claim USB device [0463:ffff]@0/0: Entity not found
   0.429002     [D5] send_to_all: SETINFO driver.state "cleanup.exit"

[clepple]

if it were up to me, I wouldn't want to take on the burden of user support for non-deterministic device matching. As much as we have tried for feature parity between the libusb-0.1 and 1.0 backends, this might be one of those cases where libusb-1.0 features would work better in the end. But I really don't have time to dig into this particular problem.

[jimklimov]

Well, as far and wide as I could, I've posted warnings about non-determinism into code and docs and PR messages, so there's that. At least it does allow users to handle situations not possible earlier.

On a related although coincidental note, having a discussion with @efuss about matching some Qx devices that are identical for all visible USB parameters but are differentiated by vendor protocol details ("slave number"). To access those nuances a callback mechanism that already exists could probably be used; however USB access must be gained in the first place (so one or more of the drivers would have to hit and skip a busy USB match) to talk Qx to the device and accept/reject it as an overall match.