D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
rebased

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

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
Fixed linter warnings.

D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
RETURN VALUES

D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
punctuation

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
punctuation

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
RETURN VALUES and fix unwanted line break in Bl/El list.

Observation: there's a lot of "dead air" in the left and right margins which makes the overall document taller. I can zoom in to 150% to get the text to fill the width of the screen.
Edit: it does look very, very nice!

Abandoning in favor of D54218

D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
format example

D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
Cloned libusb20_dev_open.3 from D54231

Repository

rG FreeBSD src repository

Lint

Lint Passed

Unit

**No Test Coverage**	<-- this

Build Status

Buildable 69414	
Build 66297: arc lint + arc unit

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

thanks @kib!

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

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

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.

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

what's next?

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
library, not syscall.

The libusb_open issue is logged here: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=291774

D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
style(9) fix

D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
Narrow scope of the review.

In D54218#1240472, @ziaee wrote:

The doc should be changed in the commit that changes the behavior for many reasons, such as bisecting and downstream consumers.

D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
Removing manpage changes because

1. clean up libusb.3 and libusb20.3 represents a lot of work that deserves a separate review review and
2. I don't want to invest that effort until I have buy-in that this change will go forward.

Smaller changesets are easier to review and merge.

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
Replace Va with Fa.

Done!

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.

Updating libusb20_be_device_foreach.3 next.

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
Move SEE ALSO after EXAMPLES.

Done! (thank you @ziaee!)

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
Shorter Nd text w/o periods.

Done!

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
License guide; DESCRIPTION gets intro sentence.

D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
Include libusb.3 and libusb20.3 man pages.

D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
Include LIBUSB_ERROR_NO_DEVICE as possible error for libusb_open.

In D54218#1239800, @ziaee wrote:

Should we document this error in libusb_open and libusb20_dev_open manuals? If so, is better to do it in this commit.

D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
simplify libusb_open

In D54218#1239800, @ziaee wrote:

Should we document this error in libusb_open and libusb20_dev_open manuals? If so, is better to do it in this commit.

The BUSY error is documented in the other review for libusb20_dev_open.3 and already exists in libusb20.3. BUSY is NOT mentioned in libusb.3 for libusb_open.

Compiling and running: ~/work/unit_test_libusb20_dev_open/build/unit_test 0BDA 2838
[ 50%] Building CXX object CMakeFiles/unit_test.dir/unit_test.cpp.o
[100%] Linking CXX executable unit_test
[100%] Built target unit_test
A(1 vs. 1 same) passes.
B(1 vs. 1 differs) passes.
C(1 vs. 0 same) passes.
D(1 vs. 0 differs) passes.
E(0 vs. 1 same) passes.
F(0 vs. 1 differs) passes.
G(0 vs. 0 same) passes.
H(0 vs. 0 differs) passes.

D54218: Introduce libusb20_dev_open_with_flags for shared vs. exclusive access.
Also offer LIBUSB20_OPEN_SHARED.

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
Clip copyright text and place Lb clause under SYNOPSIS.

I think I found some clarity.
https://lists.freebsd.org/archives/freebsd-hackers/2025-June/004719.html

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
lint fix (need clarity on library)

D54218: Introduce libusb20_dev_open_with_flags for exclusive access.
libusb20_dev_open is exclusive. Use libusb20_dev_open_with_flags for shared access.
This makes the unit test matrix simpler and is easier to document since libusb_dev_open already returns LIBUSB20_ERROR_BUSY to two calls to open the same libusb20_device pointer.

Done! What next?

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
USB access library

Maxim K. commited the fix. I've sent an email to phabric-admin@freebsd.org requesting this review be abandoned.

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
Copyright

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
lint fix

D54231: libusb20_dev_open(3) and libusb20_be_device_foreach(3) man pages.
lint fix

D54218: Introduce libusb20_dev_open_with_flags for exclusive access.
Report LIBUSB20_ERROR_BUSY in place of LIBUSB20_ERROR_ACCESS for advisory lock conflicts.

D54218: Introduce libusb20_dev_open_with_flags for exclusive access.
Non-exclusive access also checks for presence of an advisory lock.

The advantage of this review over D54173 is D54218 provides a consistent advisory lock for both libusb20 and libusb clients.

Now I have a dilemma.

Thanks to @aokblast for these comments. I'm thinking of an alternate proposal that moves the exclusivity down to libusb20_dev_open. Something like libusb20_dev_open_exclusive or libusb20_dev_open_with_flags. Opening a device exclusively should appear atomic to the application so it needs to happen inside the open.

In D54173#1238395, @aokblast wrote:

Haven't test it. But I have a comment. It would be great if we can solve multiple device issue like this.

Also, I have another problem. As you have mentioned:

On Linux and Windows, USB device enumeration omits devices currently in use. A number of ports assume this behavior.

Does this happen in libusb layer or udev(winusb) layer?