PR 291774: expand range of errors reported by libusb_open(3)

[unitrunker_unitrunker.net]

Summary

Expand the range of errors reported by libusb_open.

Currently, libusb_open reports LIBUSB_SUCCESS and LIBUSB_ERROR_NO_MEM. The latter is, in most cases, misleading. A failure is more likely to be permissions or a device that is in use elsewhere. Conveying the issue to the client software, and ultimately to the user gives the user the opportunity to better diagnose and remedy the problem.

Test Plan

Tests

1. LIBUSB_ERROR_BUSY - open the same device twice
2. LIBUSB_ERROR_NO_DEVICE - get list of devices, pause, unplug device, attempt to open the unplugged device.
3. LIBUSB_ERROR_ACCESS - get list of devices, pause, alter permissions on the device node, attempt to open a device.
4. LIBUSB_ERROR_INVALID_PARAM - pass a null device handle.
5. LIBUSB_ERROR_NO_MEM - get list of devices, pause, simulate heap full, attempt to open a device.

A program covering the above tests - included in Bugzilla - has been run against actual hardware to verify correctness.

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=291774

Update: a set of twenty one unit tests added. These can be run from kyua and do not require physical hardware.

usb_opener_atf/build $ kyua test
usb_opener:test_case_libusb20_access -> passed [0.002s]
usb_opener:test_case_libusb20_busy -> passed [0.002s]
usb_opener:test_case_libusb20_invalid -> passed [0.002s]
usb_opener:test_case_libusb20_no_device -> passed [0.002s]
usb_opener:test_case_libusb20_no_mem -> passed [0.002s]
usb_opener:test_case_libusb20_other -> passed [0.002s]
usb_opener:test_case_libusb20_success -> passed [0.002s]
usb_opener:test_case_libusb_access -> passed [0.002s]
usb_opener:test_case_libusb_busy -> passed [0.002s]
usb_opener:test_case_libusb_invalid -> passed [0.002s]
usb_opener:test_case_libusb_no_device -> passed [0.002s]
usb_opener:test_case_libusb_no_mem -> passed [0.002s]
usb_opener:test_case_libusb_other -> passed [0.002s]
usb_opener:test_case_libusb_success -> passed [0.003s]
usb_opener:test_case_libusb_with_vid_pid_access -> passed [0.002s]
usb_opener:test_case_libusb_with_vid_pid_busy -> passed [0.002s]
usb_opener:test_case_libusb_with_vid_pid_invalid -> passed [0.002s]
usb_opener:test_case_libusb_with_vid_pid_no_device -> passed [0.002s]
usb_opener:test_case_libusb_with_vid_pid_no_mem -> passed [0.002s]
usb_opener:test_case_libusb_with_vid_pid_other -> passed [0.002s]
usb_opener:test_case_libusb_with_vid_pid_success -> passed [0.002s]

Results file id is usb_opener_atf_build.20251220-103547-089277
Results saved to ~/.kyua/store/results.usb_opener_atf_build.20251220-103547-089277.db

21/21 passed (0 broken, 0 failed, 0 skipped)

[unitrunker_unitrunker.net]

D54296: Bug 291774: expand range of errors reported by libusb_open(3)
Unexpected one-line fix to backend.

[unitrunker_unitrunker.net]

The BUSY test currently fails because we're are blocked by D54218. Currently, opening the same device twice (via a different backend or dev-list) isn't an error. I'm proposing we proceed as-is. If/when D54218 is accepted, this code need not change.

[unitrunker_unitrunker.net]

For test #5 above, the unit test "hooks" malloc - using dlsym to force a NULL return on demand to simulate a "NO MEM" condition.

[kib]

I have no idea about USB code

lib/libusb/libusb20_ugen20.c

396–397

[unitrunker_unitrunker.net]

D54296: PR 291774: expand range of errors reported by libusb_open(3)
line too long

[unitrunker_unitrunker.net]

thanks @kib!

[unitrunker_unitrunker.net]

D54296: PR 291774: expand range of errors reported by libusb_open(3)
Kyua unit tests included in build

[unitrunker_unitrunker.net]

Repository

rG FreeBSD src repository

Lint

Lint Passed

Unit

**No Test Coverage**	<-- this

Build Status

Buildable 69414	
Build 66297: arc lint + arc unit

Clearly I have test coverage. No idea how to get phabricator to show that.

[unitrunker_unitrunker.net]

D54296: PR 291774: expand range of errors reported by libusb_open(3)
rebased to latest