|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | - | - |
| class/ | | 12-May-2024 | - | 17,127 | 13,536 |
| common/ | | 12-May-2024 | - | 2,175 | 1,345 |
| core/ | | 12-May-2024 | - | 2,399 | 1,818 |
| demo/ | | 12-May-2024 | - | 86,151 | 84,662 |
| osal/ | | 12-May-2024 | - | 416 | 314 |
| port/ | | 12-May-2024 | - | 2,263 | 1,735 |
| tools/ | | 12-May-2024 | - | 2 | 2 |
| CMakeLists.txt | D | 12-May-2024 | 1.9 KiB | 61 | 53 |
| LICENSE | D | 12-May-2024 | 11.1 KiB | 202 | 169 |
| README.md | D | 12-May-2024 | 9.9 KiB | 183 | 138 |
| README_zh.md | D | 12-May-2024 | 9.3 KiB | 181 | 137 |
| cherryusb_config_template.h | D | 12-May-2024 | 3.9 KiB | 152 | 77 |
README.md
1# CherryUSB
2
3[中文版](./README_zh.md)
4
5CherryUSB is a tiny, beautiful and portable USB host and device stack for embedded system with USB IP.
6
7
8
9## Why choose
10
11### Easy to study USB
12
13In 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:
14
15- Lean code, simple logic, no complex C syntax
16- Tree-based programming with cascading code
17- Class-drivers and porting-drivers are templating and simplification
18- Clear API classification (slave: initialisation, registration api, command callback api, data sending and receiving api; host: initialisation, lookup api, data sending and receiving api)
19
20### Easy to use USB
21
22In 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:
23
24- Equivalent to using uart tx dma/uart rx dma
25- 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 the packetization process)
26
27### Easy to bring out USB performance
28
29Taking 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:
30
31- Porting drivers directly to registers, no abstraction layer encapsulation
32- Memory zero copy
33- If IP has DMA then uses DMA mode (DMA with hardware packetization)
34- Unlimited length make it easier to interface with hardware DMA and take advantage of DMA
35- Subcontracting function is handled in interrupt
36
37## Directoy Structure
38
39```
40.
41├── class
42├── common
43├── core
44├── demo
45├── docs
46├── osal
47├── packet capture
48└── port
49└── tools
50
51```
52
53| Directory | Description |
54|:-------------:|:---------------------------:|
55|class | usb class driver |
56|common | usb spec macros and utils |
57|core | usb core implementation |
58|demo | different chips demo |
59|osal | os wrapper |
60|docs | doc for guiding |
61|port | usb dcd and hcd porting |
62|tools | tool url |
63
64## Device Stack Overview
65
66CherryUSB 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.
67
68CherryUSB Device Stack has the following functions：
69
70- Support USB2.0 full and high speed, USB3.0 super speed
71- Support endpoint irq callback register by users, let users do whatever they wants in endpoint irq callback.
72- Support Composite Device
73- Support Communication Device Class (CDC)
74- Support Human Interface Device (HID)
75- Support Mass Storage Class (MSC)
76- Support USB VIDEO CLASS (UVC1.0、UVC1.5)
77- Support USB AUDIO CLASS (UAC1.0、UAC2.0)
78- Support Device Firmware Upgrade CLASS (DFU)
79- Support USB MIDI CLASS (MIDI)
80- Support Remote NDIS (RNDIS)
81- Support WINUSB1.0、WINUSB2.0(with BOS)
82- Support Vendor class
83
84CherryUSB Device Stack resource usage (GCC 10.2 with -O2):
85
86| file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) |
87|:-------------:|:--------------:|:-------------------------:|:-------------:|:----------------:|
88|usbd_core.c | 3516 | 256(default) + 320 | 0 | 0 |
89|usbd_cdc.c | 392 | 0 | 0 | 0 |
90|usbd_msc.c | 2839 | 128 + 512(default) | 16 | 0 |
91|usbd_hid.c | 364 | 0 | 0 | 0 |
92|usbd_audio.c | 1455 | 0 | 0 | 0 |
93|usbd_video.c | 2494 | 0 | 84 | 0 |
94|usbd_rndis.c | 2109 | 3340 | 76 | 0 |
95
96## Host Stack Overview
97
98The CherryUSB Host Stack has a standard enumeration implementation for devices mounted on roothubs 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.
99
100CherryUSB Host Stack has the following functions：
101
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
106- Support Communication Device Class (CDC)
107- Support Human Interface Device (HID)
108- Support Mass Storage Class (MSC)
109- Support USB Video CLASS
110- Support USB Audio CLASS
111- Support Remote NDIS (RNDIS)
112- Support Vendor class
113
114The 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.
115
116CherryUSB Host Stack resource usage (GCC 10.2 with -O2):
117
118| file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) |
119|:-------------:|:--------------:|:-------------------------------:|:---------------------------:|:-------------------------------:|
120|usbh_core.c | 4237 | 512 + 8 * (1+x) *n | 28 | sizeof(struct usbh_urb) |
121|usbh_hub.c | 2919 | 32 + 4* (1+x) | 12 + sizeof(struct usbh_hub) * (1+x) | 0 |
122|usbh_cdc_acm.c | 1099 | 7 | 4 + sizeof(struct usbh_cdc_acm) * x | 0 |
123|usbh_msc.c | 2502 | 32 | 4 + sizeof(struct usbh_msc) * x | 0 |
124|usbh_hid.c | 956 | 128 | 4 + sizeof(struct usbh_hid) * x | 0 |
125|usbh_video.c | 2330 | 128 | 4 + sizeof(struct usbh_video) * x | 0 |
126|usbh_audio.c | 3168 | 128 | 4 + sizeof(struct usbh_audio) * x | 0 |
127|usbh_rndis.c | 3030 | 4096 | 4 + sizeof(struct usbh_rndis) * x | 0 |
128
129Among them, `sizeof(struct usbh_hub)` and `sizeof(struct usbh_hubport)` are affected by the following macros：
130
131```
132#define CONFIG_USBHOST_MAX_EXTHUBS 1
133#define CONFIG_USBHOST_MAX_EHPORTS 4
134#define CONFIG_USBHOST_MAX_INTERFACES 6
135#define CONFIG_USBHOST_MAX_INTF_ALTSETTINGS 1
136#define CONFIG_USBHOST_MAX_ENDPOINTS 4
137```
138
139x is affected by the following macros：
140
141```
142#define CONFIG_USBHOST_MAX_CDC_ACM_CLASS 4
143#define CONFIG_USBHOST_MAX_HID_CLASS 4
144#define CONFIG_USBHOST_MAX_MSC_CLASS 2
145#define CONFIG_USBHOST_MAX_AUDIO_CLASS 1
146#define CONFIG_USBHOST_MAX_VIDEO_CLASS 1
147#define CONFIG_USBHOST_MAX_RNDIS_CLASS 1
148
149```
150
151## Documentation Tutorial
152
153Quickly start, USB basic concepts, API manual, Class basic concepts and examples, see [CherryUSB Documentation Tutorial](https://cherryusb.readthedocs.io/)
154
155## Video Tutorial
156
157USB basic concepts and how the CherryUSB Device stack is implemented, see [CherryUSB Device Stack Tutorial](https://www.bilibili.com/video/BV1Ef4y1t73d).
158
159## Graphical Config Tool
160
161[chryusb_configurator](https://github.com/Egahp/chryusb_configurator) is written in **electron + vite2 + ts** framework，currently used to automate the generation of descriptor arrays, with additional functionality to be added later.
162
163## Demo Repo
164
165| Manufacturer | CHIP or Series | USB IP| Repo Url |Current version|
166|:--------------------:|:------------------:|:-----:|:--------:|:---------------------------:|
167|Bouffalolab | BL702/BL616/BL808 | bouffalolab/ehci|[bouffalo_sdk](https://github.com/CherryUSB/cherryusb_bouffalolab)| v0.10.1 |
168|ST | STM32F1x | fsdev |[stm32_repo](https://github.com/CherryUSB/cherryusb_stm32)|≤ v0.10.1 |
169|ST | STM32F4/STM32H7 | dwc2 |[stm32_repo](https://github.com/CherryUSB/cherryusb_stm32)|≤ v0.10.1 |
170|HPMicro | HPM6750 | hpm/ehci |[hpm_sdk](https://github.com/CherryUSB/cherryusb_hpmicro)| v0.10.1 |
171|Essemi | ES32F36xx | musb |[es32f369_repo](https://github.com/CherryUSB/cherryusb_es32)|≤ v0.10.1 |
172|AllwinnerTech | F1C100S/F1C200S | musb |[cherryusb_rtt_f1c100s](https://github.com/CherryUSB/cherryusb_rtt_f1c100s)|≤ v0.10.1 |
173|Phytium | e2000 | xhci |[phytium_repo](https://gitee.com/phytium_embedded/phytium-free-rtos-sdk)|v0.9.0 |
174|Raspberry pi | rp2040 | rp2040 |[pico-examples](https://github.com/CherryUSB/pico-examples)|≤ v0.10.1 |
175|WCH | CH32V307/ch58x | ch32_usbfs/ch32_usbhs/ch58x |[wch_repo](https://github.com/CherryUSB/cherryusb_wch)|≤ v0.10.1 |
176|Nordicsemi | Nrf52840 | nrf5x |[nrf5x_repo](https://github.com/CherryUSB/cherryusb_nrf5x)|≤ v0.10.1 |
177|Espressif | esp32s3 | dwc2 |[esp32_repo](https://github.com/CherryUSB/cherryusb_esp32)|≤ v0.10.1 |
178|Bekencorp | BK72xx | musb |[armino](https://github.com/CherryUSB/armino)|v0.7.0 |
179|Sophgo | cv18xx | dwc2 |[cvi_alios_open](https://github.com/CherryUSB/cvi_alios_open)|v0.7.0 |
180
181## Contact
182
183QQ group: 642693751
