README.md
1**English | [简体中文](README_zh.md)**
2
3<h1 align="center" style="margin: 30px 0 30px; font-weight: bold;">CherryUSB</h1>
4<p align="center">
5 <a href="https://github.com/cherry-embedded/CherryUSB/releases"><img src="https://img.shields.io/github/release/cherry-embedded/CherryUSB.svg"></a>
6 <a href="https://github.com/cherry-embedded/CherryUSB/blob/master/LICENSE"><img src="https://img.shields.io/github/license/cherry-embedded/CherryUSB.svg?style=flat-square"></a>
7 <a href="https://github.com/cherry-embedded/CherryUSB/actions/workflows/deploy-docs.yml"><img src="https://github.com/cherry-embedded/CherryUSB/actions/workflows/deploy-docs.yml/badge.svg"> </a>
8 <a href="https://discord.com/invite/wFfvrSAey8"><img src="https://img.shields.io/badge/Discord-blue?logo=discord&style=flat-square"> </a>
9</p>
10
11CherryUSB is a tiny and beautiful, high performance and portable USB host and device stack for embedded system with USB IP.
12
13
14
15## Why choose CherryUSB
16
17### Easy to study USB
18
19In order to make it easier for users to learn USB basics, enumeration, driver loading and IP drivers, the code has been written with the following advantages:
20
21- Lean code, simple logic, no complex C syntax
22- Tree-based programming with cascading code
23- Class-drivers and porting-drivers are templating and simplification
24- Clear API classification (slave: initialisation, registration api, command callback api, data sending and receiving api; host: initialisation, lookup api, data sending and receiving api)
25
26### Easy to use USB
27
28In order to facilitate the use of the USB interface and to take into account the fact that users have learned about uart and dma, the following advantages have been designed for the data sending and receiving class of interface:
29
30- Equivalent to using uart tx dma/uart rx dma
31- There is no limit to the length of send and receive, the user does not need to care about the USB packetization process (the porting driver does it)
32
33### Easy to bring out USB performance
34
35Taking into account USB performance issues and trying to achieve the theoretical bandwidth of the USB hardware, the design of the data transceiver class interface has the following advantages:
36
37- Porting drivers directly to registers, no abstraction layer encapsulation
38- Memory zero copy
39- If IP has DMA then uses DMA mode (DMA with hardware packetization)
40- Unlimited length make it easier to interface with hardware DMA and take advantage of DMA
41- Packetization is handled in interrupt
42
43## Directory Structure
44
45| Directory | Description |
46|:-------------:|:---------------------------:|
47|class | usb class driver |
48|common | usb spec macros and utils |
49|core | usb core implementation |
50|demo | usb device and host demo |
51|osal | os wrapper |
52|platform | class support for other os |
53|docs | doc for guiding |
54|port | usb dcd and hcd porting |
55|tools | tool url |
56
57## Device Stack Overview
58
59CherryUSB Device Stack provides a unified framework of functions for standard device requests, CLASS requests, VENDOR requests and custom special requests. The object-oriented and chained approach allows the user to quickly get started with composite devices without having to worry about the underlying logic. At the same time, a standard dcd porting interface has been standardised for adapting different USB IPs to achieve ip-oriented programming.
60
61CherryUSB Device Stack has the following functions:
62
63- Support USB2.0 full and high speed(USB3.0 super speed TODO)
64- Support endpoint irq callback register by users, let users do whatever they wants in endpoint irq callback.
65- Support Composite Device
66- Support Communication Device Class (CDC_ACM, CDC_ECM)
67- Support Human Interface Device (HID)
68- Support Mass Storage Class (MSC)
69- Support USB VIDEO CLASS (UVC1.0, UVC1.5)
70- Support USB AUDIO CLASS (UAC1.0, UAC2.0)
71- Support Device Firmware Upgrade CLASS (DFU)
72- Support USB MIDI CLASS (MIDI)
73- Support Remote NDIS (RNDIS)
74- Support Media Transfer Protocol (MTP)
75- Support WINUSB1.0, WINUSB2.0, WEBUSB, BOS
76- Support Vendor class
77- Support UF2
78- Support Android Debug Bridge (Only support shell)
79- Support multi device with the same USB IP
80
81CherryUSB Device Stack resource usage (GCC 10.2 with -O2, disable log):
82
83| file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) |
84|:-------------:|:--------------:|:-------------------------:|:-------------:|:----------------:|
85|usbd_core.c | ~4500 | (512(default) + 320) * bus | 0 | 0 |
86|usbd_cdc_acm.c | ~900 | 0 | 0 | 0 |
87|usbd_msc.c | ~5000 | (128 + 512(default)) * bus | 16 * bus | 0 |
88|usbd_hid.c | ~300 | 0 | 0 | 0 |
89|usbd_audio.c | ~4000 | 0 | 0 | 0 |
90|usbd_video.c | ~7000 | 0 | 132 * bus | 0 |
91|usbd_rndis.c | ~2500 | 2 * 1580(default)+156+8 | 80 | 0 |
92|usbd_cdc_ecm.c | ~900 | 2 * 1514(default)+16 | 42 | 0 |
93|usbd_mtp.c | ~9000 | 2048(default)+128 | sizeof(struct mtp_object) * n| 0 |
94
95## Host Stack Overview
96
97The CherryUSB Host Stack has a standard enumeration implementation for devices mounted on root hubs and external hubs, and a standard interface for different Classes to indicate what the Class driver needs to do after enumeration and after disconnection. A standard hcd porting interface has also been standardised for adapting different USB IPs for IP-oriented programming. Finally, the host stack is managed using os, and provides osal to make a adaptation for different os.
98
99CherryUSB Host Stack has the following functions:
100
101- Support low speed, full speed, high speed and super speed devices
102- Automatic loading of supported Class drivers
103- Support blocking transfers and asynchronous transfers
104- Support Composite Device
105- Multi-level HUB support, expandable up to 7 levels(Testing hub with 10 ports works well,only support dwc2/ehci/xhci/rp2040)
106- Support Communication Device Class (CDC_ACM, CDC_ECM)
107- Support Human Interface Device (HID)
108- Support Mass Storage Class (MSC)
109- Support USB Video CLASS (UVC1.0, UVC1.5)
110- Support USB Audio CLASS (UAC1.0)
111- Support Remote NDIS (RNDIS)
112- Support USB Bluetooth class (support nimble and zephyr bluetooth stack, support **CLASS:0xE0** or vendor class like cdc acm)
113- Support Vendor class (serial, net, wifi)
114- Support USB modeswitch
115- Support Android Open Accessory
116- Support multi host with the same USB IP
117
118The CherryUSB Host stack also provides the lsusb function, which allows you to view information about all mounted devices, including those on external hubs, with the help of a shell plugin.
119
120CherryUSB Host Stack resource usage (GCC 10.2 with -O2, disable log):
121
122| file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) |
123|:-------------:|:--------------:|:-------------------------------:|:---------------------------:|:------------:|
124|usbh_core.c | ~4500 | (512(default) + 8 * (1+x) *n) * bus | sizeof(struct usbh_hub) * bus | raw_config_desc |
125|usbh_hub.c | ~3500 | (32 + 4 * (1+x)) * bus | 12 + sizeof(struct usbh_hub) * x | 0 |
126|usbh_cdc_acm.c | ~600 | 7 * x | 4 + sizeof(struct usbh_cdc_acm) * x | 0 |
127|usbh_msc.c | ~2000 | 128 * x | 4 + sizeof(struct usbh_msc) * x | 0 |
128|usbh_hid.c | ~800 | 64 * x | 4 + sizeof(struct usbh_hid) * x | 0 |
129|usbh_video.c | ~5000 | 128 * x | 4 + sizeof(struct usbh_video) * x | 0 |
130|usbh_audio.c | ~4000 | 128 * x | 4 + sizeof(struct usbh_audio) * x | 0 |
131|usbh_rndis.c | ~3000 | 512 + 2 * 2048(default)| sizeof(struct usbh_rndis) * 1 | 0 |
132|usbh_cdc_ecm.c | ~1500 | 2 * 1514 + 16 | sizeof(struct usbh_cdc_ecm) * 1 | 0 |
133|usbh_cdc_ncm.c | ~2000 | 2 * 2048(default) + 16 + 32 | sizeof(struct usbh_cdc_ncm) * 1| 0 |
134|usbh_bluetooth.c | ~1000 | 2 * 2048(default) | sizeof(struct usbh_bluetooth) * 1 | 0 |
135|usbh_asix.c | ~7000 | 2 * 2048(default) + 16 + 32 | sizeof(struct usbh_asix) * 1 | 0 |
136|usbh_rtl8152.c | ~9000 | 16K+ 2K(default) + 2 + 32 | sizeof(struct usbh_rtl8152) * 1 | 0 |
137
138Among them, `sizeof(struct usbh_hub)` and `sizeof(struct usbh_hubport)` are affected by the following macros:
139
140```
141#define CONFIG_USBHOST_MAX_EXTHUBS 1
142#define CONFIG_USBHOST_MAX_EHPORTS 4
143#define CONFIG_USBHOST_MAX_INTERFACES 8
144#define CONFIG_USBHOST_MAX_INTF_ALTSETTINGS 8
145#define CONFIG_USBHOST_MAX_ENDPOINTS 4
146```
147
148x is affected by the following macros:
149
150```
151#define CONFIG_USBHOST_MAX_CDC_ACM_CLASS 4
152#define CONFIG_USBHOST_MAX_HID_CLASS 4
153#define CONFIG_USBHOST_MAX_MSC_CLASS 2
154#define CONFIG_USBHOST_MAX_AUDIO_CLASS 1
155#define CONFIG_USBHOST_MAX_VIDEO_CLASS 1
156```
157
158## USB IP Support
159
160Only standard and commercial USB IP are listed.
161
162| IP | device | host | Support status |
163|:----------------:|:----------:|:--------:|:--------------:|
164| OHCI(intel) | none | OHCI | √ |
165| EHCI(intel) | none | EHCI | √ |
166| XHCI(intel) | none | XHCI | √ |
167| UHCI(intel) | none | UHCI | × |
168| DWC2(synopsys) | DWC2 | DWC2 | √ |
169| MUSB(mentor) | MUSB | MUSB | √ |
170| FOTG210(faraday)| FOTG210 | EHCI | √ |
171| CHIPIDEA(synopsys)| CHIPIDEA | EHCI | √ |
172| CDNS2(cadence) | CDNS2 | CDNS2 | √ |
173| CDNS3(cadence) | CDNS3 | XHCI | × |
174| DWC3(synopsys) | DWC3 | XHCI | × |
175
176## Documentation Tutorial
177
178Quickly start, USB basic concepts, API manual, Class basic concepts and examples, see [CherryUSB Documentation Tutorial](https://cherryusb.readthedocs.io/).
179
180## Video Tutorial
181
182CherryUSB Cheese (based V1.4.3): https://www.bilibili.com/cheese/play/ss707687201 .
183
184## Descriptor Generator Tool
185
186TODO
187
188## Demo Repo
189
190| Manufacturer | CHIP or Series | USB IP| Repo Url | Support version | Support status |
191|:--------------------:|:------------------:|:-----:|:--------:|:------------------:|:-------------:|
192|Bouffalolab | BL702/BL616/BL808 | bouffalolab/ehci|[bouffalo_sdk](https://github.com/CherryUSB/bouffalo_sdk)|<= latest | Long-term |
193|ST | STM32F1x/STM32F4/STM32H7 | fsdev/dwc2 |[stm32_repo](https://github.com/CherryUSB/cherryusb_stm32)|<= latest | Long-term |
194|HPMicro | HPM6000/HPM5000 | hpm/ehci |[hpm_sdk](https://github.com/CherryUSB/hpm_sdk)|<= latest | Long-term |
195|Essemi | ES32F36xx | musb |[es32f369_repo](https://github.com/CherryUSB/cherryusb_es32)|<= latest | Long-term |
196|Phytium | e2000 | pusb2/xhci |[phytium_repo](https://gitee.com/phytium_embedded/phytium-free-rtos-sdk)|>=1.4.0 | Long-term |
197|Artinchip | d12x/d13x/d21x | aic/ehci/ohci |[luban-lite](https://gitee.com/artinchip/luban-lite)|<= latest | Long-term |
198|Espressif | esp32s2/esp32s3/esp32p4 | dwc2 |[esp32_repo](https://github.com/CherryUSB/cherryusb_esp32)|<= latest | Long-term |
199|NXP | mcx | kinetis/chipidea/ehci |[nxp_mcx_repo](https://github.com/CherryUSB/cherryusb_mcx)|<= latest | Long-term |
200|Kendryte | k230 | dwc2 |[k230_repo](https://github.com/CherryUSB/k230_sdk)|v1.2.0 | Long-term |
201|Actionstech | ATS30xx | dwc2 |[action_zephyr_repo](https://github.com/CherryUSB/lv_port_actions_technology/tree/master/action_technology_sdk)|>=1.4.0 | Long-term |
202|Nationstech | n32h4x | dwc2 |[nation_repo](https://github.com/CherryUSB/cherryusb_nation)|>=1.5.0 | Long-term |
203|Raspberry pi | rp2040/rp2350 | rp2040 |[pico-examples](https://github.com/CherryUSB/pico-examples)|<= latest | Long-term |
204|AllwinnerTech | F1C100S/F1C200S | musb |[cherryusb_rtt_f1c100s](https://github.com/CherryUSB/cherryusb_rtt_f1c100s)|<= latest | the same with musb |
205|Bekencorp | bk7256/bk7258 | musb |[bk_idk](https://github.com/CherryUSB/bk_idk)| v0.7.0 | the same with musb |
206|Sophgo | cv18xx | dwc2 |[cvi_alios_open](https://github.com/CherryUSB/cvi_alios_open)| v0.7.0 | TBD |
207|WCH | CH32V307/ch58x | ch32_usbfs/ch32_usbhs/ch58x |[wch_repo](https://github.com/CherryUSB/cherryusb_wch)|<= v0.10.2/>=v1.5.0 | TBD |
208
209## Package Support
210
211CherryUSB package is available as follows:
212
213- [RT-Thread](https://packages.rt-thread.org/detail.html?package=CherryUSB)
214- [YOC](https://www.xrvm.cn/document?temp=usb-host-protocol-stack-device-driver-adaptation-instructions&slug=yocbook)
215- [ESP-Registry](https://components.espressif.com/components/cherry-embedded/cherryusb)
216
217## Commercial Support
218
219Refer to https://cherryusb.readthedocs.io/zh-cn/latest/support/index.html.
220
221## Contact
222
223CherryUSB discord: https://discord.com/invite/wFfvrSAey8.
224
225## Company Support
226
227Thanks to the following companies for their support (in no particular order):
228
229<img src="docs/assets/bouffalolab.jpg" width="100" height="80"/> <img src="docs/assets/hpmicro.jpg" width="100" height="80" /> <img src="docs/assets/eastsoft.jpg" width="100" height="80" /> <img src="docs/assets/rtthread.jpg" width="100" height="80" /> <img src="docs/assets/sophgo.jpg" width="100" height="80" /> <img src="docs/assets/phytium.jpg" width="100" height="80" /> <img src="docs/assets/thead.jpg" width="100" height="80" /> <img src="docs/assets/nuvoton.jpg" width="100" height="80" /> <img src="docs/assets/artinchip.jpg" width="100" height="80" /> <img src="docs/assets/bekencorp.jpg" width="100" height="80" /> <img src="docs/assets/nxp.png" width="100" height="80" /> <img src="docs/assets/espressif.png" width="100" height="80" /> <img src="docs/assets/canaan.jpg" width="100" height="80" />
230<img src="docs/assets/actions.jpg" width="100" height="80" /> <img src="docs/assets/nationstech.jpg" width="100" height="80" />
231
