docs: update rst

Signed-off-by: sakumisu <1203593632@qq.com>

docs/source/quick_start/demo.rst

@@ -29,6 +29,21 @@
 - esp32p4：一个 USB2.0 内置全速 PHY 芯片，一个 USB2.0 内置高速 PHY 芯片，支持主从机。
 - 默认 demo 采用组件库安装的形式，在 https://components.espressif.com/ 中搜索 cherryusb 即可
 
+ESP-Registry 可以参考官方文档，推荐使用 vscode + esp-idf 的开发环境。
+
+- ctrl + shift + p 选择 ESP-IDF 欢迎界面，然后选择 Component mananger
+
+.. figure:: img/esp1.png
+
+- 找到 cherryusb 并安装
+
+.. figure:: img/esp2.png
+
+- 打开 menuconfig，并打开 cherryusb 的配置，根据实际情况选择主机或者从机模式
+
+.. figure:: img/esp3.png
+.. figure:: img/esp4.png
+
 基于飞腾派系列芯片（官方 SDK 支持）
 -----------------------------------
 

docs/source/quick_start/esp.rst

@@ -1,17 +0,0 @@
-基于 ESP-Registry 开发指南
-===========================
-
-ESP-Registry 可以参考官方文档，推荐使用 vscode + esp-idf 的开发环境。
-
-- ctrl + shift + p 选择 ESP-IDF 欢迎界面，然后选择 Component mananger
-
-.. figure:: img/esp1.png
-
-- 找到 cherryusb 并安装
-
-.. figure:: img/esp2.png
-
-- 打开 menuconfig，并打开 cherryusb 的配置，根据实际情况选择主机或者从机模式
-
-.. figure:: img/esp3.png
-.. figure:: img/esp4.png

docs/source/quick_start/opensource.rst

@@ -0,0 +1,62 @@
+官方开源项目分享
+====================
+
+除了基本的厂家 SDK 支持以外，我们还对一些火热的开源项目进行了支持，以便于开发者更好的使用这些项目。下面列举适配的 demo 工程链接，具体适配层参考 https://github.com/cherry-embedded/CherryUSB/tree/master/platform 。
+
+DAPLINK
+--------------
+
+适配链接：https://github.com/cherry-embedded/CherryDAP
+
+Blackmagic
+--------------
+
+适配链接：https://github.com/zhangjiance/bmp-hpm-port
+
+RT-Thread
+--------------
+
+适配链接：https://github.com/RT-Thread/rt-thread
+
+NUTTX/VELA
+--------------
+
+适配链接：https://github.com/CherryUSB/cherryusb_nuttx
+
+Zephyr
+--------------
+
+适配链接：https://github.com/hpmicro/zephyr_sdk_glue
+
+Cangaroo
+--------------
+
+Cangaroo is an open source can bus analyzer software. We provide four-channel CANFD analyzer based on hpmicro hpm5361
+
+适配上位机链接：https://github.com/RCSN/cangaroo_hpmicro_canfd_analyzer
+适配下位机链接：https://github.com/RCSN/hpm_sdk_extra/tree/main/demos/cangaroo_hpmicro
+
+LVGL
+--------------
+
+适配链接：https://github.com/cherry-embedded/CherryUSB/tree/master/platform/lvgl
+
+QMK
+--------------
+
+QMK is an open-source keyboard firmware for Atmel AVR and Arm USB families.
+
+适配链接：待开放
+
+Klipper
+--------------
+
+Klipper is a 3d-printer firmware.
+
+适配链接：待开放
+
+
+MAKCU/KMBOX
+--------------
+
+懂的都懂，不开放

docs/source/quick_start/q&a.rst

