diff --git a/docs/source/index.rst b/docs/source/index.rst index 185a7f6c..cd82bd7c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -56,6 +56,7 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 quick_start/index quick_start/rt-thread/rtthread quick_start/other_chip + q&a .. toctree:: :maxdepth: 1 diff --git a/docs/source/porting_usbip.rst b/docs/source/porting_usbip.rst index 985a607c..4cbb8df2 100644 --- a/docs/source/porting_usbip.rst +++ b/docs/source/porting_usbip.rst @@ -6,16 +6,16 @@ USB IP 勘误 FSDEV -------------------------- -FSDEV 仅支持从机。这个 ip 不同厂家基本都是基于标准的 usb 寄存器，所以用户使用时，仅需要修改 `USBD_IRQHandler` 、 `USB_BASE` 、 `USB_NUM_BIDIR_ENDPOINTS` 即可。有些芯片可能还需要配置 `PMA_ACCESS` 的值，默认为2。下表为具体芯片相关宏的修改值： +FSDEV 仅支持从机。这个 ip 不同厂家基本都是基于标准的 usb 寄存器，有些芯片可能还需要配置 `PMA_ACCESS` 的值，默认为2。下表为具体芯片相关宏的修改值： .. list-table:: :widths: 30 20 30 30 30 :header-rows: 1 * - 芯片 - - USBD_IRQHandler - - USB_BASE - - USB_NUM_BIDIR_ENDPOINTS + - 中断名 + - 寄存器地址 + - CONFIG_USBDEV_EP_NUM - PMA_ACCESS * - STM32F0 - USB_IRQHandler @@ -67,7 +67,7 @@ fsdev 需要外置 dp 上拉才能使用，有些芯片可能是接上拉电阻 MUSB -------------------------- -MUSB IP 支持主从，并且由 **mentor** 定义了一套标准的寄存器偏移，所以如果是走的标准，则从机仅需要修改 `USBD_IRQHandler` 、 `USB_BASE` 、 `USB_NUM_BIDIR_ENDPOINTS` ，主机仅需要修改 `USBH_IRQHandler` 、 `USB_BASE` 以及 `CONIFG_USB_MUSB_EP_NUM` 即可。如果非标准，则需要实现以下宏的偏移，以标准为例： +MUSB IP 支持主从，并且由 **mentor** 定义了一套标准的寄存器偏移，如果非标准，则需要实现以下宏的偏移，以标准为例： .. code-block:: C @@ -127,9 +127,9 @@ MUSB IP 支持主从，并且由 **mentor** 定义了一套标准的寄存器偏 :header-rows: 1 * - 芯片 - - USBD_IRQHandler - - USB_BASE - - USB_NUM_BIDIR_ENDPOINTS + - 中断名 + - 寄存器地址 + - CONFIG_USBDEV_EP_NUM * - ES32F3xx - USB_INT_Handler - 0x40086400 @@ -150,8 +150,8 @@ MUSB IP 支持主从，并且由 **mentor** 定义了一套标准的寄存器偏 :header-rows: 1 * - 芯片 - - USBH_IRQHandler - - USB_BASE + - 中断名 + - 寄存器地址 - CONIFG_USB_MUSB_EP_NUM * - ES32F3xx - USB_INT_Handler @@ -169,7 +169,7 @@ MUSB IP 支持主从，并且由 **mentor** 定义了一套标准的寄存器偏 DWC2 -------------------------- -DWC2 IP 支持主从，并且由 **synopsys** 定义了一套标准的寄存器偏移。大部分厂家都使用标准的寄存器偏移(除了 GCCFG(GGPIO)寄存器)，所以如果是从机仅需要修改 `USBD_IRQHandler` 、 `USB_BASE` 、 `USB_NUM_BIDIR_ENDPOINTS` ，主机仅需要修改 `USBH_IRQHandler` 、 `USB_BASE` 即可。 +DWC2 IP 支持主从，并且由 **synopsys** 定义了一套标准的寄存器偏移。大部分厂家都使用标准的寄存器偏移(除了 GCCFG(GGPIO)寄存器)，所以如果是从机仅需要修改 `中断名` 、 `USB_BASE` 、 `CONFIG_USBDEV_EP_NUM` ，主机仅需要修改 `中断名` 、 `USB_BASE` 即可。 .. note:: GCCFG(GGPIO) 根据不同的厂家设置不同，会影响 usb 枚举，需要根据厂家提供的手册进行配置,并实现 usbd_get_dwc2_gccfg_conf 和 usbh_get_dwc2_gccfg_conf 函数，填充相应需要使能的bit @@ -182,9 +182,9 @@ DWC2 IP 支持主从，并且由 **synopsys** 定义了一套标准的寄存器 :header-rows: 1 * - 芯片 - - USBH_IRQHandler - - USB_BASE - - USB_NUM_BIDIR_ENDPOINTS + - 中断名 + - 寄存器地址 + - CONFIG_USBDEV_EP_NUM * - STM32 非 H7 - OTG_FS_IRQHandler/OTG_HS_IRQHandler - 0x50000000UL/0x40040000UL @@ -201,9 +201,9 @@ DWC2 IP 支持主从，并且由 **synopsys** 定义了一套标准的寄存器 :header-rows: 1 * - 芯片 - - USBH_IRQHandler - - USB_BASE - - CONFIG_USB_DWC2_PIPE_NUM + - 中断名 + - 寄存器地址 + - CONFIG_USBHOST_PIPE_NUM * - STM32 全系列 - OTG_HS_IRQHandler - 0x40040000UL @@ -216,17 +216,17 @@ EHCI 是 intel 制定的标准主机控制器接口，任何厂家都必须实 .. code-block:: C - //Host Controller Operational Register BASE 距离基地址的偏移 - #define CONFIG_USB_EHCI_HCOR_OFFSET (0x14) - //是否打印 ehci 配置信息 - #define CONFIG_USB_EHCI_INFO_ENABLE + #define CONFIG_USB_EHCI_HCCR_OFFSET (0x0) + #define CONFIG_USB_EHCI_FRAME_LIST_SIZE 1024 + #define CONFIG_USB_EHCI_QH_NUM CONFIG_USBHOST_PIPE_NUM + #define CONFIG_USB_EHCI_QTD_NUM 3 + #define CONFIG_USB_EHCI_ITD_NUM 20 //是否关闭保留寄存器的占位，默认保留 9 个双字的占位 #define CONFIG_USB_EHCI_HCOR_RESERVED_DISABLE //是否使能 configflag 寄存器中的 bit0 #define CONFIG_USB_EHCI_CONFIGFLAG - //是否使能 port power bit - #define CONFIG_USB_EHCI_PORT_POWER - //是否查看 ehci 配置信息 - #define CONFIG_USB_EHCI_PRINT_HW_PARAM + #define CONFIG_USB_EHCI_ISO + // 不带 tt的 IP 一般使用OHCI + #define CONFIG_USB_EHCI_WITH_OHCI 同时由于 EHCI 只是主机控制器并且只支持高速，一般配合一个 otg 控制器和一个低速全速兼容控制单元，而速度的获取一般是在 otg 寄存器中，所以需要用户实现 `usbh_get_port_speed` 函数。 \ No newline at end of file diff --git a/docs/source/q&a.rst b/docs/source/q&a.rst new file mode 100644 index 00000000..d3bc84af --- /dev/null +++ b/docs/source/q&a.rst @@ -0,0 +1,81 @@ +Q & A +============================== + +移植提问模板 +---------------- + +- 使用的板子，引脚，USB IP +- USB 中断，时钟，引脚，寄存器地址是否正确，截图 +- 是否能进 USB 中断 +- 芯片是否带有 cache功能，是否做了 no cache 处理，截图 +- 硬件是否正常，是否使用杜邦线连接，如果正常，请说明正常原因 +- 打开 CONFGI_USBDEV_SETUP_LOG_PRINT，并提供 log +- 是否流片并销售 + +其余问题提问模板 +------------------ + +具体说明现象，复现方式，并提供完整 log + + +CherryUSB 版本推荐 +--------------------- + +如果没有特别情况，请使用最新版本.详细版本更新说明请参考 https://github.com/cherry-embedded/CherryUSB/releases。 + +- <= v0.10.2 初代版本 + +用于定基本的框架，仅支持单 USB IP, 并且无法动态使用硬件 pipe. +使用 XHCI 需要切到这个版本，高版本后续重构. 部分 IP 只能使用此版本，后续版本删除不再使用 + +- v1.0.0 过度版本 + +支持动态使用硬件 pipe，不再固定 + +- v1.1.0 过度版本 + +主从机支持多 USB IP 且要相同 IP, 主机增加 bluetooth, chh340, ftdi, cp210x, asix 驱动 + +- v1.2.0 + +主机增加 rtl8152，cdc ncm 主机驱动，增加 esp ，aic 驱动，DWC2 优化代码阅读，并增加一些配置宏给用户 + +- v1.3.0 + +增加一些 宏的 check; +主机增加 pl2303 驱动，支持多个 vid，pid，支持 user_data 给用户使用，优化网络性能; +从机增加一些获取端点信息的 api，并统一 ep0 buffer 的使用，支持多速度描述符自动选择功能 + +CherryUSB 性能能到多少 +---------------------------------------------------------------- + +可以达到硬件极限性能，比如 HPM 系列，从机可以到 42MB/s, 主机 44MB/s，全速芯片一般 800 ~ 1000KB/s，当然需要硬件理论支持到这速度，CherryUSB 就支持到这速度 + +ST IP 命名问题 +------------------ + +ST 命名为 USB_OTG_FS, USB_OTG_HS，并不是说明本身是高速或者全速，只是代表可以支持到高速，但是本身都是全速，需要外挂高速phy。因此，提问禁止说这两个词，请使用 USB0(PA11/PA12),USB1(PB14/PB15) 代替。其余国产厂家同理。 + +dwc2 has less endpoints than config, please check +--------------------------------------------------------------- + +该 IP 硬件上没有这么多端点，请修改 `CONFIG_USBDEV_EP_NUM`.如果是 GD 芯片，由于 GD 的 dwc2 读出来的硬件配置都是0，所以需要自行 check 并删除 while1 + +Ep addr XXX overflow +------------------------------ + +该 IP 硬件上没有这么多端点, 请更换 IP or 减少端点使用 + +This dwc2 version does not support dma mode, so stop working +---------------------------------------------------------------- + +该 DWC2 版本不支持 dma 模式，禁止使用. 如果是 GD 芯片，由于 GD 的 dwc2 读出来的硬件配置都是0，所以需要自行 check 并删除 while1 + +__has_include 报错 +------------------------------------------------------------------ +如果报错，需要编译器支持 c99 语法，如果是 keil，请用 ac6 编译器 + +CONFIG_USB_HS 何时使用 +---------------------------------------------------------------- + +当你的芯片硬件支持高速，并想初始化成高速模式时开启，相关 IP 会根据该宏配置内部或者外部 高速 PHY。 diff --git a/docs/source/quick_start/index.rst b/docs/source/quick_start/index.rst index 181bfa66..392315aa 100644 --- a/docs/source/quick_start/index.rst +++ b/docs/source/quick_start/index.rst @@ -11,7 +11,7 @@ - BL702 是一个 USB2.0 全速芯片，共 8 个端点（包含端点0）。仅支持从机。 - BL616/BL808 是一个 USB2.0 并且内置高速 PHY 芯片，共 5个端点（包含端点0）。支持主从机。 -- USB 的相关应用位于 `examples/usbdev` 和 `examples/usbhost` 目录下，根据官方环境搭建完成后，即可编译使用。 +- USB 的相关应用位于 `examples/usbdev` 和 `examples/usbhost` 目录下，根据官方环境搭建完成后，即可编译使用。 基于 ST 系列芯片 @@ -22,8 +22,8 @@ 默认提供以下 demo 工程： - F103 使用 fsdev ip -- F429 主从使用 USB_OTG_HS, 引脚 pb14/pb15, 并且都使用 dma 模式 -- H7 设备使用 USB_OTG_FS, 引脚 pa11/pa12，主机使用 USB_OTG_HS ,引脚 pb14/pb15，并且需要做 nocache 处理 +- F429 主从使用 USB1, 引脚 pb14/pb15, 并且都使用 dma 模式 +- H7 设备使用 USB0, 引脚 pa11/pa12，主机使用 USB_OTG_HS ,引脚 pb14/pb15，并且需要做 nocache 处理 默认删除 Drivers ，所以需要使用 stm32cubemx 生成一下 Drivers 目录下的文件，demo 底下提供了 **stm32xxx.ioc** 文件，双击打开，点击 **Generate Code** 即可。 @@ -32,7 +32,7 @@ 涵盖 F1/F4/H7，其余芯片基本类似，不再赘述，具体区别有： - usb ip 区别：F1使用 fsdev，F4/H7使用 dwc2 -- dwc2 ip 区别： USB_OTG_FS (引脚是 PA11/PA12) 和 USB_OTG_HS (引脚是 PB14/PB15), 其中 USB_OTG_HS 默认全速，可以接外部PHY 形成高速主机，并且带 dma 功能 +- dwc2 ip 区别： USB0 (引脚是 PA11/PA12) 和 USB1 (引脚是 PB14/PB15), 其中 USB1 默认全速，可以接外部PHY 形成高速主机，并且带 dma 功能 - F4 无cache，H7 有 cache 如果是 STM32F7/STM32H7 这种带 cache 功能，需要将 usb 使用到的 ram 定位到 no cache ram 区域。举例如下 @@ -179,4 +179,4 @@ USB Host 移植要点 仓库参考：https://github.com/CherryUSB/cherryusb_hpmicro - HPM 系列芯片均 USB 2.0 并且内置高速 PHY，支持主从机 -- USB 的相关应用位于 `samples/cherryusb` ，根据官方环境搭建完成后，即可编译使用。 +- USB 的相关应用位于 `samples/cherryusb` ，根据官方环境搭建完成后，即可编译使用。 diff --git a/docs/source/quick_start/other_chip.rst b/docs/source/quick_start/other_chip.rst index 7716e8a3..cb0832c7 100644 --- a/docs/source/quick_start/other_chip.rst +++ b/docs/source/quick_start/other_chip.rst @@ -22,16 +22,19 @@ USB Host 移植要点 - 实现 `usb_hc_low_level_init` 函数（该函数主要负责 USB 时钟、引脚、中断的初始化）。该函数可以放在你想要放的任何参与编译的 c 文件中。如何进行 USB 的时钟、引脚、中断等初始化，请自行根据你使用的芯片原厂提供的源码中进行添加。 - 调用 `usbh_initialize` 并填入 `busid` 和 USB IP 的 `reg base`， `busid` 从 0 开始，不能超过 `CONFIG_USBHOST_MAX_BUS` - 在中断函数中调用 `USBH_IRQHandler`，并传入 `busid`, 如果你的 SDK 中中断入口已经存在 `USBH_IRQHandler` ，请更改 USB 协议栈中的名称 -- 如果使用的是 GCC ，需要在链接脚本(ld)中添加如下代码（需要放在 flash 位置）： +- 如果使用的是 GCC ，需要在链接脚本中添加如下代码（需要放在 flash 位置）： .. code-block:: C + // 在 ld 文件中添加如下代码 . = ALIGN(4); __usbh_class_info_start__ = .; KEEP(*(.usbh_class_info)) __usbh_class_info_end__ = .; - // 举例如下 +GCC 举例如下： + +.. code-block:: C /* The program code and other data into "FLASH" Rom type memory */ .text : @@ -51,9 +54,9 @@ USB Host 移植要点 __usbh_class_info_end__ = .; . = ALIGN(4); _etext = .; /* define a global symbols at end of code */ - } >FLASH + } > FLASH -- 如果使用的是 Segger Embedded Studio ，需要在链接脚本(icf)中添加如下代码： +- Segger Embedded Studio 举例如下： .. code-block:: C diff --git a/docs/source/quick_start/rt-thread/img/config_file.png b/docs/source/quick_start/rt-thread/img/config_file.png deleted file mode 100644 index fd369f37..00000000 Binary files a/docs/source/quick_start/rt-thread/img/config_file.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/env0.png b/docs/source/quick_start/rt-thread/img/env0.png index bb9e8e19..c0a8b03f 100644 Binary files a/docs/source/quick_start/rt-thread/img/env0.png and b/docs/source/quick_start/rt-thread/img/env0.png differ diff --git a/docs/source/quick_start/rt-thread/img/env1.png b/docs/source/quick_start/rt-thread/img/env1.png index d232a408..2a68e052 100644 Binary files a/docs/source/quick_start/rt-thread/img/env1.png and b/docs/source/quick_start/rt-thread/img/env1.png differ diff --git a/docs/source/quick_start/rt-thread/img/env2.png b/docs/source/quick_start/rt-thread/img/env2.png index 48657413..ee37101a 100644 Binary files a/docs/source/quick_start/rt-thread/img/env2.png and b/docs/source/quick_start/rt-thread/img/env2.png differ diff --git a/docs/source/quick_start/rt-thread/img/env3.png b/docs/source/quick_start/rt-thread/img/env3.png deleted file mode 100644 index ed55056b..00000000 Binary files a/docs/source/quick_start/rt-thread/img/env3.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/env4.png b/docs/source/quick_start/rt-thread/img/env4.png deleted file mode 100644 index 36c4e53c..00000000 Binary files a/docs/source/quick_start/rt-thread/img/env4.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/env5.png b/docs/source/quick_start/rt-thread/img/env5.png deleted file mode 100644 index 85de879a..00000000 Binary files a/docs/source/quick_start/rt-thread/img/env5.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/env6.png b/docs/source/quick_start/rt-thread/img/env6.png deleted file mode 100644 index 20a57d07..00000000 Binary files a/docs/source/quick_start/rt-thread/img/env6.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/env7.png b/docs/source/quick_start/rt-thread/img/env7.png deleted file mode 100644 index dc63bebd..00000000 Binary files a/docs/source/quick_start/rt-thread/img/env7.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/env8.png b/docs/source/quick_start/rt-thread/img/env8.png deleted file mode 100644 index c2e31f9a..00000000 Binary files a/docs/source/quick_start/rt-thread/img/env8.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/rtthread.rst b/docs/source/quick_start/rt-thread/rtthread.rst index 69db0db4..b69b95fe 100644 --- a/docs/source/quick_start/rt-thread/rtthread.rst +++ b/docs/source/quick_start/rt-thread/rtthread.rst @@ -9,31 +9,28 @@ -------------------------- * 选择 Enable usb device mode 并敲回车进入。 +* 首先第一个配置是配置 USB 的速度，分为 **FS、HS**，表示使用全速还是高速功能。高速功能要求内置高速 PHY 或者外接 PHY +* 其次第二个配置则是选择 USB device ip，不清楚自己芯片是哪个 ip 的可以参考 **port** 目录下对应的 readme。 +* 选择你想使用的 class +* 选择是否使用 demo 模板 .. figure:: img/env1.png -.. figure:: img/env2.png - -* 首先第一个配置是配置 USB 的速度，分为 **FS、HS**，表示使用全速还是高速功能。 - -.. figure:: img/env3.png - -* 其次第二个配置则是选择 USB device ip，不清楚自己芯片是哪个 ip 的可以参考 **port** 目录下对应的 readme。 - -.. figure:: img/env4.png - -* 选择好 USB device ip 以后，还需要选择是哪款芯片，第三个配置则是用来选择芯片，选择以后会配置相应的 ip 的一些信息和 glue 文件 - -.. figure:: img/env5.png - -* 接下来是 class 的选择，用哪个 class 勾选哪个就可以了，使能 class 以后，双击进入可以选择一个 demo 的模板参与编译，当然也可以不选，自己写。 - -.. figure:: img/env6.png * 最后退出保存即可。 -* 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径,并实现以下内容： +* 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径,并修改以下内容： -.. figure:: img/config_file.png +.. code-block:: C + #include "rtthread.h" + + #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` * 以上内容我们推荐放在 **board.c** 中，如下代码： @@ -60,19 +57,27 @@ -------------------------- * 选择 Enable usb host mode 并敲回车进入。 - -.. figure:: img/env7.png - -* 选择 USB host ip，不清楚自己芯片是哪个 ip 的可以参考 **port** 目录下对应的 readme。选择好 USB host ip 以后，还需要选择是哪款芯片，第二个箭头则是用来选择芯片，选择以后会帮忙配置相对应的 ip 的一些信息，比如 `USB_BASE` 、 `USBH_Handler` 以及特殊的一些配置等等，如果没找到自己的芯片，可以手动在 `usb_hc_xxx.c` 中修改。 - -.. figure:: img/env8.png - +* 选择 USB host ip，不清楚自己芯片是哪个 ip 的可以参考 **port** 目录下对应的 readme。 * 根据需要勾选 class 驱动 +* 选择是否开启模板 demo，请注意， msc 禁止使能，因为默认对接到 dfs。 + +.. figure:: img/env2.png + * 最后退出保存即可。 * 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径,并实现以下内容： -.. figure:: img/config_file.png +.. code-block:: C + #include "rtthread.h" + + #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` * 以上内容我们推荐放在 **board.c** 中，如下代码：