A new pure-Rust library for cross-platform low-level access to USB devices.

the event loop may deadlock because it drops Arc<LinuxDevice>s while DEVICES is locked. Dropping a LinuxDevice will unregister its fd, which locks DEVICES reentrantly.

problem seen in the wild, backtrace from gdb:

#0  syscall () at ../sysdeps/unix/sysv/linux/x86_64/syscall.S:38
#1  0x0000562ffff02214 in std::sys::unix::futex::futex_wait () at library/std/src/sys/unix/futex.rs:62
#2  std::sys::unix::locks::futex_mutex::Mutex::lock_contended () at library/std/src/sys/unix/locks/futex_mutex.rs:56
#3  0x0000562fffb3cc2d in std::sys::unix::locks::futex_mutex::Mutex::lock (self=<optimized out>)
    at /rustc/e0d7ed1f453fb54578cc96dfea859b0e7be15016/library/std/src/sys/unix/locks/futex_mutex.rs:28
#4  std::sync::mutex::Mutex<slab::Slab<alloc::sync::Weak<nusb::platform::linux_usbfs::device::LinuxDevice, alloc::alloc::Global>>>::lock<slab::Slab<alloc::sync::Weak<nusb::platform::linux_usbfs::device::LinuxDevice, alloc::alloc::Global>>> (self=<optimized out>)
    at /rustc/e0d7ed1f453fb54578cc96dfea859b0e7be15016/library/std/src/sync/mutex.rs:273
#5  nusb::platform::linux_usbfs::events::unregister (fd=<optimized out>, events_id=0) at src/platform/linux_usbfs/events.rs:48
#6  0x0000562fffb3a245 in nusb::platform::linux_usbfs::device::{impl#1}::drop (self=<optimized out>)
    at src/platform/linux_usbfs/device.rs:116
#7  core::ptr::drop_in_place<nusb::platform::linux_usbfs::device::LinuxDevice> ()
    at /rustc/e0d7ed1f453fb54578cc96dfea859b0e7be15016/library/core/src/ptr/mod.rs:497
#8  alloc::sync::Arc<nusb::platform::linux_usbfs::device::LinuxDevice, alloc::alloc::Global>::drop_slow<nusb::platform::linux_usbfs::device::LinuxDevice, alloc::alloc::Global> (self=<optimized out>)
    at /rustc/e0d7ed1f453fb54578cc96dfea859b0e7be15016/library/alloc/src/sync.rs:1751
#9  0x0000562fffb3cf29 in alloc::sync::{impl#33}::drop<nusb::platform::linux_usbfs::device::LinuxDevice, alloc::alloc::Global> (
    self=0x7fad8f800b28) at /rustc/e0d7ed1f453fb54578cc96dfea859b0e7be15016/library/alloc/src/sync.rs:2407
#10 core::ptr::drop_in_place<alloc::sync::Arc<nusb::platform::linux_usbfs::device::LinuxDevice, alloc::alloc::Global>> ()
    at /rustc/e0d7ed1f453fb54578cc96dfea859b0e7be15016/library/core/src/ptr/mod.rs:497
#11 nusb::platform::linux_usbfs::events::event_loop () at src/platform/linux_usbfs/events.rs:63
#12 0x0000562fffb3bdc6 in core::ops::function::FnOnce::call_once<fn(), ()> ()
    at /rustc/e0d7ed1f453fb54578cc96dfea859b0e7be15016/library/core/src/ops/function.rs:250
#13 std::sys_common::backtrace::__rust_begin_short_backtrace<fn(), ()> (f=<optimized out>)
    at /rustc/e0d7ed1f453fb54578cc96dfea859b0e7be15016/library/std/src/sys_common/backtrace.rs:154
#14 0x0000562fffb392e1 in std::thread::{impl#0}::spawn_unchecked_::{closure#1}::{closure#0}<fn(), ()> ()
    at /rustc/e0d7ed1f453fb54578cc96dfea859b0e7be15016/library/std/src/thread/mod.rs:529

Important for some use cases, but I'm not going to go as far as libusb to support this on WIndows -- libusb will temporarily claim a random interface just to submit a control transfer that is not necessarily related to that interface. So this is Linux-only, and portable code will need to use the Interface method. Should be supportable on macOS as well.

Windows serializes IN transfers by default, negating the usefulness of Queue. RAW_IO disables this.

Libusb is adding an option for RAW_IO and decided to not turn it on by default for fear of breaking existing code that makes requests that are not a multiple of maxPacketSize. But nusb has no such consideration, and already documents that IN transfers must be a multiple of maxPacketSize, because it's a good idea anyway to avoid errors on overflow. I think RAW_IO should just be turned on unconditionally, and not doing so is just failing to provide the streaming behavior that users would expect.

• Linux
  • Typically udev
    • Rust udev crate looks good, but wraps a C library.
  • There's also a way to get events directly from the kernel with a NETLINK_KOBJECT_UEVENT socket
• Windows
  • RegisterDeviceNotification or CM_Register_Notification
• macOS
  • IONotificationPortCreate

For Rust async, it's normal for futures not to have their own timeouts. To implement a timeout you race the future with a timeout future such that the main future will be cancelled if the timeout completes first. But this requires a reactor to provide timer functionality as a generic future, and I want to make nusb not require pulling in tokio or async-std for the common case where you don't actually need async in the rest of the app.

futures_lite::future::block_on is implemented on top of parking, which has an API with a timeout. So we could see if futures_lite would add a timeout (seems like many uses of blocking on async IO would want this?), find another implementation that has this to recommend, or copy that code here.

https://developer.apple.com/documentation/iokit/usb_h_user-space

@ktemkin's code in https://github.com/ktemkin/usrs would be a good starting point for this, and I'd like to avoid duplicating efforts if she plans to continue developing it.

This PR adds methods to DeviceInfo to get either un-parsed descriptors (as raw bytes), or parsed descriptors (as a tree of Configuration, Interface, InterfaceAlternateSetting, Endpoint) structs.

Parsing is based off what libusb does, API is similar to rusb's.

Tested working on Linux and Windows. On windows it's only possible to get descriptors for winusb devices.