@@ -0,0 +1,124 @@
+Q & A
+==============================
+
+移植提问模板
+----------------
+
+请在下列途径提交问题：
+- RT-Thread 官方论坛: https://club.rt-thread.org/ask/tag/5f5f851966917b14.html
+- Github issue: https://github.com/cherry-embedded/CherryUSB/issues/new/choose
+
+提问中请包含以下信息：
+
+- 使用的版本
+- 使用的板子，引脚，USB IP
+- 是否配置 USB 中断，USB 时钟，USB 引脚，USB phy 配置，以及 USB 寄存器地址是否正确，截图
+- 是否能进 USB 中断
+- 芯片是否带有 cache功能，是否做了 no cache 处理，截图
+- USB 电路是否画正确，是否使用杜邦线连接，是否直连，如果正常，请说明正常原因
+- 如果能进中断，配置 **#define CONFIG_USB_DBG_LEVEL USB_DBG_LOG** 并提供 log，仅限商业 IP, 其余 IP 禁止开启 log，否则无法枚举
+- 是否流片并销售
+
+其余问题提问模板
+------------------
+
+具体说明现象，复现方式，使用我提供的 demo 再测试，以及提供完整 log
+
+CherryUSB 性能能到多少
+----------------------------------------------------------------
+
+参考 :ref:`performace_show`
+
+ST IP 命名问题
+------------------
+
+ST 命名为 USB_OTG_FS, USB_OTG_HS，并不是说明本身是高速或者全速，只是代表可以支持到高速，但是本身都是全速，需要外挂高速phy。因此，提问禁止说这两个词，请使用 USB0(PA11/PA12),USB1(PB14/PB15) 代替。其余国产厂家同理。
+
+GD IP 问题
+------------------
+
+GD IP 采用 DWC2，但是读取的硬件参数都是 0（我也不懂为什么不给人知道），因此需要用户自行知道硬件信息，从 1.5.0 开始由于需要读取硬件信息，因此无法直接使用。
+
+其次 GD 复位以后无法使用 EPDIS 功能关闭端点，需要用户删除 reset 中断中的以下代码：
+
+.. code-block:: C
+
+    USB_OTG_INEP(i)->DIEPCTL = (USB_OTG_DIEPCTL_EPDIS | USB_OTG_DIEPCTL_SNAK);
+    USB_OTG_OUTEP(i)->DOEPCTL = (USB_OTG_DOEPCTL_EPDIS | USB_OTG_DOEPCTL_SNAK);
+
+除此之外可能存在其他未知 BUG，请自行测试。
+
+开启 USB_LOG_DBG 后无法枚举
+----------------------------------------------------------------
+
+有且仅有商业性 IP 开启后可以枚举，其余 IP 禁止开启，否则无法枚举。懂得都懂。
+
+USB3 CV测试用哪个版本
+------------------------------
+
+1.4.3 版本及以上
+
+Ep addr XXX fifo overflow
+------------------------------
+
+.. figure:: img/question1.png
+
+该错误表示该端点默认设置的 fifo 空间不够用，需要增大 fifo 空间，通常见于 DWC2/MUSB IP。FIFO 设置参考相关的 glue 文件。
+
+Ep addr XXX overflow
+------------------------------
+
+.. figure:: img/question2.png
+
+该错误表示该 IP 硬件上没有这么多端点, 请更换 IP or 减少端点使用。
+当然也可以修改为双向端点，考虑到不是所有的 IP 都支持双向端点，因此默认 demo 不做双向功能，举例默认是 81 02 这样的而不是 81 01，如果支持，自行修改。某些 IP 双向端点可能会占用相同的硬件信息，不一定能同时使用，自行检查。
+
+This dwc2 version does not support dma mode, so stop working
+----------------------------------------------------------------
+
+该 DWC2 版本不支持 dma 模式，禁止使用。不使用 DMA 模式会频繁触发 NAK 中断（大概几十us一次），CPU 占用率过高。
+
+OTG 有哪些芯片支持
+------------------------------
+
+当前主线仅 HPM 芯片支持 OTG 功能，通过 ID 引脚自动切换主从模式，其他芯片请使用手动切换模式 OR 自行实现添加 ID 识别的驱动。
+
+PC 识别的 COM 口如何更改名称
+----------------------------------------------------------------
+
+这是微软对 CDC ACM 的驱动问题，无法修改，如需修改，请联系微软并缴纳费用+编写驱动后即可更改。
+
+connect 和 disconnect event 不触发
+----------------------------------------------------------------
+
+当前仅 hpm 芯片支持 connect 和 disconnect 事件，其他芯片请使用 USB 检测 vbus 电路。DWC2 IP 支持，但是由于需要占用引脚，并且大多是log 口，然后不同使能的配置也不一样，因此不做支持。
+
+__has_include 报错
+------------------------------------------------------------------
+如果报错，需要编译器支持 c99 语法，如果是 keil，请用 ac6 编译器
+
+CONFIG_USB_HS 何时使用
+----------------------------------------------------------------
+
+当你的芯片硬件支持高速，并想初始化成高速模式时开启，相关 IP 会根据该宏配置内部或者外部 高速 PHY。
+
+Failed to enable port
+----------------------------------------------------------------
+
+供电不足或者硬件 USB 电路问题
+
+移植 usb host 出现 urb  返回 -12/-14
+----------------------------------------------------------------
+
+检查 phy 配置，cache 配置（如果有），电源供电（建议自供电）
+
+USB_ERR_NAK 说明
+----------------------------------------------------------------
+
+USB_ERR_NAK 只存在于 DWC2 buffer dma 模式，DWC2 在 buffer dma模式下对于中断传输不支持硬件处理 NAK 中断，因此需要软件处理，导致 NAK 中断非常多，建议搭配定时器使用。
+DWC2 scatter/gather dma 模式下全部由硬件处理，但是不支持 split 传输。总结， **半斤 IP**。
+
+USB host 连接 USB 网卡问题
+----------------------------------------------------------------
+
+表现为能识别网卡并且分配到 IP 地址，但是无法 ping 通，这是因为网卡自身需要开启自动拨号，通常需要使用 AT 口设置。具体为 EC20/ML307 等模块。

