v1.0.3

packages/third-party/cherryusb/docs/source/quick_start/bl702.rst

@@ -1,6 +0,0 @@
-基于 BL 系列开发指南
-=========================
-
-BL 系列 USB 的开发主要使用 bl_mcu_sdk，参考 `bl_mcu_sdk <https://github.com/bouffalolab/bl_mcu_sdk>`_。
-
-USB 的相关应用位于 `examples/usbdev` 和 `examples/usbhost` 目录下，环境搭建完成后，即可编译使用。

packages/third-party/cherryusb/docs/source/quick_start/es32.rst

@@ -1,84 +0,0 @@
-基于 ES32F369 开发指南
-=========================
-
-ES32F3xx 系列单片机中 USB 外设使用标准的 musb ip，并且拥有 usb device 和 usb host 功能。本章主要介绍如何在东软载波的 ES32F369x 开发板中使用 CherryUSB。
-
-在使用之前需要从 essemi 官网下载 `keil 芯片支持包 <http://www.essemi.com/index/product/detail?id=796>`_ 并安装，
-
-
-工程样例试用
------------------------
-
-在 CherryUSB demo 目录下已经有主机跟从机的样例，在有板子的情况下，可以先跑工程样例，试用一下。
-
-- 进入 MDK-ARM 目录下，双击 `example.uvprojx` 打开工程，选择好调试器后，编译烧录即可。
-- 如果是从机，默认提供的是 cdc acm 的示例，代码烧录以后，将 usb 线插到 板子的丝印为 USB-OTG 口，并接上电脑，按下复位键，电脑便会枚举出一个串口。打开串口，勾选 DTR 可以接收数据，在发送缓冲区填入数据并发送，调试器的串口便可以打印出接收的长度和数据。
-- 如果是主机，则需要一个 usb 母口转接线，并接入相关 usb 设备，就可以进行测试了。比如接上鼠标、U盘、4G 网卡等等。
-
-USB Device 移植要点
------------------------
-
-针对自定义的工程移植，需要按照以下步骤：
-
-- 准备好可以进行调试打印的工程，并且实现 `printf`、 `malloc` 、 `free` 函数（也可以直接勾选 Use microlib 来使用）。
-- 拷贝 CherryUSB 源码到工程里
-- 添加 CherryUSB 源码和头文件路径，其中 `usbd_core.c` 和 `usb_dc_musb.c` 为必须添加项。
-- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径。所以根目录下的文件仅作为参考，不要添加根目录下的头文件。
-
-.. figure:: img/es322.png
-.. figure:: img/es323.png
-
-- 实现 `usb_dc_low_level_init` 函数，该函数主要负责 USB 时钟、引脚、中断的初始化。例如
-
-.. code-block:: C
-
-    void usb_dc_low_level_init(void)
-    {
-        ald_pmu_perh_power_config(PMU_POWER_USB, ENABLE);
-        ald_cmu_perh_clock_config(CMU_PERH_USB, ENABLE);
-        ald_cmu_perh_clock_config(CMU_PERH_GPIO, ENABLE);
-        ald_cmu_usb_clock_config(CMU_USB_CLOCK_SEL_HOSC, CMU_USB_DIV_1);
-        ald_rmu_reset_periperal(RMU_PERH_USB);
-        ald_mcu_irq_config(USB_INT_IRQn, 2, 2, ENABLE);
-        ald_mcu_irq_config(USB_DMA_IRQn, 2, 2, ENABLE);
-        usb_pin_init();
-    }
-
-- 描述符的注册、class的注册、接口的注册、端点中断的注册。不会的参考 demo 下的 template 。
-- 调用 `usbd_initialize` 初始化 usb 硬件。
-- 正常使用。
-
-
-USB Host 移植要点
------------------------
-
-针对自定义的工程移植，需要以下步骤：
-
-- 准备好可以进行调试打印的带 FreeRTOS 或者 RT-Thread 的工程，并且实现 `printf`、 `malloc` 、 `free` 函数（也可以直接勾选 Use microlib 来使用）。
-- 拷贝 CherryUSB 源码到工程里
-- 添加 CherryUSB 源码和头文件路径，其中 `usbh_core.c` 和 `usb_hc_musb.c` 、 osal 下的文件为必须添加项，根据不同的 os 添加对应的文件。
-- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h` ,并添加相应的目录头文件路径。所以根目录下的文件仅作为参考，不要添加根目录下的头文件。
-
-.. figure:: img/es324.png
-.. figure:: img/es325.png
-
-- 由于是作为主机，推荐添加所有的 class，功能全面。当然如果只用一个 class ，就添加一个。
-- 实现 `usb_hc_low_level_init` 函数，该函数主要负责 USB 时钟、引脚、中断的初始化。例如
-
-.. code-block:: C
-
-    void usb_hc_low_level_init(void)
-    {
-        ald_pmu_perh_power_config(PMU_POWER_USB, ENABLE);
-        ald_cmu_perh_clock_config(CMU_PERH_USB, ENABLE);
-        ald_cmu_perh_clock_config(CMU_PERH_GPIO, ENABLE);
-        ald_cmu_usb_clock_config(CMU_USB_CLOCK_SEL_HOSC, CMU_USB_DIV_1);
-        ald_rmu_reset_periperal(RMU_PERH_USB);
-        ald_mcu_irq_config(USB_INT_IRQn, 2, 2, ENABLE);
-        ald_mcu_irq_config(USB_DMA_IRQn, 2, 2, ENABLE);
-        usb_pin_init();
-    }
-
-- 调用 `usbh_initialize` 初始化 usb 硬件。
-- 此时编译会报错，因为协议栈中为每个 class 都添加了测试 demo，文件在 `usb_host.c` 中，如果不想要，可以直接删除。
-- 正常使用。

packages/third-party/cherryusb/docs/source/quick_start/hpm.rst

@@ -1,6 +0,0 @@
-基于 HPM 系列开发指南
-=========================
-
-HPM 系列 USB 的开发主要使用 hpm_sdk ，参考 `hpm sdk <https://github.com/hpmicro/hpm_sdk>`_。
-
-USB 的相关应用位于 `samples/cherryusb` 目录下，环境搭建完成后，即可编译使用。

