diff --git a/README.md b/README.md index 52772f0..5644f60 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ CherryUSB Device Stack resource usage (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_core.c | 3516 | 512(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 | @@ -109,7 +109,7 @@ CherryUSB Host Stack resource usage (GCC 10.2 with -O2): | file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) | |:-------------:|:--------------:|:-------------------------------:|:---------------------------:|:------------:| -|usbh_core.c | ~7700 | 512 + 8 * (1+x) *n | 28 | 0 | +|usbh_core.c | ~7700 | 512 + 8 * (1+x) *n | 28 | raw_config_desc | |usbh_hub.c | ~5600 | 32 + 4* (1+x) | 12 + sizeof(struct usbh_hub) * (1+x) | 0 | |usbh_cdc_acm.c | ~1200 | 7 | 4 + sizeof(struct usbh_cdc_acm) * x | 0 | |usbh_msc.c | ~2500 | 32 | 4 + sizeof(struct usbh_msc) * x | 0 | diff --git a/README_zh.md b/README_zh.md index 9f0a9fc..eb804f3 100644 --- a/README_zh.md +++ b/README_zh.md @@ -73,7 +73,7 @@ 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_core.c | 3516 | 512(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 | @@ -109,7 +109,7 @@ CherryUSB Host 协议栈资源占用说明（GCC 10.2 with -O2）： | file | FLASH (Byte) | No Cache RAM (Byte) | RAM (Byte) | Heap (Byte) | |:-------------:|:--------------:|:-------------------------------:|:---------------------------:|:------------:| -|usbh_core.c | ~7700 | 512 + 8 * (1+x) *n | 28 | 0 | +|usbh_core.c | ~7700 | 512 + 8 * (1+x) *n | 28 | raw_config_desc | |usbh_hub.c | ~5600 | 32 + 4* (1+x) | 12 + sizeof(struct usbh_hub) * (1+x) | 0 | |usbh_cdc_acm.c | ~1200 | 7 | 4 + sizeof(struct usbh_cdc_acm) * x | 0 | |usbh_msc.c | ~2500 | 32 | 4 + sizeof(struct usbh_msc) * x | 0 | diff --git a/docs/source/api/api_device.rst b/docs/source/api/api_device.rst index f5d5be0..49502c1 100644 --- a/docs/source/api/api_device.rst +++ b/docs/source/api/api_device.rst @@ -1,10 +1,10 @@ 设备协议栈 ========================= -设备协议栈主要负责枚举和驱动加载，枚举这边就不说了，驱动加载，也就是接口驱动加载，主要是依靠 `usbd_add_interface` 函数，记录传入的接口驱动保存到链表中，当主机进行类请求时就可以查找链表进行访问了。 +设备协议栈主要负责枚举和驱动加载，枚举这边就不说了，驱动加载，也就是接口驱动加载，主要是依靠 `usbd_add_interface` 函数，用于记录传入的接口驱动并保存到接口数组表，当主机进行类请求时就可以查找接口表进行访问了。 在调用 `usbd_desc_register` 以后需要进行接口注册和端点注册，口诀如下： -- 有多少个接口就调用多少次 `usbd_add_interface`，参数填相关 `xxx_init_intf`, 如果没有支持的，手动创建一个填入 +- 有多少个接口就调用多少次 `usbd_add_interface`，参数填相关 `xxx_init_intf`, 如果没有支持的，手动创建一个 intf 填入 - 有多少个端点就调用多少次 `usbd_add_endpoint`，当中断完成时，会调用到注册的端点回调中。 CORE @@ -38,7 +38,6 @@ CORE .. code-block:: C struct usbd_interface { - usb_slist_t list; usbd_request_handler class_interface_handler; usbd_request_handler class_endpoint_handler; usbd_request_handler vendor_handler; @@ -48,7 +47,6 @@ CORE uint8_t intf_num; }; -- **list** 接口的链表节点 - **class_interface_handler** class setup 请求回调函数,接收者为接口 - **class_endpoint_handler** class setup 请求回调函数,接收者为端点 - **vendor_handler** vendor setup 请求回调函数 @@ -69,6 +67,9 @@ usbd_desc_register - **desc** 描述符的句柄 +.. note:: 当前 API 仅支持一种速度，如果需要更高级的速度切换功能，请开启 CONFIG_USBDEV_ADVANCE_DESC，并且包含了下面所有描述符注册功能 + + usbd_msosv1_desc_register """""""""""""""""""""""""""""""""""" @@ -284,7 +285,7 @@ usbd_msc_sector_read - **sector** 扇区偏移 - **buffer** 存储读取的数据的指针 -- **length** 读取长度，当前为1个扇区的大小 +- **length** 读取长度 usbd_msc_sector_write @@ -298,7 +299,7 @@ usbd_msc_sector_write - **sector** 扇区偏移 - **buffer** 写入数据指针 -- **length** 写入长度，当前为1个扇区的大小 +- **length** 写入长度 UAC ----------------- diff --git a/docs/source/api/api_host.rst b/docs/source/api/api_host.rst index 4fb12f2..9d77441 100644 --- a/docs/source/api/api_host.rst +++ b/docs/source/api/api_host.rst @@ -49,11 +49,11 @@ CLASS 驱动信息结构体 .. code-block:: C struct usbh_interface { - struct usbh_interface_altsetting altsetting[CONFIG_USBHOST_MAX_INTF_ALTSETTINGS]; - uint8_t altsetting_num; char devname[CONFIG_USBHOST_DEV_NAMELEN]; struct usbh_class_driver *class_driver; void *priv; + struct usbh_interface_altsetting altsetting[CONFIG_USBHOST_MAX_INTF_ALTSETTINGS]; + uint8_t altsetting_num; }; 配置结构体 @@ -76,6 +76,9 @@ hubport 结构体 uint8_t port; /* Hub port index */ uint8_t dev_addr; /* device address */ uint8_t speed; /* device speed */ + uint8_t depth; /* distance from root hub */ + uint8_t route; /* route string */ + uint8_t slot_id; /* slot id */ struct usb_device_descriptor device_desc; struct usbh_configuration config; const char *iManufacturer; @@ -84,6 +87,8 @@ hubport 结构体 uint8_t *raw_config_desc; struct usb_setup_packet *setup; struct usbh_hub *parent; + struct usbh_hub *self; /* if this hubport is a hub */ + struct usbh_bus *bus; struct usb_endpoint_descriptor ep0; struct usbh_urb ep0_urb; usb_osal_mutex_t mutex; @@ -95,17 +100,24 @@ hub 结构体 .. code-block:: C struct usbh_hub { - usb_slist_t list; bool connected; bool is_roothub; uint8_t index; uint8_t hub_addr; - struct usb_hub_descriptor hub_desc; + uint8_t speed; + uint8_t nports; + uint8_t powerdelay; + uint8_t tt_think; + bool ismtt; + struct usb_hub_descriptor hub_desc; /* USB 2.0 only */ + struct usb_hub_ss_descriptor hub_ss_desc; /* USB 3.0 only */ struct usbh_hubport child[CONFIG_USBHOST_MAX_EHPORTS]; struct usbh_hubport *parent; + struct usbh_bus *bus; struct usb_endpoint_descriptor *intin; struct usbh_urb intin_urb; uint8_t *int_buffer; + struct usb_osal_timer *int_timer; }; usbh_initialize diff --git a/docs/source/index.rst b/docs/source/index.rst index c3ceb10..f0b9495 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -56,8 +56,8 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 quick_start/index quick_start/rt-thread/rtthread quick_start/other_chip - q&a version + q&a .. toctree:: :maxdepth: 1 diff --git a/docs/source/quick_start/index.rst b/docs/source/quick_start/index.rst index 392315a..5f68000 100644 --- a/docs/source/quick_start/index.rst +++ b/docs/source/quick_start/index.rst @@ -9,10 +9,16 @@ 仓库参考：https://github.com/CherryUSB/cherryusb_bouffalolab -- BL702 是一个 USB2.0 全速芯片，共 8 个端点（包含端点0）。仅支持从机。 - BL616/BL808 是一个 USB2.0 并且内置高速 PHY 芯片，共 5个端点（包含端点0）。支持主从机。 - USB 的相关应用位于 `examples/usbdev` 和 `examples/usbhost` 目录下，根据官方环境搭建完成后，即可编译使用。 +基于 HPMicro 系列芯片 +--------------------------- + +仓库参考：https://github.com/CherryUSB/cherryusb_hpmicro + +- HPM 系列芯片均 USB 2.0 并且内置高速 PHY，支持主从机 +- USB 的相关应用位于 `samples/cherryusb` ，根据官方环境搭建完成后，即可编译使用。 基于 ST 系列芯片 --------------------------- @@ -173,10 +179,3 @@ USB Host 移植要点 .. figure:: img/stm32_21.png -基于 HPMicro 系列芯片 ---------------------------- - -仓库参考：https://github.com/CherryUSB/cherryusb_hpmicro - -- HPM 系列芯片均 USB 2.0 并且内置高速 PHY，支持主从机 -- USB 的相关应用位于 `samples/cherryusb` ，根据官方环境搭建完成后，即可编译使用。 diff --git a/docs/source/quick_start/other_chip.rst b/docs/source/quick_start/other_chip.rst index ada557d..0f8e4b9 100644 --- a/docs/source/quick_start/other_chip.rst +++ b/docs/source/quick_start/other_chip.rst @@ -1,22 +1,7 @@ 芯片通用移植指南 ========================= -本节主要介绍所有带 USB IP 的芯片，移植 CherryUSB 主从协议栈时的通用步骤和注意事项。在往下看之前，需要 **你准备好一个可以打印 helloworld 的基本工程** ，并且实现了 `printf` 、 `malloc`、 `free`。如果是主机，需要 **准备好可以打印 helloworld 的带 OS 的工程**。通常来说， `printf` 大家都会实现， -`malloc`、 `free` 主要给主机使用, 默认 config 文件使用的就是 `malloc`、 `free`，推荐修改为 os 相关接口, 不推荐使用系统库，尤其是 keil 自带的这种。举例如下： - -.. code-block:: C - - // default config - #define usb_malloc(size) malloc(size) - #define usb_free(ptr) free(ptr) - - // freertos - #define usb_malloc(size) pvPortMalloc(size) - #define usb_free(ptr) vPortFree(ptr) - - //rtthread - #define usb_malloc(size) rt_malloc(size) - #define usb_free(ptr) rt_free(ptr) +本节主要介绍所有带 USB IP 的芯片，移植 CherryUSB 主从协议栈时的通用步骤和注意事项。在移植之前，需要 **你准备好一个可以打印 helloworld 的基本工程** ，默认打印使用 `printf`, 如果是主机模式， **则需要准备好可以正常执行 os 调度的基本工程**。 USB Device 移植要点 ----------------------- @@ -32,7 +17,7 @@ USB Device 移植要点 USB Host 移植要点 ----------------------- -- 拷贝 CherryUSB 源码到工程目录下，并按需添加源文件和头文件路径，其中 `usbh_core.c` 、 `usb_hc_xxx.c` 以及 **osal** 目录下源文件（根据不同的 os 选择对应的源文件）为必须添加项。而 `usb_hc_xxx.c` 是芯片所对应的 USB IP dcd 部分驱动，如果不知道自己芯片属于那个 USB IP，参考 **port** 目录下的不同 USB IP 的 readme。如果使用的 USB IP 没有支持，只能自己实现了 +- 拷贝 CherryUSB 源码到工程目录下，并按需添加源文件和头文件路径，其中 `usbh_core.c` 、 `usb_hc_xxx.c` 以及 **osal** 目录下源文件（根据不同的 os 选择对应的源文件）为必须添加项。而 `usb_hc_xxx.c` 是芯片所对应的 USB IP hcd 部分驱动，如果不知道自己芯片属于那个 USB IP，参考 **port** 目录下的不同 USB IP 的 readme。如果使用的 USB IP 没有支持，只能自己实现了 - 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径 - 实现 `usb_hc_low_level_init` 函数（该函数主要负责 USB 时钟、引脚、中断的初始化）。该函数可以放在你想要放的任何参与编译的 c 文件中。如何进行 USB 的时钟、引脚、中断等初始化，请自行根据你使用的芯片原厂提供的源码中进行添加。 - 调用 `usbh_initialize` 并填入 `busid` 和 USB IP 的 `reg base`， `busid` 从 0 开始，不能超过 `CONFIG_USBHOST_MAX_BUS` diff --git a/docs/source/quick_start/rt-thread/rtthread.rst b/docs/source/quick_start/rt-thread/rtthread.rst index b69b95f..a930371 100644 --- a/docs/source/quick_start/rt-thread/rtthread.rst +++ b/docs/source/quick_start/rt-thread/rtthread.rst @@ -25,11 +25,6 @@ #define CONFIG_USB_PRINTF(...) rt_kprintf(__VA_ARGS__) - #define usb_malloc(size) rt_malloc(size) - #define usb_free(ptr) rt_free(ptr) - - #define memcpy rt_memcpy - * USB IP 相关的 config 需要用户自己根据芯片实际情况修改 * 退出以后不急着编译，需要在代码中实现 `usb_dc_low_level_init` 函数。 * 调用 `usbd_initialize` 并填入 `busid` 和 USB IP 的 `reg base`， `busid` 从 0 开始，不能超过 `CONFIG_USBDEV_MAX_BUS` @@ -72,11 +67,6 @@ #define CONFIG_USB_PRINTF(...) rt_kprintf(__VA_ARGS__) - #define usb_malloc(size) rt_malloc(size) - #define usb_free(ptr) rt_free(ptr) - - #define memcpy rt_memcpy - * USB IP 相关的 config 需要用户自己根据芯片实际情况修改 * 在代码中实现 `usb_hc_low_level_init` 函数 * 调用 `usbh_initialize` 并填入 `busid` 和 USB IP 的 `reg base`， `busid` 从 0 开始，不能超过 `CONFIG_USBHOST_MAX_BUS` diff --git a/docs/source/version.rst b/docs/source/version.rst index 95a5d08..9e7ff2c 100644 --- a/docs/source/version.rst +++ b/docs/source/version.rst @@ -19,7 +19,7 @@ v1.1.0 过度版本 ---------------------- - **主从机支持多 USB IP 且要相同 IP** -- host 增加 bluetooth, chh340, ftdi, cp210x, asix 驱动 +- host 增加 bluetooth, ch340, ftdi, cp210x, asix 驱动 - device msc 支持多 lun，并且 CONFIG_USBDEV_MSC_BLOCK_SIZE 修改为 CONFIG_USBDEV_MSC_MAX_BUFSIZE v1.2.0