# hathach/tinyusb architecture

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

- Interactive diagram: https://gitdiagram.com/hathach/tinyusb
- Repository: https://github.com/hathach/tinyusb

## Overview

#### 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: [`src/tusb.c`](https://github.com/hathach/tinyusb/blob/master/src/tusb.c) (Stack init & task dispatch), [`examples/CMakeLists.txt`](https://github.com/hathach/tinyusb/blob/master/examples/CMakeLists.txt) (Examples build entry), [`src/portable/synopsys/dwc2/dcd_dwc2.c`](https://github.com/hathach/tinyusb/blob/master/src/portable/synopsys/dwc2/dcd_dwc2.c) (Portable controller drivers), [`src/tusb.h`](https://github.com/hathach/tinyusb/blob/master/src/tusb.h) (Public TinyUSB API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Integration &amp; Builds"]
  node_application["Application integration<br/>application boundary"]
  node_descriptors["Composite descriptors<br/>device example<br/>[usb_descriptors.c]"]
  node_examples["Examples build entry<br/>CMake entry<br/>[CMakeLists.txt]"]
end

subgraph group_core["Common Runtime"]
  node_public_api["Public TinyUSB API<br/>public header<br/>[tusb.h]"]
  node_options["Role / MCU / OS selection<br/>compile-time options<br/>[tusb_option.h]"]
  node_stack_runtime["Stack init &amp; task dispatch<br/>common runtime<br/>[tusb.c]"]
  node_common_primitives["FIFO and core types<br/>common primitives<br/>[tusb_fifo.c]"]
  node_osal["OSAL<br/>OS abstraction<br/>[osal.h]"]
end

subgraph group_device["Device Stack"]
  node_dcd_contract["Device controller contract<br/>DCD interface<br/>[dcd.h]"]
  node_device_core["Device state machine<br/>USBD core<br/>[usbd.c]"]
  node_device_classes["Device class modules<br/>class drivers<br/>[cdc_device.c]"]
end

subgraph group_host["Host Stack"]
  node_hcd_contract["Host controller contract<br/>HCD interface<br/>[hcd.h]"]
  node_host_core["Host enumeration core<br/>USBH core<br/>[usbh.c]"]
  node_hub["Hub topology manager<br/>hub support<br/>[hub.c]"]
  node_host_classes["Host class modules<br/>class drivers<br/>[msc_host.c]"]
end

subgraph group_portability["Hardware Portability"]
  node_controller_drivers["Portable controller drivers<br/>DCD/HCD implementations<br/>[dcd_dwc2.c]"]
  node_bsp_metadata["BSP family metadata<br/>target catalog<br/>[family.json]"]
end

subgraph group_validation["Validation"]
  node_ci["CI build matrix<br/>GitHub Actions<br/>[build.yml]"]
  node_hil_tests["Hardware-in-the-loop tests<br/>Python validation<br/>[hil_test.py]"]
end

node_application -->|"integrates through"| node_public_api
node_application -->|"provides"| node_descriptors
node_examples -->|"builds runnable apps"| node_application
node_public_api -->|"uses selection"| node_options
node_public_api -->|"exposes"| node_stack_runtime
node_options -->|"selects OS backend"| node_osal
node_stack_runtime -->|"uses"| node_common_primitives
node_stack_runtime -->|"dispatches via"| node_osal
node_stack_runtime -->|"runs device task"| node_device_core
node_stack_runtime -->|"runs host task"| node_host_core
node_controller_drivers -->|"implements"| node_dcd_contract
node_controller_drivers -->|"implements"| node_hcd_contract
node_controller_drivers -->|"defers ISR events"| node_osal
node_dcd_contract -->|"controller events"| node_device_core
node_device_core -->|"routes endpoints and dispatches"| node_device_classes
node_descriptors -->|"selects classes"| node_device_classes
node_hcd_contract -->|"controller events"| node_host_core
node_host_core -->|"manages topology"| node_hub
node_hub -->|"enables interface claims"| node_host_classes
node_bsp_metadata -->|"selects supported targets"| node_examples
node_ci -->|"builds"| node_examples
node_hil_tests -->|"flashes and tests"| node_examples