packages/third-party/cherryusb/docs/source/quick_start/index.rst

@@ -1,12 +1,39 @@
-基于 STM32F1/F4/H7 开发指南
-=============================
+基于现有 demo 快速验证
+=========================
 
-本节是基于 STM32 三个系列芯片的使用，涵盖 F1/F4/H7，其余芯片基本类似，不再赘述，具体区别有：
+在学习 USB 或者是学习 CherryUSB 代码之前，我们需要先基于现有的 demo 进行快速验证，为什么？是为了提升对 USB 的兴趣，能有信心进行下一步的动作，如果 demo 都跑不起来，或者自己摸索写代码，或者先看 USB 基本概念，结果看到最后，
+发现一点都看不懂，概念好多，根本记不住，从而丧失对 USB 的兴趣。因此，先跑 demo 非常重要。下面我将给大家罗列目前支持的 demo 仓库。
+
+基于 bouffalolab 系列芯片
+---------------------------
+
+仓库参考：https://github.com/CherryUSB/cherryusb_bouffalolab
+
+- BL702 是一个 USB2.0 全速芯片，共 8 个端点（包含端点0）。仅支持从机。
+- BL616/BL808 是一个 USB2.0 并且内置高速 PHY 芯片，共 5个端点（包含端点0）。支持主从机。
+- USB 的相关应用位于 `examples/usbdev` 和 `examples/usbhost` 目录下，根据官方环境搭建完成后，即可编译使用。 
+
+
+基于 ST 系列芯片
+---------------------------
+
+仓库参考：https://github.com/CherryUSB/cherryusb_stm32
+
+默认提供以下 demo 工程：
+
+- F103 使用 fsdev ip
+- F429 主从使用 USB_OTG_HS, 引脚 pb14/pb15, 并且都使用 dma 模式
+- H7 设备使用 USB_OTG_FS, 引脚 pa11/pa12，主机使用 USB_OTG_HS ,引脚 pb14/pb15，并且需要做 nocache 处理
+
+默认删除 Drivers ，所以需要使用 stm32cubemx 生成一下 Drivers 目录下的文件，demo 底下提供了 **stm32xxx.ioc** 文件，双击打开，点击 **Generate Code** 即可。
+
+.. caution:: 生成完以后，请使用 git reset 功能将被覆盖的 `main.c` 和 `stm32xxx_it.c` 文件撤回，禁止被 cubemx 覆盖。
+
+涵盖 F1/F4/H7，其余芯片基本类似，不再赘述，具体区别有：
 
 - usb ip 区别：F1使用 fsdev，F4/H7使用 dwc2
