How libusb/libusb works
libusb is a cross-platform USB access library, not an application. The architecture is a layered C library with a thin public API on top and a set of OS-specific backends underneath.
1. Public API layer
The main consumer-facing boundary is libusb/libusb.h. Applications call into this API to open devices, enumerate endpoints, submit transfers, and register hotplug callbacks. The API is designed to stay stable while platform specifics are hidden.
2. Core library layer
Most shared behavior lives in libusb/core.c, descriptor.c, hotplug.c, sync.c, io.c, and strerror.c. This layer implements device/context management, descriptor parsing, transfer orchestration, synchronous wrappers over async I/O, error translation, and the hotplug subsystem.
3. Internal abstraction boundary
libusb/libusbi.h is the internal contract between the core and the backends. It defines the common internal types, helper routines, and backend hooks so the core can remain portable while each OS implements its own device discovery and I/O semantics.
4. OS backend layer
The libusb/os directory is the portability engine. Each backend maps libusb’s abstract operations onto platform-specific USB or device APIs:
• Linux: linux_usbfs.c, linux_udev.c, linux_netlink.c
• Windows: windows_winusb.c, windows_usbdk.c, windows_common.c, windows_hotplug.c
• macOS/Darwin: darwin_usb.c
• BSD variants, Solaris, Haiku, and a null backend
• WebAssembly/WebUSB: emscripten_webusb.cpp
5. Event and threading model
Asynchronous transfer completion is driven by OS event backends in events_posix.c / events_windows.c and thread helpers in threads_posix.c / threads_windows.c. The core I/O layer uses these to wait for device events, process completion, and support the sync wrappers without exposing platform-specific concurrency primitives to callers.
6. Device discovery and hotplug flow
Discovery starts in the backend, which reports device arrival/removal and enumerates devices. The core normalizes that information into libusb device objects and, when supported, routes notifications through hotplug.c so applications can subscribe to topology changes without polling.
7. Data path for transfers
A typical transfer path is: application submits a transfer through the public API → core validates and queues it in io.c/sync.c → backend performs the platform-specific USB operation → completion is reported back through the event system → callbacks or sync waiters receive the result. This split is key to understanding the library’s architecture.
8. Descriptor and string handling
USB descriptor parsing is centralized in descriptor.c and shared across backends. Backends supply raw descriptor bytes and device information; the core turns that into uniform libusb structures for configurations, interfaces, endpoints, BOS descriptors, and string retrieval.
9. Platform-specific build and packaging
The repo is set up for multiple build systems and platforms: Autotools (configure.ac, Makefile.am), Visual Studio/MSVC projects, Xcode, Android NDK/JNI, and CI workflows across Linux, macOS, Windows, Android, and MSYS2. This reflects the library’s role as a portability layer rather than a single-runtime app.
10. Examples and test harnesses
examples/ contains standalone sample programs that exercise common API paths such as enumeration, hotplug, firmware loading, and transfers. tests/ contains unit/behavior tests and fuzz targets for descriptor parsing and BOS parsing, plus platform-specific checks like umockdev and macOS tests.
11. Fuzzing and regression protection
The tests/fuzz corpus and fuzz entrypoints target parser-heavy code paths, especially USB descriptor parsing. This is important architecturally because the parser sits at the boundary between untrusted device data and internal state.
12. External surface area
The only major external dependency is the host OS USB stack or device interface layer. libusb deliberately does not own USB hardware access directly; instead it adapts to system APIs such as usbfs/udev on Linux, WinUSB/USBDK on Windows, and the native macOS USB stack.
Overall, the diagram should show a stable public C API at the top, shared core services in the middle, and multiple interchangeable OS backends at the bottom, with event/thread support and descriptor parsing crossing those boundaries.
Main entry points: libusbi.h libusbi.h · core.c Core · io.c I/O Engine · configure.ac Build Matrix
Components 23
Public API
Consumer-facing C entrypoints and headers.
- libusb.h · Stable consumer-facing USB API.
libusb/libusb.h
Shared Core
Portable logic shared across all backends.
- Core · Device/context lifecycle and shared orchestration.
libusb/core.c - Descriptors · USB descriptor and string parsing.
libusb/descriptor.c - Hotplug · Device arrival/removal subscription and dispatch.
libusb/hotplug.c - I/O Engine · Asynchronous transfer queueing and completion handling.
libusb/io.c - Sync Wrappers · Synchronous convenience layer built over async I/O.
libusb/sync.c - Errors · Error code to string and message translation.
libusb/strerror.c - libusbi.h · Private ABI between core and OS backends.
libusb/libusbi.h
OS Backends
Platform-specific device and USB integrations.
- Linux USBFS · Linux usbfs device and transfer backend.
libusb/os/linux_usbfs.c - Linux udev · Linux device enumeration and hotplug integration.
libusb/os/linux_udev.c - Linux netlink · Linux kernel notification channel for devices.
libusb/os/linux_netlink.c - WinUSB · Windows USB transport backend.
libusb/os/windows_winusb.c - USBDK · Alternative Windows USB transport backend.
libusb/os/windows_usbdk.c - Windows Common · Shared Windows backend utilities and glue.
libusb/os/windows_common.c - Darwin USB · macOS and Darwin USB backend.
libusb/os/darwin_usb.c - WebUSB · Emscripten/WebUSB backend.
libusb/os/emscripten_webusb.cpp - Posix Events · POSIX event waiting and completion dispatch.
libusb/os/events_posix.c - Win Events · Windows event waiting and completion dispatch.
libusb/os/events_windows.c - Posix Threads · POSIX threading helpers used by the core.
libusb/os/threads_posix.c - Win Threads · Windows threading helpers used by the core.
libusb/os/threads_windows.c
Support
Examples, tests, and build/packaging surfaces.
- Examples · Standalone programs demonstrating API usage.
- Tests · Unit, behavior, and fuzz regression coverage.
- Build Matrix · Autotools, MSVC, Xcode, Android, and CI packaging.
configure.ac
Connections 27
- libusb.h → Core: calls · Applications invoke public API entrypoints that reach core services.
- Core → Descriptors: uses · Core normalizes raw descriptor data into libusb structures.
- Core → Hotplug: routes · Core publishes supported device topology changes to subscribers.
- Core → I/O Engine: queues · Core delegates transfer orchestration to the I/O layer.
- Sync Wrappers → I/O Engine: wraps · Blocking calls are implemented on top of asynchronous I/O.
- Core → Errors: reports · Core maps internal failures to stable public errors.
- Core → libusbi.h: contracts · Core and backends share private types and hooks through this boundary.
- I/O Engine → Posix Events: waits on · POSIX platforms use event backends for completion processing.
- I/O Engine → Win Events: waits on · Windows platforms use event backends for completion processing.
- Core → Posix Threads: spawns · POSIX threading helpers support concurrent progress and sync waits.
- Core → Win Threads: spawns · Windows threading helpers support concurrent progress and sync waits.
- libusbi.h → Linux USBFS: hooks · Linux backend implements the shared backend contract.
- libusbi.h → Linux udev: hooks · Linux discovery backend implements the shared backend contract.
- libusbi.h → Linux netlink: hooks · Linux notification backend implements the shared backend contract.
- libusbi.h → WinUSB: hooks · Windows transport backend implements the shared backend contract.
- libusbi.h → USBDK: hooks · Windows alternate transport backend implements the shared backend contract.
- libusbi.h → Windows Common: shared by · Windows-specific backends share utilities and glue.
- libusbi.h → Darwin USB: hooks · Darwin backend implements the shared backend contract.
- libusbi.h → WebUSB: hooks · WebUSB backend implements the shared backend contract.
- Posix Events → Linux USBFS: drives · POSIX event handling services Linux-style asynchronous operation.
- Win Events → WinUSB: drives · Windows event handling services WinUSB operations.
- Examples → libusb.h: uses · Sample programs exercise the public API.
- Tests → Descriptors: targets · Parser and regression tests focus on descriptor handling.
- Tests → Core: exercises · Behavioral tests cover context and option handling.
- Build Matrix → libusb.h: packages · Build systems assemble the library and its public surface.
- Build Matrix → Examples: builds · Packaging includes sample programs.
- Build Matrix → Tests: builds · Packaging includes validation and fuzz targets.