# libusb/libusb architecture

> Architecture diagram of the GitHub repository libusb/libusb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/libusb/libusb
- Repository: https://github.com/libusb/libusb

## Overview

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: [`libusb/libusbi.h`](https://github.com/libusb/libusb/blob/master/libusb/libusbi.h) (libusbi.h), [`libusb/core.c`](https://github.com/libusb/libusb/blob/master/libusb/core.c) (Core), [`libusb/io.c`](https://github.com/libusb/libusb/blob/master/libusb/io.c) (I/O Engine), [`configure.ac`](https://github.com/libusb/libusb/blob/master/configure.ac) (Build Matrix)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_libusb_h["libusb.h<br/>public API<br/>[libusb.h]"]
end

subgraph group_core["Shared Core"]
  node_core_c["Core<br/>[core.c]"]
  node_descriptor_c["Descriptors<br/>parser<br/>[descriptor.c]"]
  node_hotplug_c(("Hotplug<br/>notifications<br/>[hotplug.c]"))
  node_io_c["I/O Engine<br/>transfer scheduling<br/>[io.c]"]
  node_sync_c["Sync Wrappers<br/>blocking API<br/>[sync.c]"]
  node_strerror_c["Errors<br/>translation<br/>[strerror.c]"]
  node_libusbi_h["libusbi.h<br/>internal contract<br/>[libusbi.h]"]
end

subgraph group_os["OS Backends"]
  node_linux_usbfs["Linux USBFS<br/>linux backend<br/>[linux_usbfs.c]"]
  node_linux_udev["Linux udev<br/>linux discovery<br/>[linux_udev.c]"]
  node_linux_netlink["Linux netlink<br/>linux events<br/>[linux_netlink.c]"]
  node_windows_winusb["WinUSB<br/>windows backend<br/>[windows_winusb.c]"]
  node_windows_usbdk["USBDK<br/>windows backend<br/>[windows_usbdk.c]"]
  node_windows_common["Windows Common<br/>windows support<br/>[windows_common.c]"]
  node_darwin_usb["Darwin USB<br/>macOS backend<br/>[darwin_usb.c]"]
  node_emscripten_webusb["WebUSB<br/>wasm backend"]
  node_events_posix(("Posix Events<br/>event loop<br/>[events_posix.c]"))
  node_events_windows(("Win Events<br/>event loop<br/>[events_windows.c]"))
  node_threads_posix(("Posix Threads<br/>threading<br/>[threads_posix.c]"))
  node_threads_windows(("Win Threads<br/>threading<br/>[threads_windows.c]"))
end

subgraph group_support["Support"]
  node_examples["Examples<br/>sample apps"]
  node_tests["Tests<br/>regression suite"]
  node_build["Build Matrix<br/>packaging<br/>[configure.ac]"]
end

node_libusb_h -->|"calls"| node_core_c
node_core_c -->|"uses"| node_descriptor_c
node_core_c -->|"routes"| node_hotplug_c
node_core_c -->|"queues"| node_io_c
node_sync_c -->|"wraps"| node_io_c
node_core_c -->|"reports"| node_strerror_c
node_core_c -->|"contracts"| node_libusbi_h
node_io_c -->|"waits on"| node_events_posix
node_io_c -->|"waits on"| node_events_windows
node_core_c -->|"spawns"| node_threads_posix
node_core_c -->|"spawns"| node_threads_windows
node_libusbi_h -->|"hooks"| node_linux_usbfs
node_libusbi_h -->|"hooks"| node_linux_udev
node_libusbi_h -->|"hooks"| node_linux_netlink
node_libusbi_h -->|"hooks"| node_windows_winusb
node_libusbi_h -->|"hooks"| node_windows_usbdk
node_libusbi_h -->|"shared by"| node_windows_common
node_libusbi_h -->|"hooks"| node_darwin_usb
node_libusbi_h -->|"hooks"| node_emscripten_webusb
node_events_posix -->|"drives"| node_linux_usbfs
node_events_windows -->|"drives"| node_windows_winusb
node_examples -->|"uses"| node_libusb_h
node_tests -->|"targets"| node_descriptor_c
node_tests -->|"exercises"| node_core_c
node_build -->|"packages"| node_libusb_h
node_build -->|"builds"| node_examples
node_build -->|"builds"| node_tests

click node_libusb_h "https://github.com/libusb/libusb/blob/master/libusb/libusb.h"
click node_core_c "https://github.com/libusb/libusb/blob/master/libusb/core.c"
click node_descriptor_c "https://github.com/libusb/libusb/blob/master/libusb/descriptor.c"
click node_hotplug_c "https://github.com/libusb/libusb/blob/master/libusb/hotplug.c"
click node_io_c "https://github.com/libusb/libusb/blob/master/libusb/io.c"
click node_sync_c "https://github.com/libusb/libusb/blob/master/libusb/sync.c"
click node_strerror_c "https://github.com/libusb/libusb/blob/master/libusb/strerror.c"
click node_libusbi_h "https://github.com/libusb/libusb/blob/master/libusb/libusbi.h"
click node_linux_usbfs "https://github.com/libusb/libusb/blob/master/libusb/os/linux_usbfs.c"
click node_linux_udev "https://github.com/libusb/libusb/blob/master/libusb/os/linux_udev.c"
click node_linux_netlink "https://github.com/libusb/libusb/blob/master/libusb/os/linux_netlink.c"
click node_windows_winusb "https://github.com/libusb/libusb/blob/master/libusb/os/windows_winusb.c"
click node_windows_usbdk "https://github.com/libusb/libusb/blob/master/libusb/os/windows_usbdk.c"
click node_windows_common "https://github.com/libusb/libusb/blob/master/libusb/os/windows_common.c"
click node_darwin_usb "https://github.com/libusb/libusb/blob/master/libusb/os/darwin_usb.c"
click node_emscripten_webusb "https://github.com/libusb/libusb/blob/master/libusb/os/emscripten_webusb.cpp"
click node_events_posix "https://github.com/libusb/libusb/blob/master/libusb/os/events_posix.c"
click node_events_windows "https://github.com/libusb/libusb/blob/master/libusb/os/events_windows.c"
click node_threads_posix "https://github.com/libusb/libusb/blob/master/libusb/os/threads_posix.c"
click node_threads_windows "https://github.com/libusb/libusb/blob/master/libusb/os/threads_windows.c"
click node_build "https://github.com/libusb/libusb/blob/master/configure.ac"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_libusb_h toneBlue
class node_core_c,node_descriptor_c,node_hotplug_c,node_io_c,node_sync_c,node_strerror_c,node_libusbi_h toneAmber
class node_linux_usbfs,node_linux_udev,node_linux_netlink,node_windows_winusb,node_windows_usbdk,node_windows_common,node_darwin_usb,node_emscripten_webusb,node_events_posix,node_events_windows,node_threads_posix,node_threads_windows toneMint
class node_examples,node_tests,node_build toneRose
```

## Components

### Public API

Consumer-facing C entrypoints and headers.

- [libusb.h](https://github.com/libusb/libusb/blob/master/libusb/libusb.h): public API · Stable consumer-facing USB API. · `libusb/libusb.h`

### Shared Core

Portable logic shared across all backends.

- [Core](https://github.com/libusb/libusb/blob/master/libusb/core.c): context/device core · Device/context lifecycle and shared orchestration. · `libusb/core.c`
- [Descriptors](https://github.com/libusb/libusb/blob/master/libusb/descriptor.c): parser · USB descriptor and string parsing. · `libusb/descriptor.c`
- [Hotplug](https://github.com/libusb/libusb/blob/master/libusb/hotplug.c): notifications · Device arrival/removal subscription and dispatch. · `libusb/hotplug.c`
- [I/O Engine](https://github.com/libusb/libusb/blob/master/libusb/io.c): transfer scheduling · Asynchronous transfer queueing and completion handling. · `libusb/io.c`
- [Sync Wrappers](https://github.com/libusb/libusb/blob/master/libusb/sync.c): blocking API · Synchronous convenience layer built over async I/O. · `libusb/sync.c`
- [Errors](https://github.com/libusb/libusb/blob/master/libusb/strerror.c): translation · Error code to string and message translation. · `libusb/strerror.c`
- [libusbi.h](https://github.com/libusb/libusb/blob/master/libusb/libusbi.h): internal contract · Private ABI between core and OS backends. · `libusb/libusbi.h`

### OS Backends

Platform-specific device and USB integrations.

- [Linux USBFS](https://github.com/libusb/libusb/blob/master/libusb/os/linux_usbfs.c): linux backend · Linux usbfs device and transfer backend. · `libusb/os/linux_usbfs.c`
- [Linux udev](https://github.com/libusb/libusb/blob/master/libusb/os/linux_udev.c): linux discovery · Linux device enumeration and hotplug integration. · `libusb/os/linux_udev.c`
- [Linux netlink](https://github.com/libusb/libusb/blob/master/libusb/os/linux_netlink.c): linux events · Linux kernel notification channel for devices. · `libusb/os/linux_netlink.c`
- [WinUSB](https://github.com/libusb/libusb/blob/master/libusb/os/windows_winusb.c): windows backend · Windows USB transport backend. · `libusb/os/windows_winusb.c`
- [USBDK](https://github.com/libusb/libusb/blob/master/libusb/os/windows_usbdk.c): windows backend · Alternative Windows USB transport backend. · `libusb/os/windows_usbdk.c`
- [Windows Common](https://github.com/libusb/libusb/blob/master/libusb/os/windows_common.c): windows support · Shared Windows backend utilities and glue. · `libusb/os/windows_common.c`
- [Darwin USB](https://github.com/libusb/libusb/blob/master/libusb/os/darwin_usb.c): macOS backend · macOS and Darwin USB backend. · `libusb/os/darwin_usb.c`
- [WebUSB](https://github.com/libusb/libusb/blob/master/libusb/os/emscripten_webusb.cpp): wasm backend · Emscripten/WebUSB backend. · `libusb/os/emscripten_webusb.cpp`
- [Posix Events](https://github.com/libusb/libusb/blob/master/libusb/os/events_posix.c): event loop · POSIX event waiting and completion dispatch. · `libusb/os/events_posix.c`
- [Win Events](https://github.com/libusb/libusb/blob/master/libusb/os/events_windows.c): event loop · Windows event waiting and completion dispatch. · `libusb/os/events_windows.c`
- [Posix Threads](https://github.com/libusb/libusb/blob/master/libusb/os/threads_posix.c): threading · POSIX threading helpers used by the core. · `libusb/os/threads_posix.c`
- [Win Threads](https://github.com/libusb/libusb/blob/master/libusb/os/threads_windows.c): threading · Windows threading helpers used by the core. · `libusb/os/threads_windows.c`

### Support

Examples, tests, and build/packaging surfaces.

- **Examples**: sample apps · Standalone programs demonstrating API usage.
- **Tests**: regression suite · Unit, behavior, and fuzz regression coverage.
- [Build Matrix](https://github.com/libusb/libusb/blob/master/configure.ac): packaging · Autotools, MSVC, Xcode, Android, and CI packaging. · `configure.ac`

## Connections

- 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.
