update(docs): update rst

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

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` 函数。

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。

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` ，根据官方环境搭建完成后，即可编译使用。

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
 

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** 中，如下代码：