Skip to content

Commit 14320e3

Browse files
MDLZCOOLMDLZCOOL
committed
docs: 更新 README 文件结构和内容
- 统一文字，英文文档中不应该出现中文字符 - 在 README.md 中添加简体中文和繁体中文版本的链接 - 重新组织 README.md 的结构，优化标题层级 - 删除冗余的空行和不必要的标点符号
1 parent 9fd5c47 commit 14320e3

File tree

2 files changed

+452
-0
lines changed

2 files changed

+452
-0
lines changed

‎README_zh-CN.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
**[English](README.md) | 简体中文 | [繁體中文](README_zh-TW.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+
11+
CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统（带 USB IP）的高性能 USB 主从协议栈。
12+
13+
![CherryUSB](CherryUSB.svg)
14+
15+
## 为什么选择 CherryUSB
16+
17+
### 易于学习 USB
18+
19+
为了方便用户学习 USB 基本知识、枚举、驱动加载、IP 驱动，因此，编写的代码具备以下优点：
20+
21+
- 代码精简，逻辑简单，无复杂 C 语言语法
22+
- 树状化编程，代码层层递进
23+
- Class 驱动和 porting 驱动模板化、精简化
24+
- API 分类清晰（从机：初始化、注册类、命令回调类、数据收发类；主机：初始化、查找类、数据收发类）
25+
26+
### 易于使用 USB
27+
28+
为了方便用户使用 USB 接口，考虑到用户学习过 uart 和 dma，因此，设计的数据收发类接口具备以下优点：
29+
30+
- 等价于使用 uart tx dma/uart rx dma
31+
- 收发长度没有限制，用户不需要关心 USB 分包过程（分包过程在 porting 中处理）
32+
33+
### 易于发挥 USB 性能
34+
35+
考虑到 USB 性能问题，尽量达到 USB 硬件理论带宽，因此，设计的数据收发类接口具备以下优点：
36+
37+
- Porting 驱动直接对接寄存器，无抽象层封装
38+
- Memory zero copy
39+
- IP 如果带 DMA 则使用 DMA 模式（DMA 带硬件分包功能）
40+
- 长度无限制，方便对接硬件 DMA 并且发挥 DMA 的优势
41+
- 分包过程在中断中执行
42+
43+
## 目录结构
44+
45+
| 目录名 | 描述 |
46+
|:-------------:|:-------------------------------:|
47+
|class | usb class 类主从驱动 |
48+
|common | usb spec 定义、常用宏、标准接口定义 |
49+
|core | usb 主从协议栈核心实现 |
50+
|demo | 主从 class demo |
51+
|docs | 文档 |
52+
|osal | os 封装层 |
53+
|platform | 其他 os 全家桶适配 |
54+
|port | usb 主从需要实现的 porting 接口 |
55+
|tools | 工具链接 |
56+
57+
## Device 协议栈简介
58+
59+
CherryUSB Device 协议栈对标准设备请求、CLASS 请求、VENDOR 请求以及 custom 特殊请求规范了一套统一的函数框架，采用面向对象和链表的方式，能够使得用户快速上手复合设备，不用管底层的逻辑。同时，规范了一套标准的 dcd porting 接口，用于适配不同的 USB IP，达到面向 ip 编程。
60+
61+
CherryUSB Device 协议栈当前实现以下功能：
62+
63+
- 支持 USB2.0 全速和高速设备，USB3.0 超速设备
64+
- 支持端点中断注册功能，porting 给用户自己处理中断里的数据
65+
- 支持复合设备
66+
- 支持 Communication Device Class (CDC_ACM, CDC_ECM)
67+
- 支持 Human Interface Device (HID)
68+
- 支持 Mass Storage Class (MSC)
69+
- 支持 USB VIDEO CLASS (UVC1.0、UVC1.5)
70+
- 支持 USB AUDIO CLASS (UAC1.0、UAC2.0)
71+
- 支持 Device Firmware Upgrade CLASS (DFU)
72+
- 支持 USB MIDI CLASS (MIDI)
73+
- 支持 Remote NDIS (RNDIS)
74+
- 支持 WINUSB1.0、WINUSB2.0、WEBUSB、BOS
75+
- 支持 Vendor 类 class
76+
- 支持 UF2
77+
- 支持 Android Debug Bridge (Only support shell)
78+
- 支持相同 USB IP 的多从机
79+
80+
CherryUSB Device 协议栈资源占用说明（GCC 10.2 with -O2）：
81+
82+
| file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) |
83+
|:-------------:|:--------------:|:-------------------------:|:-------------:|:----------------:|
84+
|usbd_core.c | ~4400 | 512(default) + 320 | 0 | 0 |
85+
|usbd_cdc_acm.c | ~400 | 0 | 0 | 0 |
86+
|usbd_msc.c | ~3800 | 128 + 512(default) | 16 | 0 |
87+
|usbd_hid.c | ~360 | 0 | 0 | 0 |
88+
|usbd_audio.c | ~1500 | 0 | 0 | 0 |
89+
|usbd_video.c | ~2600 | 0 | 84 | 0 |
90+
|usbd_rndis.c | ~2100 | 2 * 1580(default)+156+8 | 76 | 0 |
91+
92+
## Host 协议栈简介
93+
94+
CherryUSB Host 协议栈对挂载在 root WEBUSBhub、外部 hub 上的设备规范了一套标准的枚举实现，对不同的 Class 类也规范了一套标准接口，用来指示在枚举后和断开连接后该 Class 驱动需要做的事情。同时，规范了一套标准的 hcd porting 接口，用于适配不同的 USB IP，达到面向 IP 编程。最后，协议栈使用 OS 管理，并提供了 osal 用来适配不同的 os。
95+
96+
CherryUSB Host 协议栈当前实现以下功能：
97+
98+
- 支持 low speed, full speed, high speed 和 super speed 设备
99+
- 自动加载支持的Class 驱动
100+
- 支持阻塞式传输和异步传输
101+
- 支持复合设备
102+
- 支持多级 HUB，最高可拓展到 7 级(目前测试 1拖 10 没有问题，仅支持 dwc2/ehci/xhci/rp2040)
103+
- 支持 Communication Device Class (CDC_ACM, CDC_ECM)
104+
- 支持 Human Interface Device (HID)
105+
- 支持 Mass Storage Class (MSC)
106+
- Support USB Video CLASS (UVC1.0、UVC1.5)
107+
- Support USB Audio CLASS (UAC1.0)
108+
- 支持 Remote NDIS (RNDIS)
109+
- 支持 USB Bluetooth (支持 nimble and zephyr bluetooth 协议栈，支持 **CLASS: 0xE0** 或者厂家自定义类，类似于 cdc acm 功能)
110+
- 支持 Vendor 类 class (serial, net, wifi)
111+
- 支持 USB modeswitch
112+
- 支持 Android Open Accessory
113+
- 支持相同 USB IP 的多主机
114+
115+
同时，CherryUSB Host 协议栈还提供了 lsusb 的功能，借助 shell 插件可以查看所有挂载设备的信息，包括外部 hub 上的设备的信息。
116+
117+
CherryUSB Host 协议栈资源占用说明（GCC 10.2 with -O2）：
118+
119+
| file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) |
120+
|:-------------:|:--------------:|:-------------------------------:|:---------------------------:|:------------:|
121+
|usbh_core.c | ~9000 | 512 + 8 * (1+x) *n | 28 | raw_config_desc |
122+
|usbh_hub.c | ~6000 | 32 + 4 * (1+x) | 12 + sizeof(struct usbh_hub) * (1+x) | 0 |
123+
|usbh_cdc_acm.c | ~900 | 7 | 4 + sizeof(struct usbh_cdc_acm) * x | 0 |
124+
|usbh_msc.c | ~2700 | 64 | 4 + sizeof(struct usbh_msc) * x | 0 |
125+
|usbh_hid.c | ~1400 | 256 | 4 + sizeof(struct usbh_hid) * x | 0 |
126+
|usbh_video.c | ~3800 | 128 | 4 + sizeof(struct usbh_video) * x | 0 |
127+
|usbh_audio.c | ~4100 | 128 | 4 + sizeof(struct usbh_audio) * x | 0 |
128+
|usbh_rndis.c | ~4200 | 512 + 2 * 2048(default)| sizeof(struct usbh_rndis) * 1 | 0 |
129+
|usbh_cdc_ecm.c | ~2200 | 2 * 1514 + 16 | sizeof(struct usbh_cdc_ecm) * 1 | 0 |
130+
|usbh_cdc_ncm.c | ~3300 | 2 * 2048(default) + 16 + 32 | sizeof(struct usbh_cdc_ncm) * 1 | 0 |
131+
|usbh_bluetooth.c | ~1000 | 2 * 2048(default) | sizeof(struct usbh_bluetooth) * 1 | 0 |
132+
133+
其中，`sizeof(struct usbh_hub)` 和 `sizeof(struct usbh_hubport)` 受以下宏影响：
134+
135+
```
136+
#define CONFIG_USBHOST_MAX_EXTHUBS 1
137+
#define CONFIG_USBHOST_MAX_EHPORTS 4
138+
#define CONFIG_USBHOST_MAX_INTERFACES 8
139+
#define CONFIG_USBHOST_MAX_INTF_ALTSETTINGS 8
140+
#define CONFIG_USBHOST_MAX_ENDPOINTS 4
141+
```
142+
143+
x 受以下宏影响：
144+
145+
```
146+
#define CONFIG_USBHOST_MAX_CDC_ACM_CLASS 4
147+
#define CONFIG_USBHOST_MAX_HID_CLASS 4
148+
#define CONFIG_USBHOST_MAX_MSC_CLASS 2
149+
#define CONFIG_USBHOST_MAX_AUDIO_CLASS 1
150+
#define CONFIG_USBHOST_MAX_VIDEO_CLASS 1
151+
```
152+
153+
## USB IP 支持情况
154+
155+
仅列举标准 USB IP 和商业性 USB IP
156+
157+
| IP | device | host | Support status |
158+
|:----------------:|:----------:|:--------:|:--------------:|
159+
| OHCI(intel) | none | OHCI | √ |
160+
| EHCI(intel) | none | EHCI | √ |
161+
| XHCI(intel) | none | XHCI | √ |
162+
| UHCI(intel) | none | UHCI | × |
163+
| DWC2(synopsys) | DWC2 | DWC2 | √ |
164+
| MUSB(mentor) | MUSB | MUSB | √ |
165+
| FOTG210(faraday)| FOTG210 | EHCI | √ |
166+
| CHIPIDEA(synopsys)| CHIPIDEA | EHCI | √ |
167+
| CDNS2(cadence) | CDNS2 | CDNS2 | √ |
168+
| CDNS3(cadence) | CDNS3 | XHCI | × |
169+
| DWC3(synopsys) | DWC3 | XHCI | × |
170+
171+
## 文档教程
172+
173+
CherryUSB 快速入门、USB 基本概念、API 手册、Class 基本概念和例程，参考 [CherryUSB Documentation Tutorial](https://cherryusb.readthedocs.io/)。
174+
175+
## 视频教程
176+
177+
- USB 基本知识点与 CherryUSB Device 协议栈是如何编写的（使用 v0.4.1 版本），参考 https://www.bilibili.com/video/BV1Ef4y1t73d 。
178+
- CherryUSB 腾讯会议（使用 v1.1.0 版本），参考 https://www.bilibili.com/video/BV16x421y7mM 。
179+
180+
## 图形化界面配置工具
181+
182+
[chryusb_configurator](https://github.com/Egahp/chryusb_configurator) 采用 **electron + vite2 + ts** 框架编写，当前用于自动化生成描述符数组，后续会增加其他功能。
183+
184+
## 示例仓库
185+
186+
| Manufacturer | CHIP or Series | USB IP| Repo Url | Support version | Support status |
187+
|:--------------------:|:------------------:|:-----:|:--------:|:------------------:|:-------------:|
188+
|Bouffalolab | BL702/BL616/BL808 | bouffalolab/ehci|[bouffalo_sdk](https://github.com/CherryUSB/bouffalo_sdk)|<= latest | Long-term |
189+
|ST | STM32F1x | fsdev |[stm32_repo](https://github.com/CherryUSB/cherryusb_stm32)|<= latest | Long-term |
190+
|ST | STM32F4/STM32H7 | dwc2 |[stm32_repo](https://github.com/CherryUSB/cherryusb_stm32)|<= latest | Long-term |
191+
|HPMicro | HPM6000/HPM5000 | hpm/ehci |[hpm_sdk](https://github.com/CherryUSB/hpm_sdk)|<= latest | Long-term |
192+
|Essemi | ES32F36xx | musb |[es32f369_repo](https://github.com/CherryUSB/cherryusb_es32)|<= latest | Long-term |
193+
|Phytium | e2000 | pusb2/xhci |[phytium_repo](https://gitee.com/phytium_embedded/phytium-free-rtos-sdk)|>=1.4.0 | Long-term |
194+
|Artinchip | d12x/d13x/d21x | aic/ehci/ohci |[luban-lite](https://gitee.com/artinchip/luban-lite)|<= latest | Long-term |
195+
|Espressif | esp32s2/esp32s3/esp32p4 | dwc2 |[esp32_repo](https://github.com/CherryUSB/cherryusb_esp32)|<= latest | Long-term |
196+
|NXP | mcx | kinetis/chipidea/ehci |[nxp_mcx_repo](https://github.com/CherryUSB/cherryusb_mcx)|<= latest | Long-term |
197+
|Kendryte | k230 | dwc2 |[k230_repo](https://github.com/CherryUSB/k230_sdk)|v1.2.0 | Long-term |
198+
|Raspberry pi | rp2040/rp2350 | rp2040 |[pico-examples](https://github.com/CherryUSB/pico-examples)|<= latest | Long-term |
199+
|AllwinnerTech | F1C100S/F1C200S | musb |[cherryusb_rtt_f1c100s](https://github.com/CherryUSB/cherryusb_rtt_f1c100s)|<= latest | the same with musb |
200+
|Bekencorp | bk7256/bk7258 | musb |[bk_idk](https://github.com/CherryUSB/bk_idk)| v0.7.0 | the same with musb |
201+
|Sophgo | cv18xx | dwc2 |[cvi_alios_open](https://github.com/CherryUSB/cvi_alios_open)| v0.7.0 | TBD |
202+
|WCH | CH32V307/ch58x | ch32_usbfs/ch32_usbhs/ch58x |[wch_repo](https://github.com/CherryUSB/cherryusb_wch)|<= v0.10.2 | TBD |
203+
204+
## 软件包支持
205+
206+
CherryUSB 软件包可以通过以下方式获取：
207+
208+
- [RT-Thread](https://packages.rt-thread.org/detail.html?package=CherryUSB)
209+
- [YOC](https://www.xrvm.cn/document?temp=usb-host-protocol-stack-device-driver-adaptation-instructions&slug=yocbook)
210+
- [ESP-Registry](https://components.espressif.com/components/cherry-embedded/cherryusb)
211+
212+
## 商业支持
213+
214+
参考 https://cherryusb.readthedocs.io/zh-cn/latest/support/index.html 。
215+
216+
## 联系
217+
218+
CherryUSB QQ群：642693751
219+
220+
CherryUSB 微信群：与我联系后邀请加入
221+
222+
## 支持企业
223+
224+
感谢以下企业支持（顺序不分先后）：
225+
226+
<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" />

0 commit comments

Comments
 (0)