docs/source/quick_start/share.rst

@@ -0,0 +1,27 @@
+开发者经验/开源项目分享
+========================
+
+- `RT-Thread-CherryUSB - RT-Thread <https://club.rt-thread.org/ask/tag/5f5f851966917b14.html?type=article>`_
+
+- `[HPM-DIY]hpm6750 USB开源协议栈性能对比-cherryusb or tinyusb？ <https://bbs.eeworld.com.cn/thread-1212755-1-1.html>`_
+
+- `RT-Thread-CherryUSB移植笔记(一)：APM32F407VGT6 DWC2移植 Port.A Full-Speed + Por.B High-SpeedRT-Thread问答社区 - RT-Thread <https://club.rt-thread.org/ask/article/3e893614c58da7aa.html>`_
+
+- `华大HC32F460XXX移植cherryusb协议栈，实现USB CDC ACM_cherryusb移植教程-CSDN博客 <https://blog.csdn.net/u011404840/article/details/142180703>`_
+
+- `rt-thread使用cherryusb实现虚拟串口-CSDN博客 <https://blog.csdn.net/weixin_45919462/article/details/143872583>`_
+
+- `F1C100S+rtt+CherryUSB的USB HOST成功读到U盘 / 全志 SOC / WhyCan Forum(哇酷开发者社区) <https://whycan.com/t_10289.html>`_
+
+- `模仿stm32标准库风格写的库文件（f1c100s/f1c200s)，且已移植了rt-thread、lvgl、fatfs、cherryusb / 全志 SOC / WhyCan Forum(哇酷开发者社区) <https://whycan.com/t_10475.html>`_
+
+- `printalyzer-timer: F-Stop enlarging timer and print exposure meter <https://github.com/dektronics/printalyzer-timer>`_
+
+- `MiSTeryNano: Atari STE MiSTery core for the Tang Nano 20k FPGA <https://github.com/harbaum/MiSTeryNano>`_
+
+- `Cherryuf2 <https://github.com/zhaqian12/Cherryuf2>`_
+
+- `PicoPiFi: Driverless RNDIS USB WIFI Dongle <https://github.com/sidd-kishan/PicoPiFi>`_
+
+- `phobia: Phobia Motor Controller <https://github.com/rombrew/phobia>`_
+