chore(docs): update rst

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            |

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            |

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
 -----------------

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

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

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` ，根据官方环境搭建完成后，即可编译使用。

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`

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`

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