Why CherryUSB Is the Tiny Yet Powerful USB Stack Every Embedded System Needs

Overview

CherryUSB is a small, highly portable, high‑performance USB host and device protocol stack for embedded systems that include a USB IP.

Design Goals

Easy to learn

Concise C code with simple syntax.

Hierarchical (tree‑structured) programming model.

Templated class and porting drivers.

Clear API categorisation (device: init, class registration, command callbacks, data transfer; host: init, class discovery, data transfer).

Easy to use

Data‑transfer APIs behave like UART TX/DMA and UART RX/DMA.

No length limits; packet‑splitting is handled inside the porting layer.

Easy to achieve performance

Porting driver connects directly to registers (no abstraction layer).

Zero‑copy memory handling.

DMA mode used when the IP provides hardware packet‑splitting.

Unlimited transfer length to fully exploit DMA.

Packet‑splitting performed in interrupts.

Directory Structure

class – USB class driver implementations for host and device.

common – USB spec definitions, common macros, standard interfaces.

core – Core implementation of the USB host/device stack.

demo – Sample applications for host and device classes.

docs – Documentation.

osal – OS abstraction layer.

platform – Porting for various OS families.

port – Porting interfaces required by the stack.

tools – Utility tools.

Device Stack Overview

The device stack defines a unified function framework for standard device requests, CLASS requests, VENDOR requests, and custom special requests. It uses object‑oriented and linked‑list structures so users can develop composite devices without handling low‑level logic. A standard DCD porting interface abstracts different USB IPs.

Supported features:

USB 2.0 full‑speed and high‑speed (USB 3.0 ultra‑high‑speed TODO).

Endpoint interrupt registration (user handles data in the porting layer).

Composite devices.

CDC ACM, CDC ECM.

HID.

Mass Storage Class (MSC).

USB Video Class (UVC 1.0, 1.5).

USB Audio Class (UAC 1.0, 2.0).

Device Firmware Upgrade (DFU).

USB MIDI.

Remote NDIS (RNDIS).

WINUSB 1.0/2.0, WEBUSB, BOS.

Vendor‑specific classes.

UF2.

Android Debug Bridge (shell only).

Multiple devices on the same USB IP.

Resource usage (GCC 10.2 ‑O2) for selected files:

file          FLASH (Byte)   No‑Cache RAM (Byte)   RAM (Byte)   Heap (Byte)
usbd_core.c   ~4400          512+320                0            0
usbd_cdc_acm.c~400           0                      0            0
usbd_msc.c    ~3800          128+512                16           0
usbd_hid.c    ~360           0                      0            0
usbd_audio.c  ~1500          0                      0            0
usbd_video.c  ~2600          0                      84           0
usbd_rndis.c  ~2100          2*1580+156+8           76           0

Host Stack Overview

The host stack standardises enumeration for devices attached to the root hub or external hubs, provides class‑specific interfaces for post‑enumeration handling, and defines a standard HCD porting interface for different USB IPs. An OS abstraction layer (OSAL) enables portability across operating systems.

Supported features:

USB 2.0 full‑speed and high‑speed (USB 3.0 TODO).

Automatic loading of supported class drivers.

Blocking and asynchronous transfers.

Composite devices.

Multi‑level hub support up to 7 levels (tested 1‑to‑10).

CDC ACM, CDC ECM.

HID.

MSC.

UVC 1.0/1.5.

UAC 1.0.

RNDIS.

USB Bluetooth (CLASS 0xE0 or custom).

Vendor‑specific classes (serial, net, wifi).

USB modeswitch.

Android Open Accessory.

Multiple hosts on the same USB IP.

An lsusb -like function is provided; with a shell plugin users can list all attached devices, including those behind external hubs.

Resource usage (GCC 10.2 ‑O2) for selected host files:

file               FLASH (Byte)   No‑Cache RAM (Byte)               RAM (Byte)                     Heap (Byte)
usbh_core.c        ~9000          512+8*(1+x)*n                     28                              raw_config_desc
usbh_hub.c         ~6000          32+4*(1+x)                        12+sizeof(struct usbh_hub)*(1+x) 0
usbh_cdc_acm.c     ~900           7                                 4+sizeof(struct usbh_cdc_acm)*x   0
usbh_msc.c         ~2700          64                                4+sizeof(struct usbh_msc)*x       0
usbh_hid.c         ~1400          256                               4+sizeof(struct usbh_hid)*x       0
usbh_video.c       ~3800          128                               4+sizeof(struct usbh_video)*x     0
usbh_audio.c       ~4100          128                               4+sizeof(struct usbh_audio)*x     0
usbh_rndis.c       ~4200          512+2*2048                        sizeof(struct usbh_rndis)        0
usbh_cdc_ecm.c      ~2200          2*1514+16                         sizeof(struct usbh_cdc_ecm)      0
usbh_cdc_ncm.c      ~3300          2*2048+16+32                      sizeof(struct usbh_cdc_ncm)      0
usbh_bluetooth.c   ~1000          2*2048                            sizeof(struct usbh_bluetooth)   0

USB IP Support Matrix

IP                Device   Host   Support
OHCI (intel)      none     OHCI   ✔
EHCI (intel)      none     EHCI   ✔
XHCI (intel)      none     XHCI   ✔
UHCI (intel)      none     UHCI   ✖
DWC2 (synopsys)   DWC2    DWC2   ✔
MUSB (mentor)     MUSB    MUSB   ✔
FOTG210 (faraday)FOTG210  EHCI   ✔
CHIPIDEA (synopsys)CHIPIDEA EHCI  ✔
CDNS2 (cadence)   CDNS2   CDNS2  ✔
CDNS3 (cadence)   CDNS3   XHCI   ✖
DWC3 (synopsys)  DWC3    XHCI   ✖

Documentation and Tutorials

Quick‑start guide, USB fundamentals, API manual, class concepts, and example code are available in the CherryUSB documentation tutorial.

Video tutorial (based on version 1.4.3):

https://www.bilibili.com/cheese/play/ss707687201

Example Repositories

Manufacturer   Chip/Series          USB IP                Repo URL          Support Version   Support Status
Bouffalolab   BL702/BL616/BL808    bouffalolab/ehci      bouffalo_sdk     <= latest         Long‑term
ST            STM32F1x            fsdev                stm32_repo       <= latest         Long‑term
ST            STM32F4/STM32H7     dwc2                 stm32_repo       <= latest         Long‑term
HPMicro       HPM6000/HPM5000     hpm/ehci             hpm_sdk          <= latest         Long‑term
Essemi        ES32F36xx           musb                 es32f369_repo    <= latest         Long‑term
Phytium       e2000               pusb2/xhci           phytium_repo     >=1.4.0           Long‑term
Espressif     esp32s2/esp32s3/esp32p4 dwc2              esp32_repo       <= latest         Long‑term
NXP           mcx                 kinetis/chipidea/ehci nxp_mcx_repo    <= latest         Long‑term
Kendryte      k230                dwc2                 k230_repo        v1.2.0            Long‑term
Raspberry Pi  rp2040/rp2350       rp2040               pico-examples    <= latest         Long‑term
WCH           CH32V307/ch58x      ch32_usbfs/ch32_usbhs/ch58x wch_repo   <= v0.10.2        TBD

Package Availability

CherryUSB packages can be obtained through RT‑Thread, YOC, and the ESP‑Registry.

Commercial Support

For commercial support, see

https://cherryusb.readthedocs.io/zh-cn/latest/support/index.html

.