-- dwc2 ip 区别： fs port(引脚是 PA11/PA12) 和 hs port(引脚是 PB14/PB15), 其中 hs port 默认全速，可以接外部PHY 形成高速主机，并且带 dma 功能
-- F4 与 H7 cache 区别、USB BASE 区别
-
+- dwc2 ip 区别： USB_OTG_FS (引脚是 PA11/PA12) 和 USB_OTG_HS (引脚是 PB14/PB15), 其中 USB_OTG_HS 默认全速，可以接外部PHY 形成高速主机，并且带 dma 功能
+- F4 无cache，H7 有 cache
 
 如果是 STM32F7/STM32H7 这种带 cache 功能，需要将 usb 使用到的 ram 定位到 no cache ram 区域。举例如下
 
@@ -33,27 +60,8 @@
     }
     }
 
-
-.. caution :: 如果使用 STM32F7 或者 STM32H7, 请在 CFLAG 中添加 STM32F7 或者 STM32H7 宏定义，否则无法枚举
-
-.. figure:: img/keil.png
-
-工程样例试用
------------------------
-
-默认提供以下 demo 工程：
-
-- F103 使用 fsdev ip
-- F429 主从使用 hs port,并且均用 dma 模式
-- H7 设备使用 fs port，主机使用 hs port，并且主机带 cache 支持
-
-
-默认删除 Drivers ，所以需要使用 stm32cubemx 生成一下 Drivers 目录下的文件，demo 底下提供了 **stm32xxx.ioc** 文件，双击打开，点击 **Generate Code** 即可。
-
-.. caution:: 生成完以后，请使用 git reset 功能将被覆盖的 `main.c` 和 `stm32xxx_it.c` 文件撤回，禁止被 cubemx 覆盖。
-
 USB Device 移植要点
------------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 - 使用 **stm32cubemx** 创建工程，配置基本的 RCC、UART (作为log使用)
 
@@ -86,9 +94,24 @@ USB Device 移植要点
 
 .. figure:: img/stm32_8.png
 
-- 如果使用 dwc2 ip，编译选项中需要添加 `CONFIG_USB_DWC2_PORT=xxx`，使用 PA11/PA12 则 **xxx=FS_PORT**，使用 PB14/PB15 则 **xxx=HS_PORT**
+- 如果使用 dwc2 ip，需要增加 **usb_glue_st.c** 文件，并在 `usb_config.h` 中实现以下宏：
 
-.. figure:: img/stm32_9.png
+.. code-block:: C
+
+    // 以下细节如有出入，请对照 stm32xxx.h 文件修改
+    #define USBD_IRQHandler OTG_HS_IRQHandler // pa11/pa12 引脚使用 OTG_FS_IRQHandler
+    #define USBD_BASE (0x40040000UL)        // pa11/pa12 引脚一般使用 50000000UL，STM32F7/H7 使用 0x40080000UL
+    #define CONFIG_USBDEV_EP_NUM 6          // pa11/pa12 引脚使用 4
+    #define CONFIG_USB_DWC2_RAM_SIZE 4096 // pa11/pa12 引脚使用 1280
+
+- 如果使用 fsdev ip，在 `usb_config.h` 中实现以下宏：
+
+.. code-block:: C
+
+    #define USBD_IRQHandler USB_LP_CAN1_RX0_IRQHandler
+    #define USBD_BASE (0x40005C00UL)
+    #define CONFIG_USBDEV_EP_NUM 8
+    #define CONFIG_USBDEV_FSDEV_PMA_ACCESS 2
 
 - 编译器推荐使用 **AC6**。勾选 **Microlib**，并实现 **printf** ，方便后续查看 log。
 
