How hathach/tinyusb works
Purpose and entry points
TinyUSB is a C USB host/device stack for embedded targets, with optional early-stage USB Type-C/PD support. Public integration starts at src/tusb.h; compile-time role/MCU/OS selection is in src/tusb_option.h, and common stack initialization/task dispatch is rooted in src/tusb.c. Applications provide descriptors, configuration, callbacks, and repeatedly execute the relevant non-ISR task APIs.
Core stack and concurrency
The common layer supplies types, compile-time utilities, FIFOs, and internal contracts. src/osal/osal.h selects a bare-metal or RTOS synchronization/queue implementation; drivers defer interrupt work into stack task context rather than executing protocol/class logic in ISRs. This creates the primary safety boundary: hardware ISR → controller driver event/queue → device or host task.
Paths: src/common/tusb_fifo.c, src/common/tusb_types.h, src/osal/osal.h.
Device pipeline
The device controller abstraction (dcd.h) feeds usbd.c, which owns USB device state, control transfers, configuration, endpoint routing, and class-driver dispatch. Device class implementations expose descriptors/callback-facing APIs and transfer behavior; applications can extend dispatch using the documented custom-driver callback.
Paths: src/device/dcd.h, src/device/usbd.c, src/class/cdc/cdc_device.c.
Host pipeline
The host controller abstraction (hcd.h) feeds usbh.c; hub support manages downstream topology before class drivers claim interfaces. Host class modules then implement enumeration-time matching and class transfers for CDC, HID, MSC, MIDI, and audio. This is separate from the device state machine but shares OSAL and controller-port patterns.
Paths: src/host/hcd.h, src/host/usbh.c, src/host/hub.c.
USB classes and application boundary
src/class/ contains protocol-specific host/device modules: audio, CDC/vendor serial, DFU, HID, MIDI/MIDI2, MSC, MTP, networking, printer, USBTMC, video, and Bluetooth HCI. Application-facing configuration and descriptors decide which classes compile and are registered; composite device examples demonstrate this boundary.
Paths: src/class/audio/audio_device.c, src/class/msc/msc_host.c, examples/device/cdc_msc/src/usb_descriptors.c.
Hardware portability and board integration
Portable controller drivers implement DCD/HCD contracts for controller IP blocks and MCU variants; they isolate register/DMA/interrupt mechanics from core protocol code. BSP families provide startup, clocks, pin/board APIs, link/build settings, and board identities. Family metadata drives supported-target selection across CMake/Make flows.
Paths: src/portable/synopsys/dwc2/dcd_dwc2.c, src/portable/raspberrypi/rp2040/hcd_rp2040.c, hw/bsp/family.json.
Builds, runtimes, and validation
Examples are the main runnable entry points, grouped as device, host, dual-role, and Type-C applications, with CMake and Make integration. Supported runtimes include no OS, FreeRTOS, RT-Thread, Mynewt, plus OSAL headers for Pico, Zephyr, ThreadX, and RTX4. CI uses GitHub Actions/CircleCI; validation combines native unit tests, fuzzing/OSS-Fuzz, and Python-driven hardware-in-the-loop flashing and USB tests.
Paths: examples/CMakeLists.txt, test/hil/hil_test.py, .github/workflows/build.yml.
Main entry points: tusb.c Stack init & task dispatch · CMakeLists.txt Examples build entry · dcd_dwc2.c Portable controller drivers · tusb.h Public TinyUSB API
Components 19
Integration & Builds
- Application integration · Provides configuration, descriptors, callbacks, and task polling.
- Composite descriptors
examples/device/cdc_msc/src/usb_descriptors.c - Examples build entry · Builds device, host, dual-role, and Type-C applications.
examples/CMakeLists.txt
Common Runtime
- Public TinyUSB API
src/tusb.h - Role / MCU / OS selection
src/tusb_option.h - Stack init & task dispatch · Roots common initialization and role task APIs.
src/tusb.c - FIFO and core types
src/common/tusb_fifo.c - OSAL · Selects bare-metal or RTOS synchronization and queues.
src/osal/osal.h
Device Stack
- Device controller contract
src/device/dcd.h - Device state machine · Owns control transfers, configuration, endpoint routing, and class dispatch.
src/device/usbd.c - Device class modules · Expose descriptor and callback-facing transfer behavior.
src/class/cdc/cdc_device.c
Host Stack
- Host controller contract
src/host/hcd.h - Host enumeration core
src/host/usbh.c - Hub topology manager · Discovers downstream topology before interface claims.
src/host/hub.c - Host class modules · Match interfaces during enumeration and run class transfers.
src/class/msc/msc_host.c
Hardware Portability
- Portable controller drivers · Isolate controller registers, DMA, and interrupt mechanics.
src/portable/synopsys/dwc2/dcd_dwc2.c - BSP family metadata · Drives board-family and supported-target selection.
hw/bsp/family.json
Validation
- CI build matrix
.github/workflows/build.yml - Hardware-in-the-loop tests · Flashes boards and runs USB tests.
test/hil/hil_test.py
Connections 22
- Application integration → Public TinyUSB API: integrates through
- Application integration → Composite descriptors: provides
- Examples build entry → Application integration: builds runnable apps
- Public TinyUSB API → Role / MCU / OS selection: uses selection
- Public TinyUSB API → Stack init & task dispatch: exposes
- Role / MCU / OS selection → OSAL: selects OS backend
- Stack init & task dispatch → FIFO and core types: uses
- Stack init & task dispatch → OSAL: dispatches via
- Stack init & task dispatch → Device state machine: runs device task
- Stack init & task dispatch → Host enumeration core: runs host task
- Portable controller drivers → Device controller contract: implements
- Portable controller drivers → Host controller contract: implements
- Portable controller drivers → OSAL: defers ISR events · Interrupt work is queued into stack task context.
- Device controller contract → Device state machine: controller events
- Device state machine → Device class modules: routes endpoints and dispatches
- Composite descriptors → Device class modules: selects classes
- Host controller contract → Host enumeration core: controller events
- Host enumeration core → Hub topology manager: manages topology
- Hub topology manager → Host class modules: enables interface claims
- BSP family metadata → Examples build entry: selects supported targets
- CI build matrix → Examples build entry: builds
- Hardware-in-the-loop tests → Examples build entry: flashes and tests