From cf4dfde49d171a44c31c53ff7cf57a8d3d16465c Mon Sep 17 00:00:00 2001 From: sakumisu <1203593632@qq.com> Date: Fri, 13 Oct 2023 20:17:59 +0800 Subject: update quick start, add readthedocs yaml --- docs/source/quick_start/bl702.rst | 6 -- docs/source/quick_start/es32.rst | 84 ------------------ docs/source/quick_start/hpm.rst | 6 -- docs/source/quick_start/img/es322.png | Bin 3458 -> 0 bytes docs/source/quick_start/img/es323.png | Bin 6704 -> 0 bytes docs/source/quick_start/img/es324.png | Bin 6754 -> 0 bytes docs/source/quick_start/img/es325.png | Bin 6557 -> 0 bytes docs/source/quick_start/index.rst | 156 ++++++++++++++++++++++++++++++++++ docs/source/quick_start/stm32.rst | 134 ----------------------------- 9 files changed, 156 insertions(+), 230 deletions(-) delete mode 100644 docs/source/quick_start/bl702.rst delete mode 100644 docs/source/quick_start/es32.rst delete mode 100644 docs/source/quick_start/hpm.rst delete mode 100644 docs/source/quick_start/img/es322.png delete mode 100644 docs/source/quick_start/img/es323.png delete mode 100644 docs/source/quick_start/img/es324.png delete mode 100644 docs/source/quick_start/img/es325.png create mode 100644 docs/source/quick_start/index.rst delete mode 100644 docs/source/quick_start/stm32.rst (limited to 'docs/source/quick_start') diff --git a/docs/source/quick_start/bl702.rst b/docs/source/quick_start/bl702.rst deleted file mode 100644 index 1ae1f8fa..00000000 --- a/docs/source/quick_start/bl702.rst +++ /dev/null @@ -1,6 +0,0 @@ -基于 BL 系列开发指南 -========================= - -BL 系列 USB 的开发主要使用 bl_mcu_sdk，参考 `bl_mcu_sdk `_。 - -USB 的相关应用位于 `examples/usbdev` 和 `examples/usbhost` 目录下，环境搭建完成后，即可编译使用。 \ No newline at end of file diff --git a/docs/source/quick_start/es32.rst b/docs/source/quick_start/es32.rst deleted file mode 100644 index dd1c0ab6..00000000 --- a/docs/source/quick_start/es32.rst +++ /dev/null @@ -1,84 +0,0 @@ -基于 ES32F369 开发指南 -========================= - -ES32F3xx 系列单片机中 USB 外设使用标准的 musb ip，并且拥有 usb device 和 usb host 功能。本章主要介绍如何在东软载波的 ES32F369x 开发板中使用 CherryUSB。 - -在使用之前需要从 essemi 官网下载 `keil 芯片支持包 `_ 并安装， - - -工程样例试用 ------------------------ - -在 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` 中，如果不想要，可以直接删除。 -- 正常使用。 \ No newline at end of file diff --git a/docs/source/quick_start/hpm.rst b/docs/source/quick_start/hpm.rst deleted file mode 100644 index 21c41278..00000000 --- a/docs/source/quick_start/hpm.rst +++ /dev/null @@ -1,6 +0,0 @@ -基于 HPM 系列开发指南 -========================= - -HPM 系列 USB 的开发主要使用 hpm_sdk ，参考 `hpm sdk `_。 - -USB 的相关应用位于 `samples/cherryusb` 目录下，环境搭建完成后，即可编译使用。 \ No newline at end of file diff --git a/docs/source/quick_start/img/es322.png b/docs/source/quick_start/img/es322.png deleted file mode 100644 index 09095b52..00000000 Binary files a/docs/source/quick_start/img/es322.png and /dev/null differ diff --git a/docs/source/quick_start/img/es323.png b/docs/source/quick_start/img/es323.png deleted file mode 100644 index 2712dc50..00000000 Binary files a/docs/source/quick_start/img/es323.png and /dev/null differ diff --git a/docs/source/quick_start/img/es324.png b/docs/source/quick_start/img/es324.png deleted file mode 100644 index 59cfcaec..00000000 Binary files a/docs/source/quick_start/img/es324.png and /dev/null differ diff --git a/docs/source/quick_start/img/es325.png b/docs/source/quick_start/img/es325.png deleted file mode 100644 index b3fc9ed8..00000000 Binary files a/docs/source/quick_start/img/es325.png and /dev/null differ diff --git a/docs/source/quick_start/index.rst b/docs/source/quick_start/index.rst new file mode 100644 index 00000000..b0223c6b --- /dev/null +++ b/docs/source/quick_start/index.rst @@ -0,0 +1,156 @@ +基于现有 demo 快速验证 +========================= + +在学习 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 主从使用 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 覆盖。 + +涵盖 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 区别 + +如果是 STM32F7/STM32H7 这种带 cache 功能，需要将 usb 使用到的 ram 定位到 no cache ram 区域。举例如下 + +.. code-block:: C + + cpu_mpu_config(0, MPU_Normal_NonCache, 0x24070000, MPU_REGION_SIZE_64KB); + +对应 keil 中的 sct 脚本修改： + +.. code-block:: C + + LR_IROM1 0x08000000 0x00200000 { ; load region size_region + ER_IROM1 0x08000000 0x00200000 { ; load address = execution address + *.o (RESET, +First) + *(InRoot$$Sections) + .ANY (+RO) + .ANY (+XO) + } + RW_IRAM2 0x24000000 0x00070000 { ; RW data + .ANY (+RW +ZI) + } + USB_NOCACHERAM 0x24070000 0x00010000 { ; RW data + *(.noncacheable) + } + } + + +.. caution :: 如果使用 STM32F7 或者 STM32H7, 请在 CFLAG 中添加 STM32F7 或者 STM32H7 宏定义，否则无法枚举 + +.. figure:: img/keil.png + +USB Device 移植要点 +^^^^^^^^^^^^^^^^^^^^^^ + +- 使用 **stm32cubemx** 创建工程，配置基本的 RCC、UART (作为log使用) + +.. figure:: img/stm32_1.png +.. figure:: img/stm32_2.png + +- 如果使用 fsdev ip，勾选 **USB** 。如果使用 dwc2 ip，勾选 **USB_OTG_FS** 或者勾选 **USB_OTG_HS**。开启 USB 中断，其他配置对我们没用，代码中不会使用任何 st 的 usb 库。 + +.. figure:: img/stm32_3_1.png +.. figure:: img/stm32_3.png + +- 配置 usb clock 为 48M + +.. figure:: img/stm32_4_1.png +.. figure:: img/stm32_4.png + +- 选择好工程，这里我们选择 keil，设置好 stack 和 heap，如果使用 msc 可以推荐设置大点，然后点击 **Generate Code**。 + +.. figure:: img/stm32_5.png + +- 添加 CherryUSB 必须要的源码（ **usbd_core.c** 、 **usb_dc_dwc2.c** 或者是 **usb_dc_fsdev.c** ）,以及想要使用的 class 驱动，可以将对应的 class template 添加方便测试。 + +.. figure:: img/stm32_6.png + +- 头文件该加的加 + +.. figure:: img/stm32_7.png + +- 复制一份 **cherryusb_config_template.h**，放到 `Core/Inc` 目录下，并命名为 `usb_config.h` + +.. figure:: img/stm32_8.png + +- 如果使用 dwc2 ip，编译选项中需要添加 `CONFIG_USB_DWC2_PORT=xxx`，使用 PA11/PA12 则 **xxx=FS_PORT**，使用 PB14/PB15 则 **xxx=HS_PORT** + +.. figure:: img/stm32_9.png + +- 编译器推荐使用 **AC6**。勾选 **Microlib**，并实现 **printf** ，方便后续查看 log。 + +.. figure:: img/stm32_10.png +.. figure:: img/stm32_11.png + +- 拷贝 **xxx_msp.c** 中的 **HAL_PCD_MspInit** 函数中的内容到 **usb_dc_low_level_init** 函数中，屏蔽 st 生成的 usb 中断函数和 usb 初始化 + +.. figure:: img/stm32_12.png +.. figure:: img/stm32_13.png +.. figure:: img/stm32_14.png + +- 调用 template 的内容初始化，就可以使用了 + +.. figure:: img/stm32_15.png + +USB Host 移植要点 +^^^^^^^^^^^^^^^^^^^^^^ + +前面 7 步与 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** 添加方便测试。 + +.. figure:: img/stm32_16.png + +- 编译器推荐使用 **AC6**。勾选 **Microlib**，并实现 **printf** ，方便后续查看 log。 + +.. figure:: img/stm32_10.png +.. figure:: img/stm32_11.png + +- 拷贝 **xxx_msp.c** 中的 **HAL_HCD_MspInit** 函数中的内容到 **usb_hc_low_level_init** 函数中，屏蔽 st 生成的 usb 中断函数和 usb 初始化 + +.. 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 + +基于 HPMicro 系列芯片 +--------------------------- + +仓库参考：https://github.com/CherryUSB/cherryusb_hpmicro + +- HPM 系列芯片均 USB 2.0 并且内置高速 PHY，支持主从机 +- USB 的相关应用位于 `samples/cherryusb` ，根据官方环境搭建完成后，即可编译使用。 diff --git a/docs/source/quick_start/stm32.rst b/docs/source/quick_start/stm32.rst deleted file mode 100644 index 5f1b80c3..00000000 --- a/docs/source/quick_start/stm32.rst +++ /dev/null @@ -1,134 +0,0 @@ -基于 STM32F1/F4/H7 开发指南 -============================= - -本节是基于 STM32 三个系列芯片的使用，涵盖 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 区别 - - -如果是 STM32F7/STM32H7 这种带 cache 功能，需要将 usb 使用到的 ram 定位到 no cache ram 区域。举例如下 - -.. code-block:: C - - cpu_mpu_config(0, MPU_Normal_NonCache, 0x24070000, MPU_REGION_SIZE_64KB); - -对应 keil 中的 sct 脚本修改： - -.. code-block:: C - - LR_IROM1 0x08000000 0x00200000 { ; load region size_region - ER_IROM1 0x08000000 0x00200000 { ; load address = execution address - *.o (RESET, +First) - *(InRoot$$Sections) - .ANY (+RO) - .ANY (+XO) - } - RW_IRAM2 0x24000000 0x00070000 { ; RW data - .ANY (+RW +ZI) - } - USB_NOCACHERAM 0x24070000 0x00010000 { ; RW data - *(.noncacheable) - } - } - - -.. 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使用) - -.. figure:: img/stm32_1.png -.. figure:: img/stm32_2.png - -- 如果使用 fsdev ip，勾选 **USB** 。如果使用 dwc2 ip，勾选 **USB_OTG_FS** 或者勾选 **USB_OTG_HS**。开启 USB 中断，其他配置对我们没用，代码中不会使用任何 st 的 usb 库。 - -.. figure:: img/stm32_3_1.png -.. figure:: img/stm32_3.png - -- 配置 usb clock 为 48M - -.. figure:: img/stm32_4_1.png -.. figure:: img/stm32_4.png - -- 选择好工程，这里我们选择 keil，设置好 stack 和 heap，如果使用 msc 可以推荐设置大点，然后点击 **Generate Code**。 - -.. figure:: img/stm32_5.png - -- 添加 CherryUSB 必须要的源码（ **usbd_core.c** 、 **usb_dc_dwc2.c** 或者是 **usb_dc_fsdev.c** ）,以及想要使用的 class 驱动，可以将对应的 class template 添加方便测试。 - -.. figure:: img/stm32_6.png - -- 头文件该加的加 - -.. figure:: img/stm32_7.png - -- 复制一份 **cherryusb_config_template.h**，放到 `Core/Inc` 目录下，并命名为 `usb_config.h` - -.. figure:: img/stm32_8.png - -- 如果使用 dwc2 ip，编译选项中需要添加 `CONFIG_USB_DWC2_PORT=xxx`，使用 PA11/PA12 则 **xxx=FS_PORT**，使用 PB14/PB15 则 **xxx=HS_PORT** - -.. figure:: img/stm32_9.png - -- 编译器推荐使用 **AC6**。勾选 **Microlib**，并实现 **printf** ，方便后续查看 log。 - -.. figure:: img/stm32_10.png -.. figure:: img/stm32_11.png - -- 拷贝 **xxx_msp.c** 中的 **HAL_PCD_MspInit** 函数中的内容到 **usb_dc_low_level_init** 函数中，屏蔽 st 生成的 usb 中断函数和 usb 初始化 - -.. figure:: img/stm32_12.png -.. figure:: img/stm32_13.png -.. figure:: img/stm32_14.png - -- 调用 template 的内容初始化，就可以使用了 - -.. figure:: img/stm32_15.png - -USB Host 移植要点 ------------------------ - -前面 7 步与 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** 添加方便测试。 - -.. figure:: img/stm32_16.png - -- 编译器推荐使用 **AC6**。勾选 **Microlib**，并实现 **printf** ，方便后续查看 log。 - -.. figure:: img/stm32_10.png -.. figure:: img/stm32_11.png - -- 拷贝 **xxx_msp.c** 中的 **HAL_HCD_MspInit** 函数中的内容到 **usb_hc_low_level_init** 函数中，屏蔽 st 生成的 usb 中断函数和 usb 初始化 - -.. 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 \ No newline at end of file -- cgit v1.3.1