@@ -106,9 +129,9 @@ USB Device 移植要点
 .. figure:: img/stm32_15.png
 
 USB Host 移植要点
------------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
-前面 7 步与 Device 一样。需要注意，host 驱动只支持带 dma 的 hs port (引脚是 PB14/PB15)，所以 fs port (引脚是 PA11/PA12)不做支持（没有 dma 你玩什么主机）。
+前面 6 步与 Device 一样。需要注意，host 驱动只支持带 dma 的 hs port (引脚是 PB14/PB15)，所以 fs port (引脚是 PA11/PA12)不做支持（没有 dma 你玩什么主机）。
 
 - 添加 CherryUSB 必须要的源码（ **usbh_core.c** 、 **usbh_hub.c** 、 **usb_hc_dwc2.c** 、以及 **osal** 目录下的适配层文件）,以及想要使用的 class 驱动，并且可以将对应的 **usb host.c** 添加方便测试。
 
@@ -119,16 +142,33 @@ USB Host 移植要点
 .. figure:: img/stm32_10.png
 .. figure:: img/stm32_11.png
 
-- 拷贝 **xxx_msp.c** 中的 **HAL_HCD_MspInit** 函数中的内容到 **usb_hc_low_level_init** 函数中，屏蔽 st 生成的 usb 中断函数和 usb 初始化
+- 复制一份 **cherryusb_config_template.h**，放到 `Core/Inc` 目录下，并命名为 `usb_config.h`
+
+- 增加 **usb_glue_st.c** 文件，并在 `usb_config.h` 中实现以下宏：
+
+.. code-block:: C
+
+    // 以下细节如有出入，请对照 stm32xxx.h 文件修改
+    #define CONFIG_USBHOST_PIPE_NUM 12
+
+- 拷贝 **xxx_msp.c** 中的 `HAL_HCD_MspInit` 函数中的内容到 `usb_hc_low_level_init` 函数中，屏蔽 st 生成的 usb 初始化
+- 在中断函数中调用 `USBH_IRQHandler`，并传入 bus 句柄
+- 调用 `usbh_alloc_bus` 创建 bus， `busid` 从 0 开始，不能超过 `CONFIG_USBHOST_MAX_BUS`
+- 调用 `usbh_initialize` 即可
+- 启动线程
 
 .. figure:: img/stm32_18.png
-.. figure:: img/stm32_13.png
 .. figure:: img/stm32_19.png
-
-- 调用 **usbh_initialize** 以及 os 需要的启动线程的函数即可使用
-
 .. figure:: img/stm32_20.png
 
 - 如果使用 **msc**，并且带文件系统，需要自行添加文件系统文件了，对应的 porting 编写参考 **fatfs_usbh.c** 文件。
 
-.. figure:: img/stm32_21.png
+.. figure:: img/stm32_21.png
+
+基于 HPMicro 系列芯片
+---------------------------
+
+仓库参考：https://github.com/CherryUSB/cherryusb_hpmicro
+
+- HPM 系列芯片均 USB 2.0 并且内置高速 PHY，支持主从机
+- USB 的相关应用位于 `samples/cherryusb` ，根据官方环境搭建完成后，即可编译使用。 

packages/third-party/cherryusb/docs/source/quick_start/other_chip.rst

