[CI/validation] Run hotplug tests against all four backend implementations (do not merge)

.github/vmrun-libusb.sh

@@ -14,8 +14,25 @@ modprobe dummy_hcd || true
 modprobe raw_gadget || true
 ls -l /dev/raw-gadget || true
 
-ctest --test-dir build --output-on-failure
-rc=$?
+rc=0
+for test in DeviceIO_libusb HotplugAPI_libusb Hotplug_libusb; do
+    listed=$(ctest --test-dir build -N -R "^${test}$" 2>&1)
+    listed_rc=$?
+    printf '%s\n' "$listed"
+    if [ "$listed_rc" -ne 0 ] || ! printf '%s\n' "$listed" | grep -q 'Total Tests: 1'; then
+        echo "Required CTest case '${test}' was not found."
+        rc=1
+        continue
+    fi
+
+    result=$(ASAN_OPTIONS=detect_leaks=0 ctest --test-dir build -R "^${test}$" --output-on-failure 2>&1)
+    result_rc=$?
+    printf '%s\n' "$result"
+    if [ "$result_rc" -ne 0 ] || ! printf '%s\n' "$result" | grep -Eq "^[[:space:]]*1/1 Test #[0-9]+: ${test} .* [P]assed[[:space:]]+[0-9]+([.][0-9]+)?[[:space:]]+sec[[:space:]]*$"; then
+        echo "Required CTest case '${test}' did not pass."
+        rc=1
+    fi
+done
 
 echo "=== diag ==="
 lsmod | grep -E "raw_gadget|dummy_hcd|udc" || true

.github/workflows/builds.yml

@@ -56,14 +56,16 @@ jobs:
     - name: Build CMake Framework
       working-directory: build/framework
       run: make install
-    - name: Run virtual-device tests (IOHIDUserDevice self-skips on hosted CI)
+    - name: Run device-I/O and hotplug lifecycle tests
       working-directory: build/shared
       run: |
         # The macOS virtual device needs the com.apple.developer.hid.virtual.device
         # entitlement and interactive user consent, neither available on a hosted
         # runner, so DeviceIO_darwin self-skips (CTest code 77). This still
         # verifies the provider builds and the test runs/links.
-        ASAN_OPTIONS=detect_leaks=0 ctest --output-on-failure
+        # Verbose output also reports individual hotplug cases skipped when
+        # no real device is available; device-independent lifecycle checks run.
+        ASAN_OPTIONS=detect_leaks=0 ctest --verbose --output-on-failure
     - name: Check artifacts
       uses: andstor/file-existence-action@v2
       with:

.github/workflows/libusb-vhid-test.yml

@@ -1,13 +1,15 @@
 name: Linux libusb Virtual HID Device Test (manual)
 
-# Runs the device-I/O test against the HIDAPI *libusb* backend using a real
-# virtual USB HID device (USB Raw Gadget on top of dummy_hcd).
+# Runs the device-I/O and hotplug tests against the HIDAPI *libusb* backend
+# using a real virtual USB HID device (USB Raw Gadget on top of dummy_hcd).
 #
 # The hosted ubuntu-latest (azure) kernel is built without the USB gadget
 # subsystem, so raw_gadget/dummy_hcd can't be loaded (or even built) there. We
 # therefore run the test inside a lightweight VM (virtme-ng + QEMU) booting a
-# *generic* Ubuntu kernel, whose linux-modules-extra ships dummy_hcd and
-# raw_gadget. The VM shares the host filesystem, so it runs the binaries built
+# *generic* Ubuntu kernel: linux-modules-extra supplies raw_gadget; Ubuntu does
+# not package dummy_hcd, so this workflow builds it from matching upstream
+# kernel source against that kernel's headers and installs it alongside. The VM
+# shares the host filesystem, so it runs the binaries built
 # on the host. The same approach works locally and on WSL2 (which also lacks
 # those modules in its default kernel).
 #
@@ -42,6 +44,8 @@ jobs:
         find "/lib/modules/${KVER}" \( -name 'raw_gadget*' -o -name 'dummy_hcd*' \) || true
 
     - name: Build dummy_hcd for the generic kernel (Ubuntu ships no package)
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
       run: |
         set -eux
         KVER=$(ls -1 /lib/modules | grep -- '-generic$' | sort -V | tail -n1)
