# cherry-embedded/cherryusb architecture

> Architecture diagram of the GitHub repository cherry-embedded/cherryusb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cherry-embedded/cherryusb
- Repository: https://github.com/cherry-embedded/cherryusb

## Overview

##### Main Components
- Core Stacks
- usbd_core (device)
- usbh_core (host)
- usbotg_core (OTG)
- Class Drivers (“class/”)
- Device classes (CDC, HID, MSC, Audio, Video, DFU, AOA, Vendor, etc.)
- Host classes (CDC_ACM, CDC_ECM, CDC_NCM, HID, MSC, RNDIS, Bluetooth, etc.)
- Common Utilities (“common/”)
- USB definitions, macros, linked lists, logging, memory copy, error codes
- Porting Layer (“port/”)
- DCD (Device Controller Drivers) & HCD (Host Controller Drivers) for each USB IP (DWC2, EHCI, OHCI, XHCI, MUSB, chipidea, RP2040, template, etc.)
- OS Abstraction (“osal/”)
- Wrappers for FreeRTOS, Zephyr, RT-Thread, ThreadX, µC/OS-III, etc.
- Platform Integrations (“platform/”)
- Adaptations for specific boards, file-systems (FatFs), graphics libraries (LVGL), network stacks (lwIP), UF2, DAPLink, Blackmagic, QMK, etc.
- Demos & Tools (“demo/”, “tools/”)
- Example applications illustrating usage of device/host APIs
- Utilities such as descriptor configurator, UF2 converter, packet capture helper
- Third-Party Libraries (“third_party/”)
- FreeRTOS, FatFs, lwIP, NimBLE, Zephyr Bluetooth, CherryMP (memory pool), CherryRB (ring buffer), DHCP/DNS servers, etc.
- Documentation & CI (“docs/”, “.github/”, CMakeLists, SConscript)
- ReadTheDocs source, API docs, build scripts, formatting configs

##### Relationships & Data Flows
a. Layered Flow (vertical)
- Application (demo, user code)
→ calls
- CherryUSB API
→ which dispatches to either host or device Core
→ Core uses Class-driver callbacks
→ Core & Classes invoke OSAL for synchronization, memory, timers
→ Core calls Porting Layer to drive hardware registers
→ Porting Layer programs USB IP hardware
- Hardware interrupts from USB IP
→ Porting Layer ISR
→ OSAL pushes into Core/Classes
- Platform modules sit alongside Porting & OSAL to glue on-chip peripherals (FatFs, lwIP).
b. Plugin Pattern
- Class drivers register with Core via function-pointer chains
- Port drivers implement a standard “dcd” or “hcd” interface to Core
- OSAL implements a fixed RTOS interface for threading, mutex, delay.

##### Architectural Patterns
- Layered Architecture (API → Core → Class → Port → Hardware)
- Inversion-of-Control/Plugin (registration of class drivers and port drivers)
- OS Abstraction (single osal interface, multiple backend implementations)
- Cross-compilation Build (CMake, SCons, cherrysb.cmake)
- Documentation‐driven (source/docs mirror code modules)

##### Technologies & Frameworks
- Language: C (ANSI/C99)
- Build: CMake, SCons
- RTOS: FreeRTOS, Zephyr, RT-Thread, ThreadX, µC/OS-III, NuttX, etc.
- USB IPs: DWC2, EHCI, OHCI, XHCI, MUSB, Chipidea, RP2040, etc.
- Third-party libs: FatFs, lwIP, NimBLE, etc.

##### Essential Details to Capture
- Dual-stack separation: Host stack vs. Device stack vs. OTG
- Class-driver registry chain under Core
- Standard port-driver interface (dcd/hcd) to USB hardware
- OSAL hooking into interrupts, threads, timers
- Platform examples (FatFs, lwIP) as optional layers
- Third-party blocks feeding into OSAL or directly into Core (e.g., FreeRTOS scheduling)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Application Layer
    Demos["Demos & Tools"]:::grey
    Docs["Documentation & CI"]:::grey

    %% API Layer
    API["CherryUSB API"]:::library

    %% Core & Class Layer
    subgraph "Core Stacks"
        direction TB
        usbd_core["usbd_core"]:::library
        usbh_core["usbh_core"]:::library
        usbotg_core["usbotg_core"]:::library
    end
    Class["Class Drivers"]:::library

    Common["Common Utilities"]:::library

    %% Abstraction Layer
    OSAL["OS Abstraction Layer"]:::abstraction
    Port["Porting Layer"]:::abstraction
    Platform["Platform Integrations"]:::abstraction

    %% External Layer
    TP["Third-Party Libraries"]:::external

    %% Hardware
    Hardware["USB Hardware IP"]:::external

    %% Connections
    Demos -->|"calls"| API
    API -->|"dispatch"| usbd_core
    API -->|"dispatch"| usbh_core
    API -->|"dispatch"| usbotg_core

    usbd_core -->|"register_class() / callbacks"| Class
    usbh_core -->|"register_class() / callbacks"| Class

    usbd_core -->|"osal_mutex_lock() etc."| OSAL
    usbh_core -->|"osal_mutex_lock() etc."| OSAL
    Class -->|"osal_apis"| OSAL

    usbd_core -->|"dcd_init() / dcd_[ops]"| Port
    usbh_core -->|"hcd_init() / hcd_submit_urb()"| Port

    Port -->|"drives registers"| Hardware
    Hardware -->|"ISR / IRQ"| OSAL
    OSAL -->|"signal to"| usbd_core
    OSAL -->|"signal to"| usbh_core

    Platform -->|"optional glue"| OSAL
    Platform -->|"optional glue"| Port

    TP -->|"RTOS scheduling etc."| OSAL
    TP -->|"protocol libs"| Class

    %% Click Events
    click Demos "https://github.com/cherry-embedded/cherryusb/blob/master/demo/cdc_acm_template.c"
    click Docs "https://github.com/cherry-embedded/cherryusb/tree/master/docs/source/api"
    click usbd_core "https://github.com/cherry-embedded/cherryusb/blob/master/core/usbd_core.c"
    click usbh_core "https://github.com/cherry-embedded/cherryusb/blob/master/core/usbh_core.c"
    click usbotg_core "https://github.com/cherry-embedded/cherryusb/blob/master/core/usbotg_core.c"
    click Class "https://github.com/cherry-embedded/cherryusb/blob/master/class/cdc/usbd_cdc_acm.c"
    click Common "https://github.com/cherry-embedded/cherryusb/blob/master/common/usb_def.h"
    click OSAL "https://github.com/cherry-embedded/cherryusb/blob/master/osal/usb_osal_freertos.c"
    click Port "https://github.com/cherry-embedded/cherryusb/blob/master/port/dwc2/usb_dc_dwc2.c"
    click Platform "https://github.com/cherry-embedded/cherryusb/blob/master/platform/fatfs/usbd_fatfs_mtp.c"
    click TP "https://github.com/cherry-embedded/cherryusb/tree/master/third_party/FreeRTOS-10.4/"

    %% Styles
    classDef library fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef abstraction fill:#ccccff,stroke:#333,stroke-width:1px
    classDef external fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef grey fill:#eeeeee,stroke:#333,stroke-width:1px
```