@@ -7,23 +7,27 @@ USB Device 移植要点
 -----------------------
 
 - 拷贝 CherryUSB 源码到工程目录下，并按需添加源文件和头文件路径，其中 `usbd_core.c` 和 `usb_dc_xxx.c` 为必须添加项。而 `usb_dc_xxx.c` 是芯片所对应的 USB IP dcd 部分驱动，如果不知道自己芯片属于那个 USB IP，参考 **port** 目录下的不同 USB IP 的 readme。如果使用的 USB IP 没有支持，只能自己实现了
-- 添加 `USBD_IRQHandler=xxxx` 、 `USB_NUM_BIDIR_ENDPOINTS=x` 以及 `USB_BASE=0xxxxx` 三个 cflag 编译选项，如果没有添加则使用 `usb_dc_xxx.c` 中默认配置
-- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径。
+- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径
+- 在 `usb_config.h` 中添加 `USBD_IRQHandler=xxxx` 、 `CONFIG_USBDEV_EP_NUM=x` 以及 `USBD_BASE=0xxxxx` 三个常规 porting 需要的宏
+
+.. note:: 上述三个宏仅对 fsdev、musb、dwc2 有效，因为这 3 个是通用 IP
+
 - 实现 `usb_dc_low_level_init` 函数（该函数主要负责 USB 时钟、引脚、中断的初始化）。该函数可以放在你想要放的任何参与编译的 c 文件中。如何进行 USB 的时钟、引脚、中断等初始化，请自行根据你使用的芯片原厂提供的源码中进行添加。
 - 描述符的注册、class的注册、接口的注册、端点中断的注册。不会的参考 demo 下的 template
 - 调用 `usbd_initialize` 初始化 usb 硬件
 - 编译使用。各个 class 如何使用，参考 demo 下的 template
 
-.. note:: device 移植要点其实就三个，实现 `usb_dc_low_level_init` ;改 `USBD_IRQHandler=xxxx` 、`USB_BASE=0xxxxx` 、 `USB_NUM_BIDIR_ENDPOINTS=x`;改 `usb_config.h` 中的内容。其中前面说到的3个宏也可以在 `usb_config.h` 添加
-
 USB Host 移植要点
 -----------------------
 
+.. note:: 请注意，当前是最新版本，支持多 port 功能，`USBH_BASE` 和 `USBH_IRQHandler` 的宏不能再使用，并且必须调用 `usbh_alloc_bus`，具体按照以下步骤执行。
+
 - 拷贝 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 没有支持，只能自己实现了
-- 添加 `USBH_IRQHandler=xxxx`  以及 `USB_BASE=0xxxxx` 两个 cflag 编译选项，如果没有添加则使用 `usb_hc_xxx.c` 中默认配置
-- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径。
+- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径
 - 实现 `usb_hc_low_level_init` 函数（该函数主要负责 USB 时钟、引脚、中断的初始化）。该函数可以放在你想要放的任何参与编译的 c 文件中。如何进行 USB 的时钟、引脚、中断等初始化，请自行根据你使用的芯片原厂提供的源码中进行添加。
-- 调用 `usbh_initialize` 初始化 usb 硬件
+- 调用 `usbh_alloc_bus` 创建 bus，填入 USB IP 的基地址， `busid` 从 0 开始，不能超过 `CONFIG_USBHOST_MAX_BUS`
+- 在中断函数中调用 `USBH_IRQHandler`，并传入 bus 句柄, 如果你的 SDK 中中断入口已经存在 `USBH_IRQHandler` ，请更改 USB 协议栈中的名称
+- 调用 `usbh_initialize` 
 - 如果使用的是 GCC ，需要在链接脚本(ld)中添加如下代码：
 
 .. code-block:: C

packages/third-party/cherryusb/docs/source/quick_start/rt-thread/rtthread.rst

@@ -31,11 +31,11 @@
 
 * 最后退出保存即可。
 * 退出以后不急着编译，需要在代码中实现 `usb_dc_low_level_init` 函数。
-* 复制一份 `usb_config.h` 到自己的目录中，并实现以下内容：
+* 复制一份 `usb_config.h` 到自己的目录中，并实现以下内容, 禁止包含 `"rtthread.h"` ：
 
 .. figure:: img/config_file.png
 