@@ -50,8 +54,14 @@ jobs:
         # Ubuntu packages no dummy_hcd; build it from the upstream source that
         # matches the generic kernel's major version (xairy's copy tracks newer
         # kernels and won't compile against an older one).
-        curl -fsSL -o dummyhcd/dummy_hcd.c \
-          "https://raw.githubusercontent.com/torvalds/linux/v${KMAJ}/drivers/usb/gadget/udc/dummy_hcd.c"
+        # Fetch through the authenticated contents API: anonymous runner fetches
+        # from raw.githubusercontent.com are rate-limited (HTTP 429) often enough
+        # to fail the job, and the API path counts against the token's quota.
+        curl -fsSL --retry 6 --retry-delay 15 --retry-all-errors \
+          -H "Authorization: Bearer ${GITHUB_TOKEN}" \
+          -H "Accept: application/vnd.github.raw+json" \
+          -o dummyhcd/dummy_hcd.c \
+          "https://api.github.com/repos/torvalds/linux/contents/drivers/usb/gadget/udc/dummy_hcd.c?ref=v${KMAJ}"
         printf 'obj-m += dummy_hcd.o\n' > dummyhcd/Makefile
         make -C "/lib/modules/${KVER}/build" M="${PWD}/dummyhcd" modules
         sudo install -m 0644 "${PWD}/dummyhcd/dummy_hcd.ko" \
@@ -61,10 +71,10 @@ jobs:
     - name: Build HIDAPI + tests (libusb backend)
       run: |
         cmake -B build -S hidapisrc -DCMAKE_BUILD_TYPE=RelWithDebInfo \
-          -DHIDAPI_WITH_LIBUSB=ON -DHIDAPI_WITH_HIDRAW=OFF -DHIDAPI_WITH_TESTS=ON
+          -DHIDAPI_WITH_LIBUSB=ON -DHIDAPI_WITH_HIDRAW=OFF -DHIDAPI_WITH_TESTS=ON -DHIDAPI_ENABLE_ASAN=ON
         cmake --build build
 
-    - name: Run DeviceIO_libusb inside a VM (generic kernel + raw_gadget)
+    - name: Run the virtual-device tests inside a VM (generic kernel + raw_gadget)
       run: |
         set -eux
         # The generic kernel just installed (has dummy_hcd + raw_gadget modules).

.github/workflows/win-vhid-test.yml

@@ -1,9 +1,9 @@
 name: Windows Virtual HID Device Test (manual)
 
 # Builds and self-signs a modified vhidmini2 UMDF2 driver, installs it on a
-# hosted runner, then runs the backend-agnostic device-I/O test against that
-# real virtual HID device (winapi backend). It installs a driver, so it is not
-# part of the per-push CI matrix; run it on demand from the Actions tab, or by
+# hosted runner, then runs the backend-agnostic device-I/O and hotplug tests
+# against that real virtual HID device (winapi backend). It installs a driver,
+# so it is not part of the per-push CI matrix; run it on demand from the Actions tab, or by
 # adding the 'ci-virtual-device' label to a pull request.
 #
 # The work is split across two runners because no single hosted image can do
@@ -138,14 +138,27 @@ jobs:
     - name: Build HIDAPI + tests
       shell: pwsh
       run: |
-        cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DHIDAPI_WITH_TESTS=ON
+        cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DHIDAPI_WITH_TESTS=ON -DHIDAPI_ENABLE_ASAN=ON
         cmake --build build --config Release
 
-    - name: Run device-I/O test against the virtual device
+    - name: Run device-I/O and hotplug tests against the virtual device
       shell: pwsh
       working-directory: build
       run: |