click node_descriptors "https://github.com/hathach/tinyusb/blob/master/examples/device/cdc_msc/src/usb_descriptors.c"
click node_examples "https://github.com/hathach/tinyusb/blob/master/examples/CMakeLists.txt"
click node_public_api "https://github.com/hathach/tinyusb/blob/master/src/tusb.h"
click node_options "https://github.com/hathach/tinyusb/blob/master/src/tusb_option.h"
click node_stack_runtime "https://github.com/hathach/tinyusb/blob/master/src/tusb.c"
click node_common_primitives "https://github.com/hathach/tinyusb/blob/master/src/common/tusb_fifo.c"
click node_osal "https://github.com/hathach/tinyusb/blob/master/src/osal/osal.h"
click node_dcd_contract "https://github.com/hathach/tinyusb/blob/master/src/device/dcd.h"
click node_device_core "https://github.com/hathach/tinyusb/blob/master/src/device/usbd.c"
click node_device_classes "https://github.com/hathach/tinyusb/blob/master/src/class/cdc/cdc_device.c"
click node_hcd_contract "https://github.com/hathach/tinyusb/blob/master/src/host/hcd.h"
click node_host_core "https://github.com/hathach/tinyusb/blob/master/src/host/usbh.c"
click node_hub "https://github.com/hathach/tinyusb/blob/master/src/host/hub.c"
click node_host_classes "https://github.com/hathach/tinyusb/blob/master/src/class/msc/msc_host.c"
click node_controller_drivers "https://github.com/hathach/tinyusb/blob/master/src/portable/synopsys/dwc2/dcd_dwc2.c"
click node_bsp_metadata "https://github.com/hathach/tinyusb/blob/master/hw/bsp/family.json"
click node_ci "https://github.com/hathach/tinyusb/blob/master/.github/workflows/build.yml"
click node_hil_tests "https://github.com/hathach/tinyusb/blob/master/test/hil/hil_test.py"

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_application,node_descriptors,node_examples toneBlue
class node_public_api,node_options,node_stack_runtime,node_common_primitives,node_osal toneAmber
class node_dcd_contract,node_device_core,node_device_classes toneMint
class node_hcd_contract,node_host_core,node_hub,node_host_classes toneRose
class node_controller_drivers,node_bsp_metadata toneIndigo
class node_ci,node_hil_tests toneTeal
```

## Components

### Integration & Builds

- **Application integration**: application boundary · Provides configuration, descriptors, callbacks, and task polling.
- [Composite descriptors](https://github.com/hathach/tinyusb/blob/master/examples/device/cdc_msc/src/usb_descriptors.c): device example · `examples/device/cdc_msc/src/usb_descriptors.c`
- [Examples build entry](https://github.com/hathach/tinyusb/blob/master/examples/CMakeLists.txt): CMake entry · Builds device, host, dual-role, and Type-C applications. · `examples/CMakeLists.txt`

### Common Runtime

- [Public TinyUSB API](https://github.com/hathach/tinyusb/blob/master/src/tusb.h): public header · `src/tusb.h`
- [Role / MCU / OS selection](https://github.com/hathach/tinyusb/blob/master/src/tusb_option.h): compile-time options · `src/tusb_option.h`
- [Stack init & task dispatch](https://github.com/hathach/tinyusb/blob/master/src/tusb.c): common runtime · Roots common initialization and role task APIs. · `src/tusb.c`
- [FIFO and core types](https://github.com/hathach/tinyusb/blob/master/src/common/tusb_fifo.c): common primitives · `src/common/tusb_fifo.c`
- [OSAL](https://github.com/hathach/tinyusb/blob/master/src/osal/osal.h): OS abstraction · Selects bare-metal or RTOS synchronization and queues. · `src/osal/osal.h`

### Device Stack

- [Device controller contract](https://github.com/hathach/tinyusb/blob/master/src/device/dcd.h): DCD interface · `src/device/dcd.h`
- [Device state machine](https://github.com/hathach/tinyusb/blob/master/src/device/usbd.c): USBD core · Owns control transfers, configuration, endpoint routing, and class dispatch. · `src/device/usbd.c`
- [Device class modules](https://github.com/hathach/tinyusb/blob/master/src/class/cdc/cdc_device.c): class drivers · Expose descriptor and callback-facing transfer behavior. · `src/class/cdc/cdc_device.c`

### Host Stack

- [Host controller contract](https://github.com/hathach/tinyusb/blob/master/src/host/hcd.h): HCD interface · `src/host/hcd.h`
- [Host enumeration core](https://github.com/hathach/tinyusb/blob/master/src/host/usbh.c): USBH core · `src/host/usbh.c`
- [Hub topology manager](https://github.com/hathach/tinyusb/blob/master/src/host/hub.c): hub support · Discovers downstream topology before interface claims. · `src/host/hub.c`
- [Host class modules](https://github.com/hathach/tinyusb/blob/master/src/class/msc/msc_host.c): class drivers · Match interfaces during enumeration and run class transfers. · `src/class/msc/msc_host.c`

### Hardware Portability

- [Portable controller drivers](https://github.com/hathach/tinyusb/blob/master/src/portable/synopsys/dwc2/dcd_dwc2.c): DCD/HCD implementations · Isolate controller registers, DMA, and interrupt mechanics. · `src/portable/synopsys/dwc2/dcd_dwc2.c`
- [BSP family metadata](https://github.com/hathach/tinyusb/blob/master/hw/bsp/family.json): target catalog · Drives board-family and supported-target selection. · `hw/bsp/family.json`

### Validation

- [CI build matrix](https://github.com/hathach/tinyusb/blob/master/.github/workflows/build.yml): GitHub Actions · `.github/workflows/build.yml`
- [Hardware-in-the-loop tests](https://github.com/hathach/tinyusb/blob/master/test/hil/hil_test.py): Python validation · Flashes boards and runs USB tests. · `test/hil/hil_test.py`

## Connections

- 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
