Files
CherryUSB/README.md

154 lines
8.9 KiB
Markdown
Raw Normal View History

2022-02-01 23:07:38 +08:00
# CherryUSB
2021-11-30 21:43:33 +08:00
2021-12-12 15:21:56 +08:00
[中文版](./README_zh.md)
2021-11-30 21:43:33 +08:00
2022-05-25 11:00:17 +08:00
CherryUSB is a tiny, beautiful and portable USB host and device stack for embedded system with USB ip.
2021-11-30 21:43:33 +08:00
2022-09-09 21:37:12 +08:00
![CherryUSB](./docs/assets/usb_outline.png)
2022-05-21 16:50:01 +08:00
2022-05-25 11:00:17 +08:00
## Why choose
2022-09-17 14:00:04 +08:00
- Streamlined code with small memory usage which also can be further trimmed
- Comprehensive class drivers and all master and slave class drivers are templated,making it easy for users to add new class drivers and find patterns when learning
- The APIs available to the users are very few and clearly categorised. Device: initialisation + registration apis, command callback apis, data sending and receiving apis; Host: initialisation + lookup apis, data sending and receiving apis
- Tree-based programming with a hierarchy of code that makes it easy for the user to sort out function call relationships, enumerations and class-driven loading processes
- Standardised porting interface, no need to rewrite the driver for the same ip, and porting drivers are templated to make it easier for users to add new ports
- The use of the device or host transceiver apis are equivalent to the use of the uart tx/rx dma, and there is no limit to the length
- Capable of achieving theoretical USB hardware bandwidth
2022-05-25 11:00:17 +08:00
## Directoy Structure
2021-12-04 14:41:09 +08:00
```
.
├── class
├── common
├── core
├── demo
├── docs
2022-01-15 17:14:26 +08:00
├── osal
2021-12-04 14:41:09 +08:00
├── packet capture
└── port
2022-05-25 11:00:17 +08:00
└── tools
2021-12-04 14:41:09 +08:00
```
2021-12-12 15:21:56 +08:00
| Directory | Description |
|:-------------:|:---------------------------:|
|class | usb class driver |
|common | usb spec macros and utils |
|core | usb core implementation |
2022-04-04 15:54:53 +08:00
|demo | different chips demo |
2022-01-15 17:14:26 +08:00
|osal | os wrapper |
2021-12-12 15:21:56 +08:00
|docs | doc for guiding |
2021-12-12 21:49:21 +08:00
|packet capture | packet capture file |
2021-12-12 15:21:56 +08:00
|port | usb dcd and hcd porting |
2022-04-13 10:29:33 +08:00
|tools | tool used url |
2021-12-12 15:21:56 +08:00
2022-05-25 11:00:17 +08:00
## Device Stack Overview
2021-12-12 15:21:56 +08:00
2022-02-01 23:07:38 +08:00
CherryUSB 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.
2021-12-12 15:21:56 +08:00
2022-02-01 23:07:38 +08:00
CherryUSB Device Stack has the following functions
2021-12-12 15:21:56 +08:00
2023-04-22 00:11:49 +08:00
- Support USB2.0 full and high speed, USB3.0 super speed
2021-12-12 15:21:56 +08:00
- Support endpoint irq callback register by users, let users do whatever they wants in endpoint irq callback.
2022-04-04 15:54:53 +08:00
- Support Composite Device
2022-01-29 23:36:16 +08:00
- Support Communication Device Class (CDC)
2021-12-12 15:21:56 +08:00
- Support Human Interface Device (HID)
- Support Mass Storage Class (MSC)
2022-04-04 15:54:53 +08:00
- Support USB VIDEO CLASS (UVC1.0、UVC1.5)
- Support USB AUDIO CLASS (UAC1.0、UAC2.0)
2021-12-12 15:21:56 +08:00
- Support Device Firmware Upgrade CLASS (DFU)
- Support USB MIDI CLASS (MIDI)
2022-04-04 15:54:53 +08:00
- Support Remote NDIS (RNDIS)
- Support WINUSB1.0、WINUSB2.0(with BOS)
2021-12-12 21:49:21 +08:00
- Support Vendor class
2021-12-12 15:21:56 +08:00
2022-06-23 21:30:32 +08:00
CherryUSB Device Stack resource usage (GCC 10.2 with -O2):
2021-11-30 21:43:33 +08:00
2022-10-20 21:22:08 +08:00
| file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) |
|:-------------:|:--------------:|:-------------------------:|:-------------:|:----------------:|
|usbd_core.c | 3263 | 384 | 17 | 0 |
|usbd_cdc.c | 490 | 0 | 0 | 0 |
|usbd_msc.c | 2772 | 128 + 512(default) | 16 | 0 |
|usbd_hid.c | 501 | 0 | 0 | 0 |
|usbd_audio.c | 1208 | 0 | 4 | 0 |
|usbd_video.c | 2272 | 0 | 82 | 0 |
2021-11-30 21:43:33 +08:00
2022-05-25 11:00:17 +08:00
## Host Stack Overview
2021-11-30 21:43:33 +08:00
2022-06-05 16:45:39 +08:00
The 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.
2022-01-29 23:36:16 +08:00
2022-02-01 23:07:38 +08:00
CherryUSB Host Stack has the following functions
2022-01-29 23:36:16 +08:00
- Automatic loading of supported Class drivers
- Support blocking transfers and asynchronous transfers
2022-04-04 15:54:53 +08:00
- Support Composite Device
2022-01-29 23:36:16 +08:00
- Multi-level HUB support, expandable up to 7 levels
- Support Communication Device Class (CDC)
- Support Human Interface Device (HID)
- Support 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
- Support Remote NDIS (RNDIS)
2022-01-29 23:36:16 +08:00
- Support Vendor class
2022-02-01 23:07:38 +08:00
The 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.
2022-01-29 23:36:16 +08:00
2022-06-23 21:30:32 +08:00
CherryUSB Host Stack resource usage (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-02-05 15:28:25 +08:00
|usbh_core.c | 4417 | 512 | 28 | sizeof(struct usbh_urb) |
2023-04-22 14:27:29 +08:00
|usbh_hub.c | 4895 | 32 + 4* (1+n) | 16 + sizeof(struct usbh_hub) * (1+n) | 0 |
2023-02-05 15:28:25 +08:00
|usbh_cdc_acm.c | 1064 | 7 | 4 | sizeof(struct usbh_cdc_acm) * x |
2022-09-14 20:33:47 +08:00
|usbh_msc.c | 1776 | 32 | 4 | sizeof(struct usbh_msc) * x |
2023-02-05 15:28:25 +08:00
|usbh_hid.c | 922 | 128 | 4 | sizeof(struct usbh_hid) * x |
|usbh_video.c | 3592 | 128 | 4 | sizeof(struct usbh_video) * x |
|usbh_audio.c | 3230 | 128 | 4 | sizeof(struct usbh_audio) * x |
2022-09-14 20:33:47 +08:00
Among them, `sizeof(struct usbh_hub)` and `sizeof(struct usbh_hubport)` are affected by the following macros
```
#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
2022-05-25 11:00:17 +08:00
## Documentation Tutorial
2021-11-30 21:43:33 +08:00
Quickly start, USB basic concepts, API manual, Class basic concepts and examples, see [CherryUSB Documentation Tutorial](https://cherryusb.readthedocs.io/)
2021-11-30 21:43:33 +08:00
2022-05-25 11:00:17 +08:00
## Video Tutorial
2021-11-30 21:43:33 +08:00
2022-02-15 21:06:51 +08:00
USB basic concepts and how the CherryUSB Device stack is implemented, see [CherryUSB Device Stack Tutorial](https://www.bilibili.com/video/BV1Ef4y1t73d).
2022-04-13 10:29:33 +08:00
2022-05-25 11:00:17 +08:00
## Graphical Config Tool
2022-04-13 10:29:33 +08:00
2022-05-27 22:52:37 +08:00
[chryusb_configurator](https://github.com/Egahp/chryusb_configurator) is written in **electron + vite2 + ts** frameworkcurrently used to automate the generation of descriptor arrays, with additional functionality to be added later.
## Demo Repo
| Manufacturer | CHIP or Series | USB IP| Repo Url |Corresponds to master version|
|:--------------------:|:------------------:|:-----:|:--------:|:---------------------------:|
2023-05-24 20:28:08 +08:00
|Bouffalolab | BL702/BL616/BL808 | bouffalolab/ehci|[bouffalo_sdk](https://github.com/CherryUSB/cherryusb_bouffalolab)| latest |
2023-05-26 21:18:09 +08:00
|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 |
2023-05-24 20:28:08 +08:00
|HPMicro | HPM6750 | hpm/ehci |[hpm_sdk](https://github.com/CherryUSB/cherryusb_hpmicro)|v0.7.0 |
2023-05-26 21:18:09 +08:00
|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 |
2023-05-24 20:28:08 +08:00
|Phytium | e2000 | xhci |[phytium_repo](https://gitee.com/phytium_embedded/phytium-free-rtos-sdk)|latest |
|Raspberry pi | rp2040 | rp2040 |[pico-examples](https://github.com/CherryUSB/pico-examples)|latest |
2023-01-05 22:27:55 +08:00
|WCH | CH32V307/ch58x | ch32_usbfs/ch32_usbhs/ch58x |[wch_repo](https://github.com/CherryUSB/cherryusb_wch)|latest |
2023-02-18 19:12:32 +08:00
|Nordicsemi | Nrf52840 | nrf5x |[nrf5x_repo](https://github.com/CherryUSB/cherryusb_nrf5x)|latest |
2023-05-19 15:34:29 +08:00
|Espressif | esp32s3 | dwc2 |[esp32_repo](https://github.com/CherryUSB/cherryusb_esp32)|latest |
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 |
|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 |
2022-06-05 16:45:39 +08:00
## Contact
QQ group: 642693751