-        ctest -C Release -R DeviceIO_winapi --output-on-failure
+        $env:ASAN_OPTIONS = "detect_leaks=0"
+        $tests = @("DeviceIO_winapi", "HotplugAPI_winapi", "Hotplug_winapi")
+        foreach ($test in $tests) {
+          $listed = & ctest -C Release -N -R "^$test$" 2>&1 | Out-String
+          if ($LASTEXITCODE -ne 0 -or $listed -notmatch "Total Tests: 1") {
+            throw "Required CTest case '$test' was not found."
+          }
+          $result = & ctest -C Release -R "^$test$" --output-on-failure 2>&1 | Out-String
+          $passed = "(?m)^\s*1/1 Test #\d+: " + [regex]::Escape($test) + ".*\sPassed\s+\d+(?:\.\d+)?\s+sec\s*$"
+          Write-Host $result
+          if ($LASTEXITCODE -ne 0 -or $result -notmatch $passed) {
+            throw "Required CTest case '$test' did not pass."
+          }
+        }
 
     - name: Cleanup virtual device
       if: always()

README.md

@@ -58,11 +58,29 @@ Keyboards, mice, and some other devices which are blacklisted from having
 hidraw nodes will not work. Fortunately, for nearly all the uses of hidraw,
 this is not a problem.
 
+Hotplug delivery is best-effort under kernel event-buffer overruns. An overrun
+or unrecoverable udev monitor failure stops live events without notifying existing
+callbacks; pending initial `ENUMERATE` passes still run. Once the failure is
+recorded, new registrations fail with `-1`, so an application can detect it by
+attempting a registration. Deregister all surviving callbacks before registering
+again to create a fresh monitor.
+
+The initial hotplug snapshot is keyed by `/dev/hidrawN`. If that node is reused
+while the monitor is armed and the snapshot is taken, queued events from its
+predecessor can produce `ARRIVED/LEFT/ARRIVED` for the successor connection.
+
 #### __Linux/FreeBSD/libusb__ (`libusb/hid.c`):
 
 This back-end uses libusb-1.0 to communicate directly to a USB device. This
 back-end will of course not work with Bluetooth devices.
 
+#### __Windows__ (`windows/hid.c`):
+
+Hotplug callbacks require Windows 8 or later. Registration returns `-1` when
+the required PnP notification API is unavailable. Compiler and runtime
+requirements may impose a higher minimum Windows version.
+Starting with HIDAPI 0.16, this back-end requires libusb 1.0.16 or newer.
+
 ### Test GUI
 
 HIDAPI also comes with a Test GUI. The Test GUI is cross-platform and uses

configure.ac

@@ -63,7 +63,7 @@ case $host in
 
 	# HIDAPI/libusb libs
 	AC_CHECK_LIB([rt], [clock_gettime], [LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} -lrt"], [hidapi_lib_error librt])
-	PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.9], true, [hidapi_lib_error libusb-1.0])
+	PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.16], true, [hidapi_lib_error libusb-1.0])
 	LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} $libusb_LIBS"
 	CFLAGS_LIBUSB="${CFLAGS_LIBUSB} $libusb_CFLAGS"
 	;;
@@ -87,7 +87,7 @@ case $host in
 	CFLAGS="$CFLAGS -I/usr/local/include"
 	LDFLAGS="$LDFLAGS -L/usr/local/lib"
 	LIBS="${LIBS}"
-	PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.9], true, [hidapi_lib_error libusb-1.0])
+	PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.16], true, [hidapi_lib_error libusb-1.0])
 	LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} $libusb_LIBS"
 	CFLAGS_LIBUSB="${CFLAGS_LIBUSB} $libusb_CFLAGS"
 	AC_CHECK_LIB([iconv], [iconv_open], [LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} -liconv"], [hidapi_lib_error libiconv])
@@ -100,7 +100,7 @@ case $host in
 	os="kfreebsd"
 	threads="pthreads"
 
-	PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.9], true, [hidapi_lib_error libusb-1.0])
+	PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.16], true, [hidapi_lib_error libusb-1.0])
 	LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} $libusb_LIBS"
 	CFLAGS_LIBUSB="${CFLAGS_LIBUSB} $libusb_CFLAGS"
 	;;
@@ -112,7 +112,7 @@ case $host in
 	os="haiku"
 	threads="pthreads"
 
-	PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.9], true, [hidapi_lib_error libusb-1.0])
+	PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.16], true, [hidapi_lib_error libusb-1.0])
 	LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} $libusb_LIBS"
 	CFLAGS_LIBUSB="${CFLAGS_LIBUSB} $libusb_CFLAGS"
 	AC_CHECK_LIB([iconv], [libiconv_open], [LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} -liconv"], [hidapi_lib_error libiconv])