-* 使用 `scons --target=mdk` 或者 `scons` 进行编译
+* 使用 `scons --target=mdk5` 或者 `scons` 进行编译
 
 主机配置
 --------------------------
@@ -48,15 +48,36 @@
 
 .. figure:: img/env8.png
 
-* 默认使能除了 hub 之外的所有 class 驱动。
-* 设置 psc 线程的线程栈以及线程优先级。
+* 根据需要勾选 class 驱动
 * 最后退出保存即可。
-* 退出以后不急着编译，需要在代码中实现 `usb_hc_low_level_init` 函数。
-* 复制一份 `usb_config.h` 到自己的目录中，并实现以下内容：
+* 复制一份 `usb_config.h` 到自己的目录中，并实现以下内容, 禁止包含 `"rtthread.h"` ：
 
 .. figure:: img/config_file.png
 
-* 使用 `scons --target=mdk` 或者 `scons` 进行编译
+* 在代码中实现 `usb_hc_low_level_init` 函数，USB 中断中调用 `USBH_IRQHandler`, 
+* 应用中调用 `usbh_alloc_bus` 和 `usbh_initialize`, 
+* 以上内容我们推荐放在 **board.c** 中，如下代码：
+
+.. code-block:: C
+
+        struct usbh_bus *usb_otg_hs_bus;
+
+        void OTG_HS_IRQHandler(void)
+        {
+        extern void USBH_IRQHandler(struct usbh_bus *bus);
+        USBH_IRQHandler(usb_otg_hs_bus);
+        }
+
+        int usbh_init(void)
+        {
+        usb_otg_hs_bus = usbh_alloc_bus(0, USB_OTG_HS_PERIPH_BASE);
+        usbh_initialize(usb_otg_hs_bus);
+        return 0;
+        }
+
+        INIT_APP_EXPORT(usbh_init);
+
+* 使用 `scons --target=mdk5` 或者 `scons` 进行编译，需要使用 AC6 编译器
 * 如果使用的是 GCC ，需要在链接脚本(ld)中添加如下代码：
 
 .. code-block:: C
@@ -71,17 +92,17 @@
 借助 STM32CubeMX 生成 USB 初始化
 ----------------------------------
 
-使用 STM32CubeMX 主要是用来生成 usb 时钟、引脚、中断的配置。我们需要点击如图所示文件，并配置好 USB 的时钟、中断，点击 `Generate Code`。生成的时钟配置在 `main.c` 中的 `SystemClock_Config` 文件，将其拷贝到 `board.c` 中。
+使用 STM32CubeMX 主要是用来生成 usb 时钟、引脚、中断的配置。我们需要点击如图所示文件，并配置好 USB 的时钟、中断，点击 `Generate Code`。
 
 .. figure:: img/stm32cubemx0.png
 .. figure:: img/stm32cubemx1.png
 .. figure:: img/stm32cubemx2.png
 .. figure:: img/stm32cubemx_clk.png
 
-然后将 `stm32xxxx_hal_msp.c` 中的 `HAL_PCD_MspInit` 或者是 `HAL_HCD_MspInit` 中的内容复制到 `usb_dc_low_level_init` 和 `usb_hc_low_level_init` 函数中，举例如下：
+- 将 `main.c` 中的 `SystemClock_Config` 替换掉 `board.c` 中的配置
+
+.. figure:: img/stm32_init2.png
+
+- 将 `stm32xxxx_hal_msp.c` 中的 `HAL_PCD_MspInit` 或者是 `HAL_HCD_MspInit` 中的内容复制到 `usb_dc_low_level_init` 和 `usb_hc_low_level_init` 函数中，举例如下：
 
 .. figure:: img/stm32_init.png
-
-其次将 `main.c` 中的 `SystemClock_Config` 替换掉 `board.c` 中的配置
-
-.. figure:: img/stm32_init2.png