2022-02-01 23:07:38 +08:00
# CherryUSB
2021-12-12 15:21:56 +08:00
[English ](./README.md )
2023-06-03 16:23:16 +08:00
CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统(带 USB IP)的 USB 主从协议栈。
2021-12-12 15:21:56 +08:00
2023-06-30 18:08:30 +08:00

2022-05-21 16:50:01 +08:00
2022-05-25 11:00:17 +08:00
## 为什么选择
2023-06-03 16:23:16 +08:00
### 易于学习 USB
为了方便用户学习 USB 基本知识、枚举、驱动加载、IP 驱动,因此,编写的代码具备以下优点:
- 代码精简,逻辑简单,无复杂 C 语言语法
- 树状化编程,代码层层递进
- Class 驱动和 porting 驱动模板化、精简化
- API 分类清晰(从机:初始化、注册类、命令回调类、数据收发类;主机:初始化、查找类、数据收发类)
### 易于使用 USB
为了方便用户使用 USB 接口,考虑到用户学习过 uart 和 dma, 因此, 设计的数据收发类接口具备以下优点:
- 等价于使用 uart tx dma/uart rx dma
- 收发长度没有限制,用户不需要关心 USB 分包过程( porting 驱动做分包过程)
### 易于发挥 USB 性能
考虑到 USB 性能问题,尽量达到 USB 硬件理论带宽,因此,设计的数据收发类接口具备以下优点:
- Porting 驱动直接对接寄存器,无抽象层封装
- Memory zero copy
- IP 如果带 DMA 则使用 DMA 模式( DMA 带硬件分包功能)
- 长度无限制,方便对接硬件 DMA 并且发挥 DMA 的优势
- 分包功能在中断中处理
2022-05-25 11:00:17 +08:00
## 目录结构
2021-12-12 15:21:56 +08:00
```
.
├── class
├── common
├── core
├── demo
├── docs
2022-01-15 17:14:26 +08:00
├── osal
2021-12-12 15:21:56 +08:00
└── port
2022-05-25 11:00:17 +08:00
└── tools
2021-12-12 15:21:56 +08:00
```
| 目录名 | 描述 |
2023-06-04 14:42:57 +08:00
|:-------------:|:-------------------------------:|
2021-12-12 15:21:56 +08:00
|class | usb class 类主从驱动 |
2022-01-29 23:36:16 +08:00
|common | usb spec 定义、常用宏、标准接口定义 |
2023-06-04 14:42:57 +08:00
|core | usb 主从协议栈核心实现 |
|demo | 示例 |
|docs | 文档 |
2022-01-15 17:14:26 +08:00
|osal | os 封装层 |
2021-12-12 15:21:56 +08:00
|port | usb 主从需要实现的 porting 接口 |
2023-06-04 14:42:57 +08:00
|tools | 工具链接 |
2021-12-12 15:21:56 +08:00
2022-05-25 11:00:17 +08:00
## Device 协议栈简介
2021-12-12 15:21:56 +08:00
2022-02-01 23:07:38 +08:00
CherryUSB Device 协议栈对标准设备请求、CLASS 请求、VENDOR 请求以及 custom 特殊请求规范了一套统一的函数框架,采用面向对象和链表的方式,能够使得用户快速上手复合设备,不用管底层的逻辑。同时,规范了一套标准的 dcd porting 接口,用于适配不同的 USB IP, 达到面向 ip 编程。
2021-12-12 15:21:56 +08:00
2022-02-01 23:07:38 +08:00
CherryUSB Device 协议栈当前实现以下功能:
2021-12-12 15:21:56 +08:00
2023-04-21 23:44:48 +08:00
- 支持 USB2.0 全速和高速设备, USB3.0 超速设备
2021-12-12 15:21:56 +08:00
- 支持端点中断注册功能, porting 给用户自己处理中断里的数据
2022-04-04 15:54:53 +08:00
- 支持复合设备
2022-01-29 23:36:16 +08:00
- 支持 Communication Device Class (CDC)
2021-12-12 15:21:56 +08:00
- 支持 Human Interface Device (HID)
- 支持 Mass Storage Class (MSC)
2022-04-04 15:54:53 +08:00
- 支持 USB VIDEO CLASS (UVC1.0、UVC1.5)
- 支持 USB AUDIO CLASS (UAC1.0、UAC2.0)
2021-12-12 15:21:56 +08:00
- 支持 Device Firmware Upgrade CLASS (DFU)
- 支持 USB MIDI CLASS (MIDI)
2022-04-04 15:54:53 +08:00
- 支持 Remote NDIS (RNDIS)
- 支持 WINUSB1.0、WINUSB2.0(带 BOS )
2021-12-12 15:21:56 +08:00
- 支持 Vendor 类 class
2022-05-25 11:00:17 +08:00
CherryUSB Device 协议栈资源占用说明( GCC 10.2 with -O2) :
2021-12-12 15:21:56 +08:00
2022-10-20 21:22:08 +08:00
| file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) |
|:-------------:|:--------------:|:-------------------------:|:-------------:|:----------------:|
2023-07-12 23:01:15 +08:00
|usbd_core.c | 3516 | 256(default) + 320 | 0 | 0 |
|usbd_cdc.c | 392 | 0 | 0 | 0 |
|usbd_msc.c | 2839 | 128 + 512(default) | 16 | 0 |
|usbd_hid.c | 364 | 0 | 0 | 0 |
|usbd_audio.c | 1455 | 0 | 0 | 0 |
|usbd_video.c | 2494 | 0 | 84 | 0 |
|usbd_rndis.c | 2109 | 3340 | 76 | 0 |
2021-12-12 15:21:56 +08:00
2022-05-25 11:00:17 +08:00
## Host 协议栈简介
2021-12-12 15:21:56 +08:00
2022-02-01 23:07:38 +08:00
CherryUSB Host 协议栈对挂载在 roothub、外部 hub 上的设备规范了一套标准的枚举实现,对不同的 Class 类也规范了一套标准接口,用来指示在枚举后和断开连接后该 Class 驱动需要做的事情。同时,规范了一套标准的 hcd porting 接口,用于适配不同的 USB IP, 达到面向 IP 编程。最后,协议栈使用 OS 管理,并提供了 osal 用来适配不同的 os。
2022-01-29 23:36:16 +08:00
2022-02-01 23:07:38 +08:00
CherryUSB Host 协议栈当前实现以下功能:
2022-01-29 23:36:16 +08:00
- 自动加载支持的Class 驱动
- 支持阻塞式传输和异步传输
2022-04-04 15:54:53 +08:00
- 支持复合设备
2022-01-29 23:36:16 +08:00
- 支持多级 HUB,最高可拓展到 7 级
- 支持 Communication Device Class (CDC)
- 支持 Human Interface Device (HID)
- 支持 Mass Storage Class (MSC)
2022-12-31 22:48:05 +08:00
- Support USB Video CLASS
- Support USB Audio CLASS
2022-04-04 15:54:53 +08:00
- 支持 Remote NDIS (RNDIS)
- 支持 Vendor 类 class
2022-01-29 23:36:16 +08:00
2022-02-01 23:07:38 +08:00
同时, CherryUSB Host 协议栈还提供了 lsusb 的功能,借助 shell 插件可以查看所有挂载设备的信息,包括外部 hub 上的设备的信息。
2022-01-29 23:36:16 +08:00
2022-06-23 21:30:32 +08:00
CherryUSB Host 协议栈资源占用说明( GCC 10.2 with -O2) :
2022-09-14 20:33:47 +08:00
| file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) |
|:-------------:|:--------------:|:-------------------------------:|:---------------------------:|:-------------------------------:|
2023-07-12 23:01:15 +08:00
|usbh_core.c | 4237 | 512 + 8 * (1+x) *n | 28 | sizeof(struct usbh_urb) |
|usbh_hub.c | 2919 | 32 + 4* (1+x) | 12 + sizeof(struct usbh_hub) * (1+x) | 0 |
|usbh_cdc_acm.c | 1099 | 7 | 4 + sizeof(struct usbh_cdc_acm) * x | 0 |
|usbh_msc.c | 2502 | 32 | 4 + sizeof(struct usbh_msc) * x | 0 |
|usbh_hid.c | 956 | 128 | 4 + sizeof(struct usbh_hid) * x | 0 |
|usbh_video.c | 2330 | 128 | 4 + sizeof(struct usbh_video) * x | 0 |
|usbh_audio.c | 3168 | 128 | 4 + sizeof(struct usbh_audio) * x | 0 |
|usbh_rndis.c | 3030 | 4096 | 4 + sizeof(struct usbh_rndis) * x | 0 |
2022-09-14 20:33:47 +08:00
其中,`sizeof(struct usbh_hub)` 和 `sizeof(struct usbh_hubport)` 受以下宏影响:
```
#define CONFIG_USBHOST_MAX_EXTHUBS 1
#define CONFIG_USBHOST_MAX_EHPORTS 4
#define CONFIG_USBHOST_MAX_INTERFACES 6
#define CONFIG_USBHOST_MAX_INTF_ALTSETTINGS 1
#define CONFIG_USBHOST_MAX_ENDPOINTS 4
```
2022-06-23 21:30:32 +08:00
2023-07-12 23:01:15 +08:00
x 受以下宏影响:
```
#define CONFIG_USBHOST_MAX_CDC_ACM_CLASS 4
#define CONFIG_USBHOST_MAX_HID_CLASS 4
#define CONFIG_USBHOST_MAX_MSC_CLASS 2
#define CONFIG_USBHOST_MAX_AUDIO_CLASS 1
#define CONFIG_USBHOST_MAX_VIDEO_CLASS 1
#define CONFIG_USBHOST_MAX_RNDIS_CLASS 1
```
2022-05-25 11:00:17 +08:00
## 文档教程
2021-12-12 15:21:56 +08:00
2022-03-08 12:39:41 +08:00
CherryUSB 快速入门、USB 基本概念, API 手册, Class 基本概念和例程,参考 [CherryUSB 文档教程 ](https://cherryusb.readthedocs.io/ )
2021-12-12 15:21:56 +08:00
2022-05-25 11:00:17 +08:00
## 视频教程
2021-12-12 15:21:56 +08:00
2022-02-14 22:39:17 +08:00
USB 基本知识点与 CherryUSB Device 协议栈是如何编写的,参考 [CherryUSB Device 协议栈教程 ](https://www.bilibili.com/video/BV1Ef4y1t73d ).
2022-04-13 10:29:33 +08:00
2022-05-25 11:00:17 +08:00
## 图形化界面配置工具
2022-04-13 10:29:33 +08:00
2022-05-27 22:52:37 +08:00
[chryusb_configurator ](https://github.com/Egahp/chryusb_configurator ) 采用 **electron + vite2 + ts ** 框架编写,当前用于自动化生成描述符数组,后续会增加其他功能。
## 示例仓库
2023-09-30 22:01:22 +08:00
| 厂商 | 芯片或者系列 | USB IP| 仓库链接 | 当前版本 |
2022-07-28 21:25:29 +08:00
|:--------------------:|:------------------:|:-----:|:--------:|:---------------------------:|
2023-09-30 22:01:22 +08:00
|Bouffalolab | BL702/BL616/BL808 | bouffalolab/ehci|[bouffalo_sdk ](https://github.com/CherryUSB/cherryusb_bouffalolab )| v0.10.1 |
|ST | STM32F1x | fsdev |[stm32_repo ](https://github.com/CherryUSB/cherryusb_stm32 )|≤ v0.10.1 |
|ST | STM32F4/STM32H7 | dwc2 |[stm32_repo ](https://github.com/CherryUSB/cherryusb_stm32 )|≤ v0.10.1 |
|HPMicro | HPM6750 | hpm/ehci |[hpm_sdk ](https://github.com/CherryUSB/cherryusb_hpmicro )| v0.10.1 |
|Essemi | ES32F36xx | musb |[es32f369_repo ](https://github.com/CherryUSB/cherryusb_es32 )|≤ v0.10.1 |
|AllwinnerTech | F1C100S/F1C200S | musb |[cherryusb_rtt_f1c100s ](https://github.com/CherryUSB/cherryusb_rtt_f1c100s )|≤ v0.10.1 |
2023-07-29 17:05:21 +08:00
|Phytium | e2000 | xhci |[phytium_repo ](https://gitee.com/phytium_embedded/phytium-free-rtos-sdk )|v0.9.0 |
2023-09-30 22:01:22 +08:00
|Raspberry pi | rp2040 | rp2040 |[pico-examples ](https://github.com/CherryUSB/pico-examples )|≤ v0.10.1 |
|WCH | CH32V307/ch58x | ch32_usbfs/ch32_usbhs/ch58x |[wch_repo ](https://github.com/CherryUSB/cherryusb_wch )|≤ v0.10.1 |
|Nordicsemi | Nrf52840 | nrf5x |[nrf5x_repo ](https://github.com/CherryUSB/cherryusb_nrf5x )|≤ v0.10.1 |
|Espressif | esp32s3 | dwc2 |[esp32_repo ](https://github.com/CherryUSB/cherryusb_esp32 )|≤ v0.10.1 |
2023-05-24 20:28:08 +08:00
|Bekencorp | BK72xx | musb |[armino ](https://github.com/CherryUSB/armino )|v0.7.0 |
2023-05-26 21:18:09 +08:00
|Sophgo | cv18xx | dwc2 |[cvi_alios_open ](https://github.com/CherryUSB/cvi_alios_open )|v0.7.0 |
2022-06-05 16:45:39 +08:00
## Contact
QQ 群:642693751