[nmbro]

Stacked on #3782 (configure-libusb-auto-fallback): its two commits
(build: accept libusb-1.0 from 1.0.9 on, build: fall back to libusb-0.1 if libusb-1.0 is too old) are at the bottom of this branch.
Please review #3782 first. The commits for this PR are the last five.
I'll rebase once #3782 is merged.

What and why

On Windows, libusb-0.1 (libusb-win32 with libusb0.sys, or
libusb-compat) has nothing over libusb-1.0 with the WinUSB driver.
It also lacks the async and threading support some drivers need
(e.g. apcmicrolink). This branch makes libusb-1.0 the only USB
backend for MinGW/MSYS2 builds.

1. scripts/Windows: update wdi-simple for WinUSB
   • The driver installer still installed libusb0.sys, which
     libusb-1.0 cannot use without libusbK.dll. It now installs
     WinUSB by default, with libusbK as an option.
   • Bug fixes:
     • It looped until a 0xFFFF/0xFFFF entry, but the generated
       nutscan-usb.h table ends with {0, 0}, so it read past the
       end.
     • It could return an uninitialized value.
     • It passed an extra printf argument.
     • It never parsed its options or freed the device list.
   • Composite devices are now matched on their first interface.
   • The README was rewritten for current libwdi (the old SourceForge
     wiki and ddk_build.cmd are gone). The WiX installer text now
     points at Zadig/WinUSB.
2. build: remove libusb-0.1 support for Windows
   • configure refuses --with-usb=libusb-0.1 for mingw targets,
     ignores an auto-detected libusb-0.1 there, and no longer looks
     for lusb0_usb.h or in /mingw64/lib.
   • libusb0.c errors out on WIN32 and loses its Windows-only code.
   • blazer_usb.c no longer skips LIBUSB_ERROR_OVERFLOW on
     Windows; that was a libusb-win32 limitation.
   • Docs, nut-usbinfo.pl and AppVeyor drop libusb-win32 and
     libusb-compat.
   • NEWS and UPGRADING are updated: packagers depend on libusb-1.0,
     and devices bound to libusb0.sys must be re-bound to WinUSB.
3. fix(wincompat): drop libusb-win32 ETIMEDOUT fallback
   • #define ETIMEDOUT 116 came from libusb-win32's error.h.
     MinGW's errno.h defines it as 138, so the fallback was dead
     code, and with libusb-0.1 gone its FIXME no longer applies.
