chore(docs): update rst

2025-05-08 07:59:31 +08:00 · 2024-07-23 20:13:28 +08:00 · 2024-07-23 20:13:28 +08:00 · 4c4ee7f003
commit 4c4ee7f003
parent 1c2fd3407a
9 changed files with 38 additions and 51 deletions
--- 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            |
--- 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            |
--- 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
 -----------------
--- 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
--- 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
--- 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` ，根据官方环境搭建完成后，即可编译使用。
--- 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`
--- 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`
--- 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