diff --git a/docs/source/quick_start/es32.rst b/docs/source/quick_start/es32.rst index 5c63290d..dd1c0ab6 100644 --- a/docs/source/quick_start/es32.rst +++ b/docs/source/quick_start/es32.rst @@ -23,7 +23,7 @@ USB Device 移植要点 - 准备好可以进行调试打印的工程,并且实现 `printf`、 `malloc` 、 `free` 函数(也可以直接勾选 Use microlib 来使用)。 - 拷贝 CherryUSB 源码到工程里 - 添加 CherryUSB 源码和头文件路径,其中 `usbd_core.c` 和 `usb_dc_musb.c` 为必须添加项。 -- 拷贝 `usb_config.h` 文件到自己工程目录下,并添加相应的目录头文件路径。所以根目录下的文件仅作为参考,不要添加根目录下的头文件。 +- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下,命名为 `usb_config.h`,并添加相应的目录头文件路径。所以根目录下的文件仅作为参考,不要添加根目录下的头文件。 .. figure:: img/es322.png .. figure:: img/es323.png @@ -57,7 +57,7 @@ USB Host 移植要点 - 准备好可以进行调试打印的带 FreeRTOS 或者 RT-Thread 的工程,并且实现 `printf`、 `malloc` 、 `free` 函数(也可以直接勾选 Use microlib 来使用)。 - 拷贝 CherryUSB 源码到工程里 - 添加 CherryUSB 源码和头文件路径,其中 `usbh_core.c` 和 `usb_hc_musb.c` 、 osal 下的文件为必须添加项,根据不同的 os 添加对应的文件。 -- 拷贝 `usb_config.h` 文件到自己工程目录下,并添加相应的目录头文件路径。所以根目录下的文件仅作为参考,不要添加根目录下的头文件。 +- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下,命名为 `usb_config.h` ,并添加相应的目录头文件路径。所以根目录下的文件仅作为参考,不要添加根目录下的头文件。 .. figure:: img/es324.png .. figure:: img/es325.png diff --git a/docs/source/quick_start/img/stm32_16.png b/docs/source/quick_start/img/stm32_16.png index 4573f911..70f2e63c 100644 Binary files a/docs/source/quick_start/img/stm32_16.png and b/docs/source/quick_start/img/stm32_16.png differ diff --git a/docs/source/quick_start/img/stm32_17.png b/docs/source/quick_start/img/stm32_17.png deleted file mode 100644 index 04ff0010..00000000 Binary files a/docs/source/quick_start/img/stm32_17.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_17_1.png b/docs/source/quick_start/img/stm32_17_1.png deleted file mode 100644 index 1144cbda..00000000 Binary files a/docs/source/quick_start/img/stm32_17_1.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_17_2.png b/docs/source/quick_start/img/stm32_17_2.png deleted file mode 100644 index 605458e0..00000000 Binary files a/docs/source/quick_start/img/stm32_17_2.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_17_3.png b/docs/source/quick_start/img/stm32_17_3.png deleted file mode 100644 index 219e9f78..00000000 Binary files a/docs/source/quick_start/img/stm32_17_3.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_17_4.png b/docs/source/quick_start/img/stm32_17_4.png deleted file mode 100644 index c9d03c74..00000000 Binary files a/docs/source/quick_start/img/stm32_17_4.png and /dev/null differ diff --git a/docs/source/quick_start/other_chip.rst b/docs/source/quick_start/other_chip.rst index c7433cc9..e76ce36d 100644 --- a/docs/source/quick_start/other_chip.rst +++ b/docs/source/quick_start/other_chip.rst @@ -8,13 +8,12 @@ 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` 中默认配置 -- 拷贝 `usb_config.h` 文件到自己工程目录下,并添加相应的目录头文件路径。所以根目录下的文件仅作为参考,不要添加根目录下的头文件路径 +- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下,命名为 `usb_config.h`,并添加相应的目录头文件路径。 - 实现 `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 移植要点 @@ -22,7 +21,7 @@ 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 没有支持,只能自己实现了 - 添加 `USBH_IRQHandler=xxxx` 以及 `USB_BASE=0xxxxx` 两个 cflag 编译选项,如果没有添加则使用 `usb_hc_xxx.c` 中默认配置 -- 拷贝 `usb_config.h` 文件到自己工程目录下,并添加相应的目录头文件路径。所以根目录下的文件仅作为参考,不要添加根目录下的头文件路径 +- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下,命名为 `usb_config.h`,并添加相应的目录头文件路径。 - 实现 `usb_hc_low_level_init` 函数(该函数主要负责 USB 时钟、引脚、中断的初始化)。该函数可以放在你想要放的任何参与编译的 c 文件中。如何进行 USB 的时钟、引脚、中断等初始化,请自行根据你使用的芯片原厂提供的源码中进行添加。 - 调用 `usbh_initialize` 初始化 usb 硬件 - 如果使用的是 GCC ,需要在链接脚本(ld)中添加如下代码: @@ -49,8 +48,48 @@ USB Host 移植要点 - 编译使用。各个 class 如何使用,参考 demo 下的 `usb_host.c` 文件 -.. note:: device 移植要点其实就三个,实现 `usb_hc_low_level_init` ; 改 `USBH_IRQHandler=xxxx` 、`USB_BASE=0xxxxx` ; 改 `usb_config.h` 中的内容。其中前面说到的2个宏也可以在 `usb_config.h` 添加 +.. caution:: 如果主从 ip 共用一个中断,设置 `USBD_IRQHandler=USBD_IRQHandler` 、 `USBH_IRQHandler=USBH_IRQHandler` ,然后由真正的中断函数根据主从模式调用这两个函数。 -.. note:: 使用 host 时,推荐添加除了 hub 以外的所有适配的 class 驱动,达到自动加载驱动的目的。当然,如果不用,那就不添加。 +带 cache 功能的芯片使用注意 +------------------------------- -.. caution:: 如果主从 ip 共用一个中断,设置 `USBD_IRQHandler=USBD_IRQHandler` 、 `USBH_IRQHandler=USBH_IRQHandler` ,然后由真正的中断函数根据主从模式调用这两个函数。 \ No newline at end of file +协议栈以及 port 中不会对 cache 区域的 ram 进行 clean 或者 invalid,所以需要使用一块非 cache 区域的 ram 来维护。 `USB_NOCACHE_RAM_SECTION` 宏表示将变量指定到非 cache ram上, +因此,用户需要在对应的链接脚本中添加 no cache ram 的 section。默认 `USB_NOCACHE_RAM_SECTION` 定义为 `__attribute__((section(".noncacheable")))`。 + +GCC: + +.. code-block:: C + + // 放在 no cache ram 的 region 中 + .no_cache_ram_region : AT (__no_cache_ram_addr) + { + . = ALIGN(4); + *(.noncacheable) + . = ALIGN(4); + } > no_cache_ram + +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) + } + } + +ICF: + +.. code-block:: C + + define region NONCACHEABLE_RAM = [from 0x1140000 size 256K]; + place in NONCACHEABLE_RAM { section .noncacheable, section .noncacheable.init, section .noncacheable.bss }; // Noncacheable diff --git a/docs/source/quick_start/stm32.rst b/docs/source/quick_start/stm32.rst index fe8924fc..754894b4 100644 --- a/docs/source/quick_start/stm32.rst +++ b/docs/source/quick_start/stm32.rst @@ -8,6 +8,31 @@ - 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) + } + } + 工程样例试用 ----------------------- @@ -52,7 +77,7 @@ USB Device 移植要点 .. figure:: img/stm32_7.png -- 复制一份 **usb_config.h**,这里放到 `Core/Inc` 目录下 +- 复制一份 **cherryusb_config_template.h**,放到 `Core/Inc` 目录下,并命名为 `usb_config.h` .. figure:: img/stm32_8.png @@ -79,26 +104,10 @@ USB Host 移植要点 前面 7 步与 Device 一样。需要注意,host 驱动只支持带 dma 的 hs port,所以 fs port 不做支持(没有 dma 你玩什么主机)。 -- 添加 CherryUSB 必须要的源码( **usbh_core.c** 、 **usb_hc_dwc2.c** 、以及 **osal** 目录下的适配层文件),以及想要使用的 class 驱动(推荐添加除了 hub 之外的所有的 class),可以将对应的 usb host template 添加方便测试。 +- 添加 CherryUSB 必须要的源码( **usbh_core.c** 、 **usbh_hub.c** 、 **usb_hc_dwc2.c** 、以及 **osal** 目录下的适配层文件),以及想要使用的 class 驱动,并且可以将对应的 **usb host.c** 添加方便测试。 .. figure:: img/stm32_16.png -- 编译选项中需要添加 `CONFIG_USBHOST_HIGH_WORKQ`,作用是在线程中复位 port。 - -.. figure:: img/stm32_17.png - -- 如果使用 STM32H7 或者 F7 ,需要添加 `STM32H7` 或者 `STM32F7` 编译选项 -- 如果使用的是 F7/H7 这种带 cache功能的,由于 dma 原因,所以需要刷 cache,编译选项中需要添加 `CONFIG_USB_DCACHE_ENABLE`,并实现刷 cache的两个函数。当然,可以不开 dcahe功能,就不需要添加编译选项。 -并且需要搭配 MPU 使用,如果是新手,对 cache不了解,推荐关闭 cache功能。默认 cache 使用 Write Back 属性。 - -.. figure:: img/stm32_17_1.png -.. figure:: img/stm32_17_2.png -.. figure:: img/stm32_17_3.png - -.. note:: STM32 h7/f7 usb dma 访问的 ram 只能是从 0x24000000 开始的地址,所以,推荐关闭 0x20000000 开始的地址。 - -.. figure:: img/stm32_17_4.png - - 编译器推荐使用 **AC6**。勾选 **Microlib**,并实现 **printf** ,方便后续查看 log。 .. figure:: img/stm32_10.png .. figure:: img/stm32_11.png