leeebo/cherryusb

# CherryUSB [English](./README.md) CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统(带 USB IP)的 USB 主从协议栈。 ![CherryUSB](./docs/assets/CherryUSB.svg) ## 为什么选择 ### 易于学习 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 的优势 - 分包功能在中断中处理 ## 目录结构 ``` . ├── class ├── common ├── core ├── demo ├── docs ├── osal └── port └── tools ``` | 目录名 | 描述 | |:-------------:|:-------------------------------:| |class | usb class 类主从驱动 | |common | usb spec 定义、常用宏、标准接口定义 | |core | usb 主从协议栈核心实现 | |demo | 示例 | |docs | 文档 | |osal | os 封装层 | |port | usb 主从需要实现的 porting 接口 | |tools | 工具链接 | ## Device 协议栈简介 CherryUSB Device 协议栈对标准设备请求、CLASS 请求、VENDOR 请求以及 custom 特殊请求规范了一套统一的函数框架，采用面向对象和链表的方式，能够使得用户快速上手复合设备，不用管底层的逻辑。同时，规范了一套标准的 dcd porting 接口，用于适配不同的 USB IP，达到面向 ip 编程。 CherryUSB Device 协议栈当前实现以下功能： - 支持 USB2.0 全速和高速设备，USB3.0 超速设备 - 支持端点中断注册功能，porting 给用户自己处理中断里的数据 - 支持复合设备 - 支持 Communication Device Class (CDC) - 支持 Human Interface Device (HID) - 支持 Mass Storage Class (MSC) - 支持 USB VIDEO CLASS (UVC1.0、UVC1.5) - 支持 USB AUDIO CLASS (UAC1.0、UAC2.0) - 支持 Device Firmware Upgrade CLASS (DFU) - 支持 USB MIDI CLASS (MIDI) - 支持 Remote NDIS (RNDIS) - 支持 WINUSB1.0、WINUSB2.0(带 BOS ) - 支持 Vendor 类 class CherryUSB Device 协议栈资源占用说明（GCC 10.2 with -O2）： | file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) | |:-------------:|:--------------:|:-------------------------:|:-------------:|:----------------:| |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 | ## Host 协议栈简介 CherryUSB Host 协议栈对挂载在 roothub、外部 hub 上的设备规范了一套标准的枚举实现，对不同的 Class 类也规范了一套标准接口，用来指示在枚举后和断开连接后该 Class 驱动需要做的事情。同时，规范了一套标准的 hcd porting 接口，用于适配不同的 USB IP，达到面向 IP 编程。最后，协议栈使用 OS 管理，并提供了 osal 用来适配不同的 os。 CherryUSB Host 协议栈当前实现以下功能： - 自动加载支持的Class 驱动 - 支持阻塞式传输和异步传输 - 支持复合设备 - 支持多级 HUB,最高可拓展到 7 级 - 支持 Communication Device Class (CDC) - 支持 Human Interface Device (HID) - 支持 Mass Storage Class (MSC) - Support USB Video CLASS - Support USB Audio CLASS - 支持 Remote NDIS (RNDIS) - 支持 Vendor 类 class 同时，CherryUSB Host 协议栈还提供了 lsusb 的功能，借助 shell 插件可以查看所有挂载设备的信息，包括外部 hub 上的设备的信息。 CherryUSB Host 协议栈资源占用说明（GCC 10.2 with -O2）： | file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) | |:-------------:|:--------------:|:-------------------------------:|:---------------------------:|:-------------------------------:| |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 | 其中，`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 ``` 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 ``` ## 文档教程 CherryUSB 快速入门、USB 基本概念，API 手册，Class 基本概念和例程，参考 [CherryUSB 文档教程](https://cherryusb.readthedocs.io/) ## 视频教程 USB 基本知识点与 CherryUSB Device 协议栈是如何编写的，参考 [CherryUSB Device 协议栈教程](https://www.bilibili.com/video/BV1Ef4y1t73d). ## 图形化界面配置工具 [chryusb_configurator](https://github.com/Egahp/chryusb_configurator) 采用 **electron + vite2 + ts** 框架编写，当前用于自动化生成描述符数组，后续会增加其他功能。 ## 示例仓库 | 厂商 | 芯片或者系列 | USB IP| 仓库链接 | 对应 master 版本 | |:--------------------:|:------------------:|:-----:|:--------:|:---------------------------:| |Bouffalolab | BL702/BL616/BL808 | bouffalolab/ehci|[bouffalo_sdk](https://github.com/CherryUSB/cherryusb_bouffalolab)| v0.9.0 | |ST | STM32F1x | fsdev |[stm32_repo](https://github.com/CherryUSB/cherryusb_stm32)|latest | |ST | STM32F4/STM32H7 | dwc2 |[stm32_repo](https://github.com/CherryUSB/cherryusb_stm32)|latest | |HPMicro | HPM6750 | hpm/ehci |[hpm_sdk](https://github.com/CherryUSB/cherryusb_hpmicro)|v0.8.0 | |Essemi | ES32F36xx | musb |[es32f369_repo](https://github.com/CherryUSB/cherryusb_es32)|latest | |AllwinnerTech | F1C100S/F1C200S | musb |[cherryusb_rtt_f1c100s](https://github.com/CherryUSB/cherryusb_rtt_f1c100s)|latest | |Phytium | e2000 | xhci |[phytium_repo](https://gitee.com/phytium_embedded/phytium-free-rtos-sdk)|v0.9.0 | |Raspberry pi | rp2040 | rp2040 |[pico-examples](https://github.com/CherryUSB/pico-examples)|latest | |WCH | CH32V307/ch58x | ch32_usbfs/ch32_usbhs/ch58x |[wch_repo](https://github.com/CherryUSB/cherryusb_wch)|latest | |Nordicsemi | Nrf52840 | nrf5x |[nrf5x_repo](https://github.com/CherryUSB/cherryusb_nrf5x)|latest | |Espressif | esp32s3 | dwc2 |[esp32_repo](https://github.com/CherryUSB/cherryusb_esp32)|latest | |Bekencorp | BK72xx | musb |[armino](https://github.com/CherryUSB/armino)|v0.7.0 | |Sophgo | cv18xx | dwc2 |[cvi_alios_open](https://github.com/CherryUSB/cvi_alios_open)|v0.7.0 | |Nuvoton | Nuc442 | nuvoton |[nuc442_repo](https://github.com/CherryUSB/cherryusb_nuc442)|v0.4.1 | |Geehy | APM32E10x APM32F0xx| fsdev |[apm32_repo](https://github.com/CherryUSB/cherryusb_apm32)|v0.4.1 | ## Contact QQ 群:642693751

readme (zh)

Links

Targets

License: Apache-2.0

Stats

Badge