diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..ed14f4de --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,35 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + # You can also specify other tool versions: + # nodejs: "20" + # rust: "1.70" + # golang: "1.20" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/source/conf.py + # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs + # builder: "dirhtml" + # Fail on all warnings to avoid broken references + # fail_on_warning: true + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index faa3dac6..5c7f9db4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -53,10 +53,7 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 :maxdepth: 1 :caption: 快速上手 - quick_start/bl702 - quick_start/stm32 - quick_start/hpm - quick_start/es32 + quick_start/index quick_start/rt-thread/rtthread quick_start/other_chip 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/stm32.rst b/docs/source/quick_start/index.rst similarity index 74% rename from docs/source/quick_start/stm32.rst rename to docs/source/quick_start/index.rst index 5f1b80c3..b0223c6b 100644 --- a/docs/source/quick_start/stm32.rst +++ b/docs/source/quick_start/index.rst @@ -1,13 +1,41 @@ -基于 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 主从使用 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 @@ -38,22 +66,8 @@ .. 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使用) @@ -106,7 +120,7 @@ USB Device 移植要点 .. figure:: img/stm32_15.png USB Host 移植要点 ------------------------ +^^^^^^^^^^^^^^^^^^^^^^ 前面 7 步与 Device 一样。需要注意，host 驱动只支持带 dma 的 hs port (引脚是 PB14/PB15)，所以 fs port (引脚是 PA11/PA12)不做支持（没有 dma 你玩什么主机）。 @@ -131,4 +145,12 @@ USB Host 移植要点 - 如果使用 **msc**，并且带文件系统，需要自行添加文件系统文件了，对应的 porting 编写参考 **fatfs_usbh.c** 文件。 -.. figure:: img/stm32_21.png \ No newline at end of file +.. figure:: img/stm32_21.png + +基于 HPMicro 系列芯片 +--------------------------- + +仓库参考：https://github.com/CherryUSB/cherryusb_hpmicro + +- HPM 系列芯片均 USB 2.0 并且内置高速 PHY，支持主从机 +- USB 的相关应用位于 `samples/cherryusb` ，根据官方环境搭建完成后，即可编译使用。