How cherry-embedded/cherryusb works
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)