4. docs(install): document WinUSB/Zadig setup for USB devices
   • A new "USB-connected devices" section for Windows covers binding
     the UPS to WinUSB with Zadig or wdi-simple, and the Windows 7
     minimum of Zadig/libwdi.
   • The historical MSI section now says it used libusb-win32, and
     points to the WiX installer work (Investigate and make use of Windows Installer code in NUT for Windows codebase #1485).
5. fix(nut-scanner): call libusb-1.0 methods with LIBUSB_CALL
   • Found while testing 32-bit builds of this branch: nut-scanner -U
     crashed (SIGSEGV in libusb_get_device_descriptor@8). On 32-bit
     Windows, libusb-1.0 exports its methods as __stdcall
     (LIBUSB_CALL is WINAPI there), but nut-scanner called them
     through default cdecl function pointers, which misaligned the
     stack. The pointers are now declared with LIBUSB_CALL.
   • LIBUSB_CALL is empty on other platforms, and 64-bit Windows has
     a single calling convention, so nothing else changes.
   • This was already broken on master. It matters more now that
     libusb-1.0 is the only USB backend on Windows.

Closes: #1507

Testing

Native MSYS2 UCRT64 on Windows 11 (fresh install), gcc 16.2.0 (Rev6),
libusb 1.0.30. Configured with
--with-usb --enable-Werror CFLAGS='-g -O2 -D_WIN32_WINNT=0x0601'
(Windows 7 API level):

• configure: build USB drivers: yes (libusb-1.0).
• make with -Werror: no warnings.
  • Caveat: on master, UCRT64 -Werror builds also fail in
    common/strptime.c ('tzname' is deprecated ... UCRT). That is
    unrelated to this PR and fixed in a separate branch. For this
    test, only that file was temporarily replaced with the fixed one.
• make check: 16 passed, 1 skipped (become_user() needs root).
  make check took about 2 minutes.

Real hardware: APC Smart-UPS 500 (051d:0003, FW UPS 16.1 / ID=1052),
bound to WinUSB with Zadig, read-only:

• nut-scanner -U found it: driver = "usbhid-ups"
  (alternately apc_modbus apcmicrolink), vendorid = "051D",
  productid = "0003", with serial and bus. Exit code 0.
• apcmicrolink -d 1 -x port=auto: Microlink HID tunnel found (Output
  Report 0x90, Input Report 0x89), ups.status: OL,
  battery.charge: 100, driver.version.usb: libusb-1.0.30 (API: 0x0100010C). Exit code 0.
• usbhid-ups -d 1 -x port=auto, for comparison: APC HID 0.102
  subdriver, ups.status: OL, battery.runtime: 1348, the same libusb
  version. Exit code 0.
• Earlier (on the first commits): apcmicrolink and nut-scanner with
  the same UPS on Windows 10.

32-bit: MSYS2 MINGW32 (i686, MSVCRT), gcc 16.2.0, libusb 1.0.30 built
from source (MSYS2 no longer packages libusb for MINGW32), same
configure flags:

• Two existing master bugs had to be worked around with files from a
  separate branch with Windows fixes; they are unrelated to this PR:
  • configure fails when CFLAGS are set, because
    m4/nut_stash_warnings.m4 overwrites the TMP environment variable,
    and gcc then cannot create its temporary files.
  • PRIuSIZE is hard-coded "llu" for all Windows builds, but size_t
    is 32 bits on WIN32, so 2 tests fail (parseconf-test,
    nutdrv_qx_cypress_utest).
• With those two fixes: make with -Werror gives no warnings, and
  make check passes 14 of 14 tests (1 skipped, become_user()).
• Real UPS, read-only, 32-bit binaries:
  • apcmicrolink and usbhid-ups: ups.status: OL, libusb-1.0.30.
  • nut-scanner -U: crashed before commit 5; finds the UPS with it.
• Timings (8-core machine): configure 290 s, make 323 s, make check
  187 s with the PRIuSIZE failures and 110 s without them.
• Commit 5 was also rebuilt for UCRT64 (64-bit) with -Werror: no
  warnings, and nut-scanner -U still finds the UPS.

Not tested:

• The 64-bit MINGW64 (MSVCRT) environment locally: current MSYS2 no
  longer packages libusb for MINGW64 (only for UCRT64 and CLANG64).
  AppVeyor still builds there, with the libusb package from its older
  MSYS2 image, so CI covers that build.
• wdi-simple binding a device itself: Zadig was used.
• The WiX installer.
• Any device other than this UPS.
• AppVeyor CI on this branch, which runs once the PR is opened.

AI disclosure

Prepared with Claude Code (Claude Opus 5.5, model claude-opus-5-5):
code, docs, test runs and this description. I reviewed the changes and
ran the hardware tests with my own UPS. I take responsibility for the
submission.

🤖 Generated with Claude Code

[github-actions]

A ZIP file with standard source tarball and another tarball with pre-built docs for commit e2ed286 is temporarily available: NUT-tarballs-PR-3791.zip.

[jimklimov]

Quite solid, thanks!

[AppVeyorBot]

✅ Build nut 2.8.5.5888-master completed (commit 19c34d3158 by @jimklimov)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.5888-master.7z
• ccache: 30 of 577 compilations were cache hits (5.2%); cache size 749 of 750 MiB after cleanup

[AppVeyorBot]

✅ Build nut 2.8.5.5888-master completed (commit 19c34d3158 by @jimklimov)