docs: update docs and add english version

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

.github/workflows/deploy-docs.yml

@@ -11,7 +11,7 @@ permissions:
 jobs:
   deploy:
     runs-on: ubuntu-latest
-    
+
     steps:
       - uses: actions/checkout@v4
         with:
@@ -23,6 +23,6 @@ jobs:
       - uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: gh-pages
-          folder: docs/build/html
+          folder: docs/output/zh/html
 
 

README.md

@@ -14,31 +14,31 @@ CherryUSB is a tiny and beautiful, high performance and portable USB host and de
 
 ## Why choose CherryUSB
 
-### Easy to study USB
+### Easy to Learn USB
 
-In order to make it easier for users to learn USB basics, enumeration, driver loading and IP drivers, the code has been written with the following advantages:
+To facilitate user learning of USB fundamentals, enumeration, driver loading, and IP drivers, the written code has the following advantages:
 
-- Lean code, simple logic, no complex C syntax
-- Tree-based programming with cascading code
-- Class-drivers and porting-drivers are templating and simplification
-- Clear API classification (slave: initialisation, registration api, command callback api, data sending and receiving api; host: initialisation, lookup api, data sending and receiving api)
+- Streamlined code with simple logic and no complex C language syntax
+- Tree-structured programming with progressive code layers
+- Templated and simplified Class drivers and porting drivers
+- Clear API categorization (Device: initialization, class registration, command callbacks, data transmission; Host: initialization, class discovery, data transmission)
 
-### Easy to use USB
+### Easy to Use USB
 
-In order to facilitate the use of the USB interface and to take into account the fact that users have learned about uart and dma, the following advantages have been designed for the data sending and receiving class of interface:
+To facilitate user interaction with USB interfaces, considering users’ familiarity with UART and DMA, the designed data transmission interface has the following advantages:
 
-- Equivalent to using uart tx dma/uart rx dma
-- There is no limit to the length of send and receive, the user does not need to care about the USB packetization process (the porting driver does it)
+- Equivalent to using UART TX DMA/UART RX DMA
+- No length restrictions on transmission/reception; users don’t need to worry about USB packetization (porting drivers handle packetization)
 
-### Easy to bring out USB performance
+### Easy to Achieve USB Performance
 
-Taking into account USB performance issues and trying to achieve the theoretical bandwidth of the USB hardware, the design of the data transceiver class interface has the following advantages:
+Considering USB performance requirements to reach theoretical USB hardware bandwidth, the designed data transmission interface has the following advantages:
 
-- Porting drivers directly to registers, no abstraction layer encapsulation
+- Porting drivers directly interface with registers without abstraction layer encapsulation
 - Memory zero copy
-- If IP has DMA then uses DMA mode (DMA with hardware packetization)
-- Unlimited length make it easier to interface with hardware DMA and take advantage of DMA
-- Packetization is handled in interrupt
+- DMA mode used when IP supports DMA (DMA provides hardware packetization functionality)
+- No length restrictions, facilitating hardware DMA interfacing and maximizing DMA advantages
+- Packetization handled in interrupt context
 
 Performance show：https://cherryusb.cherry-embedded.org/show/
 
@@ -176,55 +176,31 @@ Only standard and commercial USB IP are listed.
 |  CDNS3(cadence)  |  CDNS3     | XHCI     |  ×   |
 |  DWC3(synopsys)  |  DWC3      | XHCI     |  ×   |
 
-## Documentation Tutorial
+## Resources
 
-Quickly start, USB basic concepts, API manual, Class basic concepts and examples, see [CherryUSB Documentation Tutorial](https://cherryusb.readthedocs.io/).
+### Getting Started
 
-## Video Tutorial
+- 📖 [CherryUSB Documentation](https://cherryusb.readthedocs.io/en/latest/)
+- 💻 [CherryUSB Demo Repo](https://cherryusb.readthedocs.io/en/latest/quick_start/demo.html)
+- 📺 [CherryUSB Cheese(>= V1.4.3)](https://www.bilibili.com/cheese/play/ss707687201)
 
-CherryUSB Cheese (>= V1.4.3): https://www.bilibili.com/cheese/play/ss707687201 .
-
-## Descriptor Generator Tool
-
-Cherry Descriptor: https://desc.cherry-embedded.org/en
-
-## Demo Repo
-
-|   Manufacturer       |  CHIP or Series    | USB IP| Repo Url | Support version     | Note |
-|:--------------------:|:------------------:|:-----:|:--------:|:------------------:|:-------------:|
-|Bouffalolab    |  BL702/BL616/BL808 | bouffalolab/ehci|[bouffalo_sdk](https://github.com/CherryUSB/bouffalo_sdk)|<= latest | Official |
-|ST             |  STM32F1x/STM32F4/STM32H7 | fsdev/dwc2 |[stm32_repo](https://github.com/CherryUSB/cherryusb_stm32)|<= latest | Community |
-|HPMicro        |  HPM6000/HPM5000 | hpm/ehci |[hpm_sdk](https://github.com/CherryUSB/hpm_sdk)|<= latest | Official |
-|Essemi         |  ES32F36xx | musb |[es32f369_repo](https://github.com/CherryUSB/cherryusb_es32)|<= latest | Official |
-|Phytium        |  e2000 | pusb2/xhci |[phytium_repo](https://gitee.com/phytium_embedded/phytium-free-rtos-sdk)|>=1.4.0  | Official |
-|Artinchip      |  d12x/d13x/d21x | aic/ehci/ohci |[luban-lite](https://gitee.com/artinchip/luban-lite)|<= latest  | Official |
-|Espressif      |  esp32s2/esp32s3/esp32p4 | dwc2 |[esp32_repo](https://github.com/CherryUSB/cherryusb_esp32)/[espressif](https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb)|<= latest | Official |
-|Kendryte       |  k230 | dwc2 |[k230_repo](https://github.com/CherryUSB/k230_sdk)|v1.2.0 | Official |
-|Actionstech    |  ATS30xx | dwc2 |[action_zephyr_repo](https://github.com/CherryUSB/lv_port_actions_technology/tree/master/action_technology_sdk)|>=1.4.0 | Official |
-|SiFli          |  SF32LB5x | musb |[SiFli_sdk](https://github.com/OpenSiFli/SiFli-SDK)|>=1.5.0 | Official |
-|NXP            |  mcx | kinetis/chipidea/ehci |[nxp_mcx_repo](https://github.com/CherryUSB/cherryusb_mcx)|<= latest | Community |
-|Nationstech    |  n32h4x | dwc2 |[nation_repo](https://github.com/CherryUSB/cherryusb_nation)|>=1.5.0 | Official ongoing |
-|Raspberry pi   |  rp2040/rp2350 | rp2040 |[pico-sdk](https://github.com/CherryUSB/pico-sdk)|<= latest | Official ongoing |
-|AllwinnerTech  |  F1C100S/F1C200S | musb |[cherryusb_rtt_f1c100s](https://github.com/CherryUSB/cherryusb_rtt_f1c100s)|<= latest | no more update |
-|Bekencorp      |  bk7256/bk7258 | musb |[bk_idk](https://github.com/CherryUSB/bk_idk)| v0.7.0 | Official |
-|Sophgo         |  cv18xx | dwc2 |[cvi_alios_open](https://github.com/CherryUSB/cvi_alios_open)| v0.7.0 | Official |
-|WCH            |  CH32V307/ch58x | ch32_usbfs/ch32_usbhs/ch58x |[wch_repo](https://github.com/CherryUSB/cherryusb_wch)|<= v0.10.2/>=v1.5.0 | no more update |
-
-## Package Support
-
-CherryUSB package is available as follows:
+### Package Support
 
 - [RT-Thread](https://packages.rt-thread.org/detail.html?package=CherryUSB)
 - [YOC](https://www.xrvm.cn/document?temp=usb-host-protocol-stack-device-driver-adaptation-instructions&slug=yocbook)
 - [ESP-Registry](https://components.espressif.com/components/cherry-embedded/cherryusb)
 
-## Commercial Support
+### Descriptor Generator Tool
 
-Refer to https://cherryusb.readthedocs.io/zh-cn/latest/support/index.html.
+Cherry Descriptor: https://desc.cherry-embedded.org/en
+
+### Contact
 
-## Contact
+CherryUSB discord: https://discord.com/invite/wFfvrSAey8
+
+## Commercial Support
 
-CherryUSB discord: https://discord.com/invite/wFfvrSAey8.
+Refer to https://cherryusb.readthedocs.io/en/latest/support/index.html
 
 ## Company Support
 

README_zh.md

@@ -176,58 +176,34 @@ x 受以下宏影响：
 |  CDNS3(cadence)  |  CDNS3     | XHCI     |  ×   |
 |  DWC3(synopsys)  |  DWC3      | XHCI     |  ×   |
 
-## 文档教程
+## Resources
 
-CherryUSB 快速入门、USB 基本概念、API 手册、Class 基本概念和例程，参考 [CherryUSB Documentation Tutorial](https://cherryusb.readthedocs.io/)。
+### 快速开始
 
-## 视频教程
+- 📖 [CherryUSB Documentation](https://cherryusb.readthedocs.io/zh-cn/latest/)
+- 💻 [CherryUSB Demo Repo](https://cherryusb.readthedocs.io/zh-cn/latest/quick_start/demo.html)
+- 📺 [CherryUSB Cheese(>= V1.4.3)](https://www.bilibili.com/cheese/play/ss707687201)
 
-CherryUSB 课程（>= V1.4.3）：https://www.bilibili.com/cheese/play/ss707687201 。
-
-## 描述符生成工具
-
-Cherry Descriptor: https://desc.cherry-embedded.org/zh
-
-## 示例仓库
-
-|   Manufacturer       |  CHIP or Series    | USB IP| Repo Url | Support version     | Note |
-|:--------------------:|:------------------:|:-----:|:--------:|:------------------:|:-------------:|
-|Bouffalolab    |  BL702/BL616/BL808 | bouffalolab/ehci|[bouffalo_sdk](https://github.com/CherryUSB/bouffalo_sdk)|<= latest | Official |
-|ST             |  STM32F1x/STM32F4/STM32H7 | fsdev/dwc2 |[stm32_repo](https://github.com/CherryUSB/cherryusb_stm32)|<= latest | Community |
-|HPMicro        |  HPM6000/HPM5000 | hpm/ehci |[hpm_sdk](https://github.com/CherryUSB/hpm_sdk)|<= latest | Official |
-|Essemi         |  ES32F36xx | musb |[es32f369_repo](https://github.com/CherryUSB/cherryusb_es32)|<= latest | Official |
-|Phytium        |  e2000 | pusb2/xhci |[phytium_repo](https://gitee.com/phytium_embedded/phytium-free-rtos-sdk)|>=1.4.0  | Official |
-|Artinchip      |  d12x/d13x/d21x | aic/ehci/ohci |[luban-lite](https://gitee.com/artinchip/luban-lite)|<= latest  | Official |
-|Espressif      |  esp32s2/esp32s3/esp32p4 | dwc2 |[esp32_repo](https://github.com/CherryUSB/cherryusb_esp32)/[espressif](https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb)|<= latest | Official |
-|Kendryte       |  k230 | dwc2 |[k230_repo](https://github.com/CherryUSB/k230_sdk)|v1.2.0 | Official |
-|Actionstech    |  ATS30xx | dwc2 |[action_zephyr_repo](https://github.com/CherryUSB/lv_port_actions_technology/tree/master/action_technology_sdk)|>=1.4.0 | Official |
-|SiFli          |  SF32LB5x | musb |[SiFli_sdk](https://github.com/OpenSiFli/SiFli-SDK)|>=1.5.0 | Official |
-|NXP            |  mcx | kinetis/chipidea/ehci |[nxp_mcx_repo](https://github.com/CherryUSB/cherryusb_mcx)|<= latest | Community |
-|Nationstech    |  n32h4x | dwc2 |[nation_repo](https://github.com/CherryUSB/cherryusb_nation)|>=1.5.0 | Official ongoing |
-|Raspberry pi   |  rp2040/rp2350 | rp2040 |[pico-sdk](https://github.com/CherryUSB/pico-sdk)|<= latest | Official ongoing |
-|AllwinnerTech  |  F1C100S/F1C200S | musb |[cherryusb_rtt_f1c100s](https://github.com/CherryUSB/cherryusb_rtt_f1c100s)|<= latest | no more update |
-|Bekencorp      |  bk7256/bk7258 | musb |[bk_idk](https://github.com/CherryUSB/bk_idk)| v0.7.0 | Official |
-|Sophgo         |  cv18xx | dwc2 |[cvi_alios_open](https://github.com/CherryUSB/cvi_alios_open)| v0.7.0 | Official |
-|WCH            |  CH32V307/ch58x | ch32_usbfs/ch32_usbhs/ch58x |[wch_repo](https://github.com/CherryUSB/cherryusb_wch)|<= v0.10.2/>=v1.5.0 | no more update |
-
-## 软件包支持
-
-CherryUSB 软件包可以通过以下方式获取：
+### 软件包支持
 
 - [RT-Thread](https://packages.rt-thread.org/detail.html?package=CherryUSB)
 - [YOC](https://www.xrvm.cn/document?temp=usb-host-protocol-stack-device-driver-adaptation-instructions&slug=yocbook)
 - [ESP-Registry](https://components.espressif.com/components/cherry-embedded/cherryusb)
 
-## 商业支持
+### 描述符生成工具
 
-参考 https://cherryusb.readthedocs.io/zh-cn/latest/support/index.html 。
+Cherry Descriptor: https://desc.cherry-embedded.org/zh
 
-## 联系
+### Contact
 
 CherryUSB QQ群：642693751
 
 CherryUSB 微信群：与我联系后邀请加入
 
+## 商业支持
+
+参考 https://cherryusb.readthedocs.io/zh-cn/latest/support/index.html
+
 ## 支持企业
 
 感谢以下企业支持（顺序不分先后）：

docs/Makefile

@@ -5,16 +5,15 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M help
 
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M html "zh" "output/zh" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M html "en" "output/en" $(SPHINXOPTS) $(O)

.readthedocs.yaml → docs/en/.readthedocs.yaml

@@ -16,7 +16,7 @@ build:
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
-  configuration: docs/source/conf.py
+  configuration: docs/en/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

docs/en/api/api_config.rst

@@ -0,0 +1,162 @@
+USB CONFIG Description
+=======================================
+
+General CONFIG
+---------------------
+
+CONFIG_USB_PRINTF
+^^^^^^^^^^^^^^^^^^^^
+
+USB log functionality, defaults to redirect to printf. Note that USB log will be used in interrupts, so the redirected API must not block. For example, if using RT-Thread, please change to rt-kprintf
+
+CONFIG_USB_DBG_LEVEL
+^^^^^^^^^^^^^^^^^^^^^^
+
+Controls the log print level
+
+CONFIG_USB_PRINTF_COLOR_ENABLE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Controls log color printing, enabled by default
+
+CONFIG_USB_DCACHE_ENABLE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When not using nocache RAM, enable this macro to ensure data consistency. **When using EHCI, nocache RAM is still required internally**.
+
+CONFIG_USB_ALIGN_SIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+USB buffer alignment size, default is 4. IP in DMA mode may have alignment requirements for input buffers, typically 4. If other alignment is needed, please modify this value.
+
+USB_NOCACHE_RAM_SECTION
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the chip doesn't have cache functionality, this macro is ineffective. If it does, USB input/output buffers must be placed in nocache RAM to ensure data consistency.
+
+Device Protocol Stack CONFIG
+------------------------------
+
+CONFIG_USBDEV_REQUEST_BUFFER_LEN
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Controls the maximum length of control transfer receive and send buffer, default is 512.
+
+CONFIG_USBDEV_SETUP_LOG_PRINT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enable or disable setup packet dump information, disabled by default.
+
+CONFIG_USBDEV_DESC_CHECK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Not implemented yet
+
+CONFIG_USBDEV_TEST_MODE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Enable or disable USB test mode
+
+CONFIG_USBDEV_MSC_MAX_BUFSIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Maximum length of MSC cache. Larger cache results in higher USB speed because storage media typically has much higher multi-block read/write speeds than single block, such as SD cards.
+Default 512. For flash, needs to be changed to 4K. Cache size must be a multiple of the storage media's block size.
+
+CONFIG_USBDEV_MSC_MANUFACTURER_STRING
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CONFIG_USBDEV_MSC_PRODUCT_STRING
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CONFIG_USBDEV_MSC_VERSION_STRING
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CONFIG_USBDEV_MSC_POLLING
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Run usbd_msc_sector_read and usbd_msc_sector_write operations in while1, used in bare-metal systems.
+
+CONFIG_USBDEV_MSC_THREAD
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enable or disable MSC thread, disabled by default. usbd_msc_sector_read and usbd_msc_sector_write are executed in interrupts by default, so if OS is enabled, it's recommended to enable this macro, then usbd_msc_sector_read and usbd_msc_sector_write will execute in threads.
+
+CONFIG_USBDEV_MSC_PRIO
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Priority of MSC read/write thread, default is 4. Lower values mean higher priority.
+
+CONFIG_USBDEV_MSC_STACKSIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Stack size of MSC read/write thread, default 2K bytes
+
+CONFIG_USBDEV_RNDIS_RESP_BUFFER_SIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Maximum receive and send length for RNDIS control transfers. Minimum length determined by RNDIS options list, default should be greater than or equal to 156.
+
+CONFIG_USBDEV_RNDIS_ETH_MAX_FRAME_SIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Maximum length of RNDIS Ethernet frame, default 1580
+
+CONFIG_USBDEV_RNDIS_VENDOR_ID
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CONFIG_USBDEV_RNDIS_VENDOR_DESC
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CONFIG_USBDEV_RNDIS_USING_LWIP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+RNDIS interface with LWIP
+
+Host Protocol Stack CONFIG
+----------------------------
+
+The following parameters determine the maximum number of supported external hubs, interfaces, endpoints per interface, and altsetting counts. Changing these values affects RAM size, it's recommended to adjust according to actual requirements.
+
+.. code-block:: C
+
+    #define CONFIG_USBHOST_MAX_RHPORTS          1
+    #define CONFIG_USBHOST_MAX_EXTHUBS          1
+    #define CONFIG_USBHOST_MAX_EHPORTS          4
+    #define CONFIG_USBHOST_MAX_INTERFACES       6
+    #define CONFIG_USBHOST_MAX_INTF_ALTSETTINGS 1
+    #define CONFIG_USBHOST_MAX_ENDPOINTS        4
+
+The following parameters determine the maximum number of supported class drivers. Changing these values affects RAM size, it's recommended to adjust according to actual requirements.
+
+.. code-block:: C
+
+    #define CONFIG_USBHOST_MAX_SERIAL_CLASS  4
+    #define CONFIG_USBHOST_MAX_HID_CLASS     4
+    #define CONFIG_USBHOST_MAX_MSC_CLASS     2
+    #define CONFIG_USBHOST_MAX_AUDIO_CLASS   1
+    #define CONFIG_USBHOST_MAX_VIDEO_CLASS   1
+
+CONFIG_USBHOST_PSC_PRIO
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Priority of host plug/unplug thread, default is 0. Lower values mean higher priority.
+
+CONFIG_USBHOST_PSC_STACKSIZE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Stack size of host plug/unplug thread, default 2K bytes
+
+CONFIG_USBHOST_REQUEST_BUFFER_LEN
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Maximum length for control transfer receive or send
+
+CONFIG_USBHOST_CONTROL_TRANSFER_TIMEOUT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Timeout for control transfer send or receive, default 500 ms
+
+CONFIG_USBHOST_MSC_TIMEOUT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Timeout for MSC read/write transfers, default 5s

docs/en/api/api_device.rst

@@ -0,0 +1,503 @@
+Device Protocol Stack
+=======================================
+
+The device protocol stack is mainly responsible for enumeration and driver loading. We won't discuss enumeration here, but for driver loading (i.e., interface driver loading), it mainly relies on the `usbd_add_interface` function to record the passed-in interface driver and save it to the interface array table. When the host makes class requests, it can search the interface table for access.
+After calling `usbd_desc_register`, interface registration and endpoint registration need to be performed according to the following rules:
+
+- Call `usbd_add_interface` as many times as there are interfaces, with parameters filling in the relevant `xxx_init_intf`. If not supported, manually create an intf and fill it in
+- Call `usbd_add_endpoint` as many times as there are endpoints. When interrupts complete, the registered endpoint callback will be called.
+
+Refer to the diagram below:
+
+.. figure:: img/api_device1.png
+
+CORE
+-----------------
+
+Endpoint Structure
+""""""""""""""""""""""""""""""""""""
+
+The endpoint structure is mainly used to register interrupt completion callback functions for different endpoint addresses.
+
+.. code-block:: C
+
+    struct usbd_endpoint {
+        uint8_t ep_addr;
+        usbd_endpoint_callback ep_cb;
+    };
+
+- **ep_addr** Endpoint address (with direction)
+- **ep_cb** Endpoint completion interrupt callback function.
+
+.. note:: To summarize in one sentence: in callback function is equivalent to DMA transmission completion interrupt callback function; out callback function is equivalent to DMA reception completion interrupt callback function
+
+Interface Structure
+""""""""""""""""""""""""""""""""""""
+
+The interface structure is mainly used to register requests other than standard device requests for different class devices, including class device requests, vendor device requests, and custom device requests, as well as related notification callback functions in the protocol stack.
+
+.. code-block:: C
+
+    struct usbd_interface {
+        usbd_request_handler class_interface_handler;
+        usbd_request_handler class_endpoint_handler;
+        usbd_request_handler vendor_handler;
+        usbd_notify_handler notify_handler;
+        const uint8_t *hid_report_descriptor;
+        uint32_t hid_report_descriptor_len;
+        uint8_t intf_num;
+    };
+
+- **class_interface_handler** class setup request callback function, recipient is interface
+- **class_endpoint_handler** class setup request callback function, recipient is endpoint
+- **vendor_handler** vendor setup request callback function
+- **notify_handler** interrupt flag, protocol stack related status callback function
+- **hid_report_descriptor** hid report descriptor
+- **hid_report_descriptor_len** hid report descriptor length
+- **intf_num** current interface offset
+
+usbd_desc_register
+""""""""""""""""""""""""""""""""""""
+
+``usbd_desc_register`` is used to register USB descriptors. Descriptor types include: device descriptor, configuration descriptor (including configuration descriptor, interface descriptor, class descriptor, endpoint descriptor), string descriptor, device qualifier descriptor, other speed descriptor, BOS descriptor, WinUSB descriptor.
+
+.. code-block:: C
+
+    // Enable CONFIG_USBDEV_ADVANCE_DESC
+    void usbd_desc_register(uint8_t busid, const struct usb_descriptor *desc);
+
+    // Disable CONFIG_USBDEV_ADVANCE_DESC
+    void usbd_desc_register(uint8_t busid, const uint8_t *desc);
+    void usbd_msosv1_desc_register(uint8_t busid, struct usb_msosv1_descriptor *desc);
+    void usbd_msosv2_desc_register(uint8_t busid, struct usb_msosv2_descriptor *desc);
+    void usbd_bos_desc_register(uint8_t busid, struct usb_bos_descriptor *desc);
+    void usbd_webusb_desc_register(uint8_t busid, struct usb_webusb_descriptor *desc);
+
+- **desc**  Descriptor handle
+
+.. note:: Currently CONFIG_USBDEV_ADVANCE_DESC is enabled by default. If you need to use the old version API, please disable this macro. Starting from v1.6.0, only APIs with CONFIG_USBDEV_ADVANCE_DESC enabled are available
+
+usbd_add_interface
+""""""""""""""""""""""""""""""""""""
+
+``usbd_add_interface`` adds an interface driver. **The addition order must follow the interface order in the descriptor**.
+
+.. code-block:: C
+
+    void usbd_add_interface(uint8_t busid, struct usbd_interface *intf);
+
+- **busid** USB bus ID
+- **intf**  Interface driver handle, usually obtained from different class `xxx_init_intf` functions
+
+usbd_add_endpoint
+""""""""""""""""""""""""""""""""""""
+
+``usbd_add_endpoint`` adds an endpoint interrupt completion callback function.
+
+.. code-block:: C
+
+    void usbd_add_endpoint(uint8_t busid, struct usbd_endpoint *ep);
+
+- **busid** USB bus ID
+- **ep**    Endpoint handle
+
+usbd_initialize
+""""""""""""""""""""""""""""""""""""
+
+``usbd_initialize`` is used to initialize USB device register configuration, USB clock, interrupts, etc. Note that this function must be called last after registering descriptor APIs. **If using an OS, it must be executed within a thread**.
+
+.. code-block:: C
+
+    int usbd_initialize(uint8_t busid, uintptr_t reg_base, usbd_event_handler_t event_handler);
+
+- **busid** USB bus ID
+- **reg_base** USB device register base address
+- **event_handler** Protocol stack interrupt or status callback function, event events
+- **return** Returns 0 for success, other values indicate failure
+
+Event events include:
+
+.. code-block:: C
+
+    USBD_EVENT_ERROR,        /** USB error reported by the controller */
+    USBD_EVENT_RESET,        /** USB reset */
+    USBD_EVENT_SOF,          /** Start of Frame received */
+    USBD_EVENT_CONNECTED,    /** USB connected*/
+    USBD_EVENT_DISCONNECTED, /** USB disconnected */
+    USBD_EVENT_SUSPEND,      /** USB connection suspended by the HOST */
+    USBD_EVENT_RESUME,       /** USB connection resumed by the HOST */
+
+    /* USB DEVICE STATUS */
+    USBD_EVENT_CONFIGURED,        /** USB configuration done */
+    USBD_EVENT_SET_INTERFACE,     /** USB interface selected */
+    USBD_EVENT_SET_REMOTE_WAKEUP, /** USB set remote wakeup */
+    USBD_EVENT_CLR_REMOTE_WAKEUP, /** USB clear remote wakeup */
+    USBD_EVENT_INIT,              /** USB init done when call usbd_initialize */
+    USBD_EVENT_DEINIT,            /** USB deinit done when call usbd_deinitialize */
+    USBD_EVENT_UNKNOWN
+
+.. note:: Most IPs do not support USBD_EVENT_CONNECTED and USBD_EVENT_DISCONNECTED events. Currently only HPM chips support them. For other chips, design your own VBUS detection circuit as an alternative
+
+usbd_deinitialize
+""""""""""""""""""""""""""""""""""""
+
+``usbd_deinitialize`` is used to deinitialize USB device, turn off USB device clock, interrupts, etc.
+
+.. code-block:: C
+
+    int usbd_deinitialize(uint8_t busid);
+
+- **busid** USB bus ID
+- **return** Returns 0 for success, other values indicate failure
+
+CDC ACM
+-----------------
+
+usbd_cdc_acm_init_intf
+""""""""""""""""""""""""""""""""""""
+
+``usbd_cdc_acm_init_intf`` is used to initialize USB CDC ACM class interface and implement related functions for this interface.
+
+- ``cdc_acm_class_interface_request_handler`` is used to handle USB CDC ACM class Setup requests.
+- ``cdc_notify_handler`` is used to handle other USB CDC interrupt callback functions.
+
+.. code-block:: C
+
+    struct usbd_interface *usbd_cdc_acm_init_intf(uint8_t busid, struct usbd_interface *intf);
+
+- **busid** USB bus ID
+- **return**  Interface handle
+
+usbd_cdc_acm_set_line_coding
+""""""""""""""""""""""""""""""""""""
+
+``usbd_cdc_acm_set_line_coding`` is used to configure the serial port. If only using USB without serial port, this interface does not need to be implemented by the user and can use the default.
+
+.. code-block:: C
+
+    void usbd_cdc_acm_set_line_coding(uint8_t busid, uint8_t intf, struct cdc_line_coding *line_coding);
+
+- **busid** USB bus ID
+- **intf** Control interface number
+- **line_coding** Serial port configuration
+
+usbd_cdc_acm_get_line_coding
+""""""""""""""""""""""""""""""""""""
+
+``usbd_cdc_acm_get_line_coding`` is used to get serial port configuration. If only using USB without serial port, this interface does not need to be implemented by the user and can use the default.
+
+.. code-block:: C
+
+    void usbd_cdc_acm_get_line_coding(uint8_t busid, uint8_t intf, struct cdc_line_coding *line_coding);
+
+- **busid** USB bus ID
+- **intf** Control interface number
+- **line_coding** Serial port configuration
+
+usbd_cdc_acm_set_dtr
+""""""""""""""""""""""""""""""""""""
+
+``usbd_cdc_acm_set_dtr`` is used to control serial port DTR. If only using USB without serial port, this interface does not need to be implemented by the user and can use the default.
+
+.. code-block:: C
+
+    void usbd_cdc_acm_set_dtr(uint8_t busid, uint8_t intf, bool dtr);
+
+- **busid** USB bus ID
+- **intf** Control interface number
+- **dtr** dtr = 1 means pull low level, 0 means pull high level
+
+usbd_cdc_acm_set_rts
+""""""""""""""""""""""""""""""""""""
+
+``usbd_cdc_acm_set_rts`` is used to control serial port RTS. If only using USB without serial port, this interface does not need to be implemented by the user and can use the default.
+
+.. code-block:: C
+
+    void usbd_cdc_acm_set_rts(uint8_t busid, uint8_t intf, bool rts);
+
+- **busid** USB bus ID
+- **intf** Control interface number
+- **rts** rts = 1 means pull low level, 0 means pull high level
+
+CDC_ACM_DESCRIPTOR_INIT
+""""""""""""""""""""""""""""""""""""
+
+``CDC_ACM_DESCRIPTOR_INIT`` configures the default CDC ACM required descriptors and parameters for user convenience. Total length is `CDC_ACM_DESCRIPTOR_LEN`.
+
+.. code-block:: C
+
+    CDC_ACM_DESCRIPTOR_INIT(bFirstInterface, int_ep, out_ep, in_ep, str_idx);
+
+- **bFirstInterface** Indicates the offset of the first interface of this CDC ACM in all interfaces
+- **int_ep** Indicates interrupt endpoint address (with direction)
+- **out_ep** Indicates bulk out endpoint address (with direction)
+- **in_ep** Indicates bulk in endpoint address (with direction)
+- **str_idx** String ID corresponding to control interface
+
+HID
+-----------------
+
+usbd_hid_init_intf
+""""""""""""""""""""""""""""""""""""
+
+``usbd_hid_init_intf`` is used to initialize USB HID class interface and implement related functions for this interface:
+
+- ``hid_class_interface_request_handler`` is used to handle USB HID class Setup requests.
+- ``hid_notify_handler`` is used to handle other USB HID interrupt callback functions.
+
+.. code-block:: C
+
+    struct usbd_interface *usbd_hid_init_intf(uint8_t busid, struct usbd_interface *intf, const uint8_t *desc, uint32_t desc_len);
+
+- **busid** USB bus ID
+- **desc** Report descriptor
+- **desc_len** Report descriptor length
+
+MSC
+-----------------
+
+usbd_msc_init_intf
+""""""""""""""""""""""""""""""""""""
+``usbd_msc_init_intf`` is used to initialize MSC class interface, implement related functions for this interface, and register endpoint callback functions. (Since MSC BOT protocol is fixed, user implementation is not needed, so endpoint callback functions naturally don't need user implementation).
+
+- ``msc_storage_class_interface_request_handler`` is used to handle USB MSC Setup interrupt requests.
+- ``msc_storage_notify_handler`` is used to implement other USB MSC interrupt callback functions.
+
+- ``mass_storage_bulk_out`` is used to handle USB MSC endpoint out interrupts.
+- ``mass_storage_bulk_in`` is used to handle USB MSC endpoint in interrupts.
+
+.. code-block:: C
+
+    struct usbd_interface *usbd_msc_init_intf(uint8_t busid, struct usbd_interface *intf, const uint8_t out_ep, const uint8_t in_ep);
+
+- **busid** USB bus ID
+- **out_ep**     out endpoint address
+- **in_ep**      in endpoint address
+
+usbd_msc_get_cap
+""""""""""""""""""""""""""""""""""""
+
+``usbd_msc_get_cap`` is used to get the LUN, number of sectors, and sector size of the storage device. Users must implement this function.
+
+.. code-block:: C
+
+    void usbd_msc_get_cap(uint8_t busid, uint8_t lun, uint32_t *block_num, uint16_t *block_size);
+
+- **busid** USB bus ID
+- **lun** Storage logical unit, currently unused, defaults to supporting one
+- **block_num**  Number of storage sectors
+- **block_size**  Storage sector size
+
+usbd_msc_sector_read
+""""""""""""""""""""""""""""""""""""
+
+``usbd_msc_sector_read`` is used to read data from a storage device starting at a specific sector address. Users must implement this function.
+
+.. code-block:: C
+
+    int usbd_msc_sector_read(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length);
+
+- **busid** USB bus ID
+- **lun** Storage logical unit, currently unused, defaults to supporting one
+- **sector** Sector offset
+- **buffer** Pointer to store read data
+- **length** Read length
+
+
+usbd_msc_sector_write
+""""""""""""""""""""""""""""""""""""
+
+``usbd_msc_sector_write`` is used to write data to a storage device starting at a specific sector. Users must implement this function.
+
+.. code-block:: C
+
+    int usbd_msc_sector_write(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length);
+
+- **busid** USB bus ID
+- **lun** Storage logical unit, currently unused, defaults to supporting one
+- **sector** Sector offset
+- **buffer** Write data pointer
+- **length** Write length
+
+UAC
+-----------------
+
+usbd_audio_init_intf
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_init_intf`` is used to initialize USB Audio class interface and implement related functions for this interface:
+
+- ``audio_class_interface_request_handler`` is used to handle USB Audio Setup interface recipient interrupt requests.
+- ``audio_class_endpoint_request_handler`` is used to handle USB Audio Setup endpoint recipient interrupt requests.
+- ``audio_notify_handler`` is used to implement other USB Audio interrupt callback functions.
+
+.. code-block:: C
+
+    struct usbd_interface *usbd_audio_init_intf(uint8_t busid, struct usbd_interface *intf,
+                                                uint16_t uac_version,
+                                                struct audio_entity_info *table,
+                                                uint8_t num);
+
+- **busid** USB bus ID
+- **intf**  Interface handle
+- **uac_version**  Audio class version, UAC1.0 or UAC2.0
+- **table** Audio entity information table
+- **num** Audio entity information table length
+
+usbd_audio_open
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_open`` is used to start audio data transmission. Host sends start command callback function.
+
+.. code-block:: C
+
+    void usbd_audio_open(uint8_t intf);
+
+- **intf** Interface number to open
+
+usbd_audio_close
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_close`` is used to stop audio data transmission. Host sends stop command callback function.
+
+.. code-block:: C
+
+    void usbd_audio_close(uint8_t intf);
+
+- **intf** Interface number to close
+
+usbd_audio_set_mute
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_set_mute`` is used to set mute.
+
+.. code-block:: C
+
+    void usbd_audio_set_mute(uint8_t busid, uint8_t ep, uint8_t ch, bool mute);
+
+- **busid** USB bus ID
+- **ep** Endpoint to set mute
+- **ch** Channel to set mute
+- **mute** 1 means mute, 0 means opposite
+
+usbd_audio_set_volume
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_set_volume`` is used to set volume.
+
+.. code-block:: C
+
+    void usbd_audio_set_volume(uint8_t busid, uint8_t ep, uint8_t ch, int volume_db);
+
+- **busid** USB bus ID
+- **ep** Endpoint to set volume
+- **ch** Channel to set volume
+- **volume_db** Volume to set in decibels, range -100dB ~ 0dB
+
+usbd_audio_set_sampling_freq
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_set_sampling_freq`` is used to set the sampling rate of the audio module on the device
+
+.. code-block:: C
+
+    void usbd_audio_set_sampling_freq(uint8_t busid, uint8_t ep, uint32_t sampling_freq);
+
+- **ep** Endpoint to set sampling rate
+- **sampling_freq** Sampling rate to set
+
+usbd_audio_get_sampling_freq_table
+""""""""""""""""""""""""""""""""""""
+
+``usbd_audio_get_sampling_freq_table`` is used to get the list of supported sampling rates. If the function is not implemented, the default sampling rate list is used. UAC2 only.
+
+.. code-block:: C
+
+    void usbd_audio_get_sampling_freq_table(uint8_t busid, uint8_t ep, uint8_t **sampling_freq_table);
+
+- **ep** Endpoint to get sampling rate
+- **sampling_freq_table** Sampling rate list address, format refers to default sampling rate list
+
+UVC
+-----------------
+
+usbd_video_init_intf
+""""""""""""""""""""""""""""""""""""
+
+``usbd_video_init_intf`` is used to initialize USB Video class interface and implement related functions for this interface:
+
+- ``video_class_interface_request_handler`` is used to handle USB Video Setup interrupt requests.
+- ``video_notify_handler`` is used to implement other USB Video interrupt callback functions.
+
+.. code-block:: C
+
+    struct usbd_interface *usbd_video_init_intf(uint8_t busid, struct usbd_interface *intf,
+                                                uint32_t dwFrameInterval,
+                                                uint32_t dwMaxVideoFrameSize,
+                                                uint32_t dwMaxPayloadTransferSize);
+- **busid** USB bus ID
+- **intf**  Interface handle
+- **dwFrameInterval** Video frame interval, unit 100ns
+- **dwMaxVideoFrameSize** Maximum video frame size
+- **dwMaxPayloadTransferSize** Maximum payload transfer size
+
+usbd_video_open
+""""""""""""""""""""""""""""""""""""
+
+``usbd_video_open`` is used to start video data transmission.
+
+.. code-block:: C
+
+    void usbd_video_open(uint8_t intf);
+
+- **intf** Interface number to open
+
+usbd_video_close
+""""""""""""""""""""""""""""""""""""
+
+``usbd_video_close`` is used to stop video data transmission.
+
+.. code-block:: C
+
+    void usbd_video_open(uint8_t intf);
+
+- **intf** Interface number to close
+
+usbd_video_stream_start_write
+""""""""""""""""""""""""""""""""""""
+
+``usbd_video_stream_start_write`` is used to start sending one frame of video data stream. Must be used together with `usbd_video_stream_split_transfer`.
+
+.. code-block:: C
+
+    int usbd_video_stream_start_write(uint8_t busid, uint8_t ep, uint8_t *ep_buf, uint8_t *stream_buf, uint32_t stream_len, bool do_copy);
+
+- **busid** USB bus ID
+- **ep** Video data endpoint address
+- **ep_buf** Video data endpoint transfer buffer
+- **stream_buf** One frame video data source buffer
+- **stream_len** One frame video data source buffer size
+- **do_copy** Whether to copy stream_buf data to ep_buf. This parameter is false only when stream_buf is in nocache area and DCACHE_ENABLE is not enabled
+
+usbd_video_stream_split_transfer
+""""""""""""""""""""""""""""""""""""
+
+``usbd_video_stream_split_transfer`` is used to split video data stream transmission. Must be used together with `usbd_video_stream_start_write`.
+
+.. code-block:: C
+
+    int usbd_video_stream_split_transfer(uint8_t busid, uint8_t ep);
+
+- **busid** USB bus ID
+- **ep** Video data endpoint address
+- **return** Returns true when one frame data transmission is complete, false when data transmission is not complete
+
+RNDIS
+-----------------
+
+CDC ECM
+-----------------
+
+MTP
+-----------------

docs/en/api/api_host.rst

@@ -0,0 +1,317 @@
+Host Protocol Stack
+=======================================
+
+For the naming, classification, and member composition of structures in the host protocol stack, refer to the following two diagrams:
+
+.. figure:: img/api_host1.png
+.. figure:: img/api_host2.png
+
+CORE
+-----------------
+
+CLASS Driver Information Structure
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_class_info {
+        uint8_t match_flags;           /* Used for product specific matches; range is inclusive */
+        uint8_t bInterfaceClass;       /* Base device class code */
+        uint8_t bInterfaceSubClass;    /* Sub-class, depends on base class. Eg. */
+        uint8_t bInterfaceProtocol;    /* Protocol, depends on base class. Eg. */
+        const uint16_t (*id_table)[2]; /* List of Vendor/Product ID pairs */
+        const struct usbh_class_driver *class_driver;
+    };
+
+Endpoint Structure
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_endpoint {
+        struct usb_endpoint_descriptor ep_desc;
+    };
+
+Interface Altsetting Structure
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_interface_altsetting {
+        struct usb_interface_descriptor intf_desc;
+        struct usbh_endpoint ep[CONFIG_USBHOST_MAX_ENDPOINTS];
+    };
+
+Interface Structure
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_interface {
+        char devname[CONFIG_USBHOST_DEV_NAMELEN];
+        struct usbh_class_driver *class_driver;
+        void *priv;
+        struct usbh_interface_altsetting altsetting[CONFIG_USBHOST_MAX_INTF_ALTSETTINGS];
+        uint8_t altsetting_num;
+    };
+
+Configuration Structure
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_configuration {
+        struct usb_configuration_descriptor config_desc;
+        struct usbh_interface intf[CONFIG_USBHOST_MAX_INTERFACES];
+    };
+
+hubport Structure
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_hubport {
+        bool connected;   /* True: device connected; false: disconnected */
+        uint8_t port;     /* Hub port index */
+        uint8_t dev_addr; /* device address */
+        uint8_t speed;    /* device speed */
+        uint8_t depth;    /* distance from root hub */
+        uint8_t route;    /* route string */
+        uint8_t slot_id;  /* slot id */
+        struct usb_device_descriptor device_desc;
+        struct usbh_configuration config;
+        const char *iManufacturer;
+        const char *iProduct;
+        const char *iSerialNumber;
+        uint8_t *raw_config_desc;
+        struct usb_setup_packet *setup;
+        struct usbh_hub *parent;
+        struct usbh_hub *self; /* if this hubport is a hub */
+        struct usbh_bus *bus;
+        struct usb_endpoint_descriptor ep0;
+        struct usbh_urb ep0_urb;
+        usb_osal_mutex_t mutex;
+    };
+
+hub Structure
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: C
+
+    struct usbh_hub {
+        bool connected;
+        bool is_roothub;
+        uint8_t index;
+        uint8_t hub_addr;
+        uint8_t speed;
+        uint8_t nports;
+        uint8_t powerdelay;
+        uint8_t tt_think;
+        bool ismtt;
+        struct usb_hub_descriptor hub_desc; /* USB 2.0 only */
+        struct usb_hub_ss_descriptor hub_ss_desc; /* USB 3.0 only */
+        struct usbh_hubport child[CONFIG_USBHOST_MAX_EHPORTS];
+        struct usbh_hubport *parent;
+        struct usbh_bus *bus;
+        struct usb_endpoint_descriptor *intin;
+        struct usbh_urb intin_urb;
+        uint8_t *int_buffer;
+        struct usb_osal_timer *int_timer;
+    };
+
+usbh_initialize
+""""""""""""""""""""""""""""""""""""
+
+``usbh_initialize`` is used to initialize the USB host protocol stack, including: initializing the USB host controller, creating roothub device, creating hub detection thread.
+
+.. code-block:: C
+
+    int usbh_initialize(uint8_t busid, uint32_t reg_base, usbh_event_handler_t event_handler);
+
+- **busid**  bus id, starting from 0, cannot exceed `CONFIG_USBHOST_MAX_BUS`
+- **reg_base**  hcd register base address
+- **event_handler**  host event callback function, can be NULL
+- **return**  0 indicates normal, other values indicate error
+
+usbh_find_class_instance
+""""""""""""""""""""""""""""""""""""
+
+``usbh_find_class_instance`` finds the corresponding class structure handle based on the registered class name.
+
+.. code-block:: C
+
+    void *usbh_find_class_instance(const char *devname);
+
+- **devname**  class name
+- **return**  class structure handle
+
+lsusb
+""""""""""""""""""""""""""""""""""""
+
+``lsusb`` is used to view and operate device information on the hub. Requires shell plugin to use.
+
+.. code-block:: C
+
+    int lsusb(int argc, char **argv);
+
+SERIAL
+-----------------
+
+usbh_serial_open
+""""""""""""""""""""""""""""""""""""
+
+``usbh_serial_open`` opens a serial device according to the path.
+
+.. code-block:: C
+
+    struct usbh_serial *usbh_serial_open(const char *devname, uint32_t open_flags);
+
+- **devname**  serial path
+- **open_flags**  open flags, refer to `USBH_SERIAL_OFLAG_*` definitions
+- **return**  serial structure handle
+
+usbh_serial_close
+""""""""""""""""""""""""""""""""""""
+
+``usbh_serial_close`` closes the serial device.
+
+.. code-block:: C
+
+    void usbh_serial_close(struct usbh_serial *serial);
+
+- **serial**  serial structure handle
+
+usbh_serial_control
+""""""""""""""""""""""""""""""""""""
+
+``usbh_serial_control`` configures the serial port.
+
+.. code-block:: C
+
+    int usbh_serial_control(struct usbh_serial *serial, int cmd, void *arg);
+
+- **serial**  serial structure handle
+- **cmd**  control command, refer to `USBH_SERIAL_CMD_*` definitions
+- **arg**  control parameter pointer
+- **return**  0 indicates normal, other values indicate error
+
+usbh_serial_write
+""""""""""""""""""""""""""""""""""""
+
+``usbh_serial_write`` writes data to the serial port.
+
+.. code-block:: C
+
+    int usbh_serial_write(struct usbh_serial *serial, const void *buffer, uint32_t buflen);
+
+- **serial**  serial structure handle
+- **buffer**  data buffer pointer
+- **buflen**  length of data to write
+- **return**  actual length of data written or error code
+
+.. note:: If CONFIG_USB_DCACHE_ENABLE is not enabled, buffer needs to be in nocache area, otherwise it needs to be aligned to CONFIG_USB_ALIGN_SIZE area.
+
+usbh_serial_read
+""""""""""""""""""""""""""""""""""""
+
+``usbh_serial_read`` reads data from the serial port. **If baud rate is not set, this API is not allowed to be used. After setting baud rate, rx reception will be enabled internally and data will be written to ringbuf**.
+
+.. code-block:: C
+
+    int usbh_serial_read(struct usbh_serial *serial, void *buffer, uint32_t buflen);
+
+- **serial**  serial structure handle
+- **buffer**  data buffer pointer
+- **buflen**  maximum length of data to read
+- **return**  actual length of data read or error code
+
+.. note:: Since ringbuffer is used internally, there are no restrictions on user buffer attributes.
+
+usbh_serial_cdc_write_async
+""""""""""""""""""""""""""""""""""""
+
+``usbh_serial_cdc_write_async`` asynchronously writes data to the serial port. **If baud rate is set, this API is not allowed to be used**.
+
+.. code-block:: C
+
+    int usbh_serial_cdc_write_async(struct usbh_serial *serial, uint8_t *buffer, uint32_t buflen, usbh_complete_callback_t complete, void *arg);
+
+- **serial**  serial structure handle
+- **buffer**  data buffer pointer
+- **buflen**  length of data to send
+- **complete**  data write completion callback function
+- **arg**  callback function parameter
+- **return**  0 indicates normal, other values indicate error
+
+.. note:: If CONFIG_USB_DCACHE_ENABLE is not enabled, buffer needs to be in nocache area, otherwise it needs to be aligned to CONFIG_USB_ALIGN_SIZE area.
+
+usbh_serial_cdc_read_async
+""""""""""""""""""""""""""""""""""""
+
+``usbh_serial_cdc_read_async`` asynchronously reads data from the serial port. **If baud rate is set, this API is not allowed to be used. After setting baud rate, rx reception will be enabled internally and data will be written to ringbuf**.
+
+.. code-block:: C
+
+    int usbh_serial_cdc_read_async(struct usbh_serial *serial, uint8_t *buffer, uint32_t buflen, usbh_complete_callback_t complete, void *arg);
+
+- **serial**  serial structure handle
+- **buffer**  data buffer pointer
+- **buflen**  maximum length of data to read, up to 16K at a time. Must be a multiple of wMaxPacketSize
+- **complete**  data read completion callback function
+- **arg**  callback function parameter
+- **return**  0 indicates normal, other values indicate error
+
+.. note:: If CONFIG_USB_DCACHE_ENABLE is not enabled, buffer needs to be in nocache area, otherwise it needs to be aligned to CONFIG_USB_ALIGN_SIZE area.
+
+HID
+-----------------
+
+MSC
+-----------------
+
+usbh_msc_scsi_init
+""""""""""""""""""""""""""""""""""""
+
+``usbh_msc_scsi_init`` initializes msc scsi device. Gets MSC status and capacity information.
+
+.. code-block:: C
+
+    int usbh_msc_scsi_init(struct usbh_msc *msc_class);
+
+- **msc_class**  msc structure handle
+- **return**  0 indicates normal, other values indicate error
+
+usbh_msc_scsi_write10
+""""""""""""""""""""""""""""""""""""
+
+``usbh_msc_scsi_write10`` writes data to msc device.
+
+.. code-block:: C
+
+    int usbh_msc_scsi_write10(struct usbh_msc *msc_class, uint32_t start_sector, const uint8_t *buffer, uint32_t nsectors);
+
+- **msc_class**  msc structure handle
+- **start_sector**  starting sector
+- **buffer**  data buffer pointer
+- **nsectors**  number of sectors to write
+- **return**  returns 0 for normal, other values indicate error
+
+usbh_msc_scsi_read10
+""""""""""""""""""""""""""""""""""""
+
+``usbh_msc_scsi_read10`` reads data from msc device.
+
+.. code-block:: C
+
+    int usbh_msc_scsi_read10(struct usbh_msc *msc_class, uint32_t start_sector, uint8_t *buffer, uint32_t nsectors);
+
+- **msc_class**  msc structure handle
+- **start_sector**  starting sector
+- **buffer**  data buffer pointer
+- **nsectors**  number of sectors to read
+- **return**  returns 0 for normal, other values indicate error
+
+NETWORK
+-----------------
+
+Already integrated with lwIP protocol stack or other network protocol stacks, use socket API.

docs/en/api/api_port.rst

@@ -0,0 +1,266 @@
+Host and Device Drivers
+=======================================
+
+.. note:: Please note that starting from version v1.1, the busid parameter has been added, while everything else remains unchanged, so API documentation is not updated
+
+device controller(dcd)
+-------------------------
+
+usb_dc_init
+""""""""""""""""""""""""""""""""""""
+
+``usb_dc_init`` is used to initialize USB device controller registers, set USB pins, clock, interrupts, etc. **This function is not open to users**.
+
+.. code-block:: C
+
+    int usb_dc_init(void);
+
+- **return** Returns 0 for success, other values indicate error
+
+usb_dc_deinit
+""""""""""""""""""""""""""""""""""""
+
+``usb_dc_deinit`` is used to de-initialize USB device controller registers. **This function is not open to users**.
+
+.. code-block:: C
+
+    int usb_dc_deinit(void);
+
+- **return** Returns 0 for success, other values indicate error
+
+usbd_set_address
+""""""""""""""""""""""""""""""""""""
+
+``usbd_set_address`` sets the device address. **This function is not open to users**.
+
+.. code-block:: C
+
+    int usbd_set_address(const uint8_t addr);
+
+- **addr** Device address
+- **return** Returns 0 for success, other values indicate error
+
+usbd_ep_open
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_open`` sets endpoint properties and enables corresponding endpoint interrupts. **This function is not open to users**.
+
+.. code-block:: C
+
+    int usbd_ep_open(const struct usb_endpoint_descriptor *ep);
+
+- **ep** Endpoint descriptor
+- **return** Returns 0 for success, other values indicate error
+
+usbd_ep_close
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_close`` closes an endpoint. **This function is not open to users**.
+
+.. code-block:: C
+
+    int usbd_ep_close(const uint8_t ep);
+
+- **ep** Endpoint address
+- **return** Returns 0 for success, other values indicate error
+
+usbd_ep_set_stall
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_set_stall`` sets an endpoint to stall state and sends a stall handshake packet. **This function is open to users**.
+
+.. code-block:: C
+
+    int usbd_ep_set_stall(const uint8_t ep);
+
+- **ep** Endpoint address
+- **return** Returns 0 for success, other values indicate error
+
+usbd_ep_clear_stall
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_clear_stall`` clears the stall state of an endpoint. **This function is not open to users**.
+
+.. code-block:: C
+
+    int usbd_ep_clear_stall(const uint8_t ep);
+
+- **ep** Endpoint address
+- **return** Returns 0 for success, other values indicate error
+
+usbd_ep_is_stalled
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_is_stalled`` reads the current stall state of an endpoint. **This function is not open to users**.
+
+.. code-block:: C
+
+    int usbd_ep_is_stalled(const uint8_t ep, uint8_t *stalled);
+
+- **ep** Endpoint address
+- **return** Returns 1 for stalled, 0 for not stalled
+
+usbd_ep_start_write
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_start_write`` starts endpoint transmission. After transmission completion, it will call the registered IN endpoint transfer completion interrupt callback function. This function performs asynchronous transmission. **This function is open to users**.
+
+.. code-block:: C
+
+    int usbd_ep_start_write(const uint8_t ep, const uint8_t *data, uint32_t data_len);
+
+- **ep** IN endpoint address
+- **data** Transmission data buffer
+- **data_len** Transmission length, theoretically unlimited, recommended within 16K bytes
+- **return** Returns 0 for success, other values indicate error
+
+usbd_ep_start_read
+""""""""""""""""""""""""""""""""""""
+
+``usbd_ep_start_read`` starts endpoint reception. After reception completion, it will call the registered OUT endpoint transfer completion interrupt callback function. This function performs asynchronous reception. **This function is open to users**.
+
+.. code-block:: C
+
+    int usbd_ep_start_read(const uint8_t ep, uint8_t *data, uint32_t data_len);
+
+- **ep** OUT endpoint address
+- **data** Reception data buffer
+- **data_len** Reception length, theoretically unlimited, recommended within 16K bytes, and preferably a multiple of maximum packet size
+- **return** Returns 0 for success, other values indicate error
+
+.. note:: After starting reception, transfer completion interrupt will be triggered under two conditions: 1. Last packet is a short packet (less than EP MPS); 2. Total received length equals data_len
+
+.. note:: For bulk transfers, data_len is usually designed as EP MPS. The following three cases can be modified to multiple EP MPS: fixed length; custom protocol with length information (MSC); host manually sends ZLP or short packet (RNDIS)
+
+host controller(hcd)
+------------------------
+
+usb_hc_init
+""""""""""""""""""""""""""""""""""""
+
+``usb_hc_init`` is used to initialize USB host controller registers, set USB pins, clock, interrupts, etc. **This function is not open to users**.
+
+.. code-block:: C
+
+    int usb_hc_init(void);
+
+- **return** Returns 0 for success, other values indicate error
+
+usb_hc_deinit
+""""""""""""""""""""""""""""""""""""
+
+``usb_hc_deinit`` is used to de-initialize USB host controller registers. **This function is not open to users**.
+
+.. code-block:: C
+
+    int usb_hc_deinit(void);
+
+- **return** Returns 0 for success, other values indicate error
+
+usbh_roothub_control
+""""""""""""""""""""""""""""""""""""
+
+``usbh_roothub_control`` is used to send requests to the root hub. **This function is not open to users**.
+
+.. code-block:: C
+
+    int usbh_roothub_control(struct usb_setup_packet *setup, uint8_t *buf);
+
+- **setup** Request
+- **buf** Reception buffer
+- **return** Returns 0 for success, other values indicate error
+
+usbh_submit_urb
+""""""""""""""""""""""""""""""""""""
+
+``usbh_submit_urb`` performs data requests to endpoints at a specific address. **This function is open to users**.
+
+.. code-block:: C
+
+    int usbh_submit_urb(struct usbh_urb *urb);
+
+- **urb** USB request block
+- **return** Returns 0 for success, other values indicate error
+
+Among them, the `urb` structure information is as follows:
+
+.. code-block:: C
+
+    struct usbh_urb {
+        usb_slist_t list;
+        void *hcpriv;
+        struct usbh_hubport *hport;
+        struct usb_endpoint_descriptor *ep;
+        uint8_t data_toggle;
+        uint8_t interval;
+        struct usb_setup_packet *setup;
+        uint8_t *transfer_buffer;
+        uint32_t transfer_buffer_length;
+        int transfer_flags;
+        uint32_t actual_length;
+        uint32_t timeout;
+        int errorcode;
+        uint32_t num_of_iso_packets;
+        uint32_t start_frame;
+        usbh_complete_callback_t complete;
+        void *arg;
+    #if defined(__ICCARM__) || defined(__ICCRISCV__) || defined(__ICCRX__)
+        struct usbh_iso_frame_packet *iso_packet;
+    #else
+        struct usbh_iso_frame_packet iso_packet[0];
+    #endif
+    };
+
+- **hcpriv** Host controller driver private member
+- **hport** The hport used by current URB
+- **ep** The endpoint used by current URB
+- **data_toggle** Current data toggle
+- **interval** URB transfer interval in microseconds. If interval is greater than 1000us, software timer needs to be used for maintenance
+- **setup** Setup request buffer, used by endpoint 0
+- **transfer_buffer** Transfer data buffer
+- **transfer_buffer_length** Transfer length
+- **transfer_flags** Flags carried during transfer
+- **actual_length** Actual transfer length
+- **timeout** Transfer timeout. If 0, the function is non-blocking and can be used in interrupts
+- **errorcode** Error code
+- **num_of_iso_packets** Number of ISO frames or microframes
+- **complete** Transfer completion callback function
+- **arg** Parameters carried when transfer completes
+- **iso_packet** ISO data packet
+
+.. note:: If there are no special time requirements for timeout, it must be set to 0xffffffff. In principle, timeout is not allowed. If timeout occurs, generally cannot continue working
+
+`errorcode` can return the following values:
+
+.. code-block:: C
+
+  #define USB_ERR_NOMEM    1
+  #define USB_ERR_INVAL    2
+  #define USB_ERR_NODEV    3
+  #define USB_ERR_NOTCONN  4
+  #define USB_ERR_NOTSUPP  5
+  #define USB_ERR_BUSY     6
+  #define USB_ERR_RANGE    7
+  #define USB_ERR_STALL    8
+  #define USB_ERR_BABBLE   9
+  #define USB_ERR_NAK      10
+  #define USB_ERR_DT       11
+  #define USB_ERR_IO       12
+  #define USB_ERR_SHUTDOWN 13
+  #define USB_ERR_TIMEOUT  14
+
+Among them, the `iso_packet` structure information is as follows:
+
+.. code-block:: C
+
+  struct usbh_iso_frame_packet {
+      uint8_t *transfer_buffer;
+      uint32_t transfer_buffer_length;
+      uint32_t actual_length;
+      int errorcode;
+  };
+
+- **transfer_buffer** Transfer data buffer
+- **transfer_buffer_length** Transfer length
+- **actual_length** Actual transfer length
+- **errorcode** Error code

docs/en/class/class_audio.rst

@@ -0,0 +1,4 @@
+UAC
+=======================================
+
+Reference official audio-related PDFs

docs/en/class/class_cdc.rst

@@ -0,0 +1,4 @@
+CDC
+=======================================
+
+Reference official CDC-related PDFs

docs/en/class/class_hid.rst

@@ -0,0 +1,4 @@
+HID
+=======================================
+
+Reference official HID-related PDFs

docs/en/class/class_msc.rst

@@ -0,0 +1,4 @@
+MSC
+=======================================
+
+Reference official MSC-related PDFs

docs/en/class/class_video.rst

@@ -0,0 +1,4 @@
+UVC
+=======================================
+
+Reference official video-related PDFs

docs/en/class/winusb.rst

@@ -0,0 +1,2 @@
+WINUSB
+=======================================

docs/source/conf.py → docs/en/conf.py

@@ -3,7 +3,7 @@
 # -- Project information
 
 project = 'CherryUSB'
-copyright = '2022 ~ 2025, sakumisu'
+copyright = '2022 ~ 2026, sakumisu'
 author = 'sakumisu'
 
 release = '1.6.0'

docs/en/demo/usb_otg.rst

@@ -0,0 +1,14 @@
+USB OTG
+=================
+
+If you need to use OTG functionality, first the chip you're using needs to support ID detection capability, then enable the ``CONFIG_USB_OTG_ENABLE`` macro, and replace ``usbh_initialize`` or ``usbd_initialize`` in previous examples with ``usbotg_initialize``.
+
+The ID detection circuit varies depending on different USB interface types, with micro-USB and USB-C being the two common interface types.
+
+- If it's a micro-USB interface, connect the ID line to the chip's ID pin and enable the ID function.
+- If it's a USB-C interface, since there's no ID pin, you need to use CC circuit to convert to ID and then connect to the chip's ID pin. A common circuit diagram is shown below (DNP means Do Not Populate):
+
+.. figure:: img/otg.png
+
+
+.. note:: In addition to the ID pin, you also need to add VBUS output switch control. When working in host mode, enable VBUS power supply; when working in device mode, disable VBUS power supply.

docs/en/demo/usbd_adb.rst

@@ -0,0 +1,28 @@
+ADB Device
+=================
+
+The adb device demo refers to the `demo/adb/usbd_adb_template.c` template. It adapts to **cherrysh** (`platform/demo/adb/cherrysh_port.c`) and **rt-thread msh** (`platform/rtthread/usbd_adb_shell.c`) by default. You only need to add the following initialization in main.
+
+.. code-block:: C
+
+    cherryadb_init(0, xxxxx);
+
+If using rt-thread, you also need to enable adb device in menuconfig.
+
+.. figure:: img/rtt_adb_shell1.png
+
+Entering ADB
+--------------
+
+- When using **cherrysh**, automatically enters adb mode after enumeration is completed
+- When using **msh**, you need to input ``adb_enter`` in **msh** to enter adb mode
+
+Exiting ADB
+--------------
+
+- When using **cherrysh**, input ``exit`` to exit adb mode
+- When using **msh**, you need to input ``adb_exit`` in **msh** to exit adb mode
+
+.. figure:: img/cherryadb.png
+
+.. figure:: img/rtt_adb_shell2.png

docs/en/demo/usbd_audiov1.rst

@@ -0,0 +1,10 @@
+AudioV1 Device
+=================
+
+UAC1 demo refers to `demo/audio_v1_*.c` template.
+
+When using UAC1.0, pay attention to the following points:
+
+- When using Windows, when modifying any descriptor parameters, you must synchronously modify the string descriptor and uninstall the driver, otherwise Windows will consider the device unchanged and continue to use the old driver, causing device recognition failure. Linux is not subject to this restriction.
+- Download RemoveGhostDev64.exe from the QQ group files to automatically delete all USB registered driver information, eliminating the need for the first step
+- Prohibit adding print statements and time-consuming operations in interrupts, otherwise it will affect USB transmission according to interval

docs/en/demo/usbd_audiov2.rst

@@ -0,0 +1,10 @@
+AudioV2 Device
+=================
+
+When using UAC2.0, please note the following points:
+
+- On Windows, when modifying any parameter in the descriptor, the string descriptor must be modified synchronously and the driver must be uninstalled. Otherwise, Windows will think the device has not changed and continue to use the old driver, resulting in device recognition failure. Linux is not subject to this limitation.
+- You can download RemoveGhostDev64.exe from the QQ group files to automatically delete all USB registered driver information, eliminating the need for the first step
+- Windows 10 UAC2.0 functionality is incomplete, please use Windows 11 to test UAC2.0 functionality. Linux is not subject to this limitation
+- Windows has calculation errors in the sampling rate range setting for multi-channel (more than 2 channels). For example, if you set 8K~96K, the actual range is greater than or equal to 8K and less than 96K, not less than or equal to 96K. Linux is not subject to this limitation
+- Prohibit adding prints and time-consuming operations in interrupts, otherwise it will affect USB transmission according to interval

docs/en/demo/usbd_cdc_acm.rst

@@ -0,0 +1,104 @@
+CDC ACM Device
+=================
+
+This demo mainly demonstrates CDC ACM functionality. Reference the `demo/cdc_acm_template.c` template. Includes transmission/reception testing, DTR control, ZLP testing, and performance testing.
+
+- Allocate read/write buffers for data transmission/reception. Buffers need to be modified with nocache. Here we use 2048 bytes for both read and write for subsequent ZLP testing and performance testing.
+
+.. code-block:: C
+
+    USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t read_buffer[2048]; /* 2048 is only for test speed , please use CDC_MAX_MPS for common*/
+    USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t write_buffer[2048];
+
+
+- In the protocol stack event callback, we need to start the first transmission after enumeration is complete and clear the related flags. This can be done in the reset event or in the configured event.
+
+.. code-block:: C
+
+    static void usbd_event_handler(uint8_t busid, uint8_t event)
+    {
+        switch (event) {
+            case USBD_EVENT_RESET:
+                break;
+            case USBD_EVENT_CONNECTED:
+                break;
+            case USBD_EVENT_DISCONNECTED:
+                break;
+            case USBD_EVENT_RESUME:
+                break;
+            case USBD_EVENT_SUSPEND:
+                break;
+            case USBD_EVENT_CONFIGURED:
+                ep_tx_busy_flag = false;
+                /* setup first out ep read transfer */
+                usbd_ep_start_read(busid, CDC_OUT_EP, read_buffer, 2048);
+                break;
+            case USBD_EVENT_SET_REMOTE_WAKEUP:
+                break;
+            case USBD_EVENT_CLR_REMOTE_WAKEUP:
+                break;
+
+            default:
+                break;
+        }
+    }
+
+- Continue to initiate reception in the reception complete interrupt; determine whether to send ZLP in the transmission complete interrupt.
+
+.. code-block:: C
+
+    void usbd_cdc_acm_bulk_out(uint8_t busid, uint8_t ep, uint32_t nbytes)
+    {
+        USB_LOG_RAW("actual out len:%d\r\n", nbytes);
+        // for (int i = 0; i < 100; i++) {
+        //     printf("%02x ", read_buffer[i]);
+        // }
+        // printf("\r\n");
+        /* setup next out ep read transfer */
+        usbd_ep_start_read(busid, CDC_OUT_EP, read_buffer, 2048);
+    }
+
+    void usbd_cdc_acm_bulk_in(uint8_t busid, uint8_t ep, uint32_t nbytes)
+    {
+        USB_LOG_RAW("actual in len:%d\r\n", nbytes);
+
+        if ((nbytes % usbd_get_ep_mps(busid, ep)) == 0 && nbytes) {
+            /* send zlp */
+            usbd_ep_start_write(busid, CDC_IN_EP, NULL, 0);
+        } else {
+            ep_tx_busy_flag = false;
+        }
+    }
+
+- The following is for testing DTR functionality and controlling USB transmission. DTR and RTS are only used in conjunction with UART; for pure USB, they are not very useful - this is just for testing. DTR switch uses any serial port host computer and check DTR.
+
+.. code-block:: C
+
+    void usbd_cdc_acm_set_dtr(uint8_t busid, uint8_t intf, bool dtr)
+    {
+        if (dtr) {
+            dtr_enable = 1;
+        } else {
+            dtr_enable = 0;
+        }
+    }
+
+- Keep calling send in the main function
+
+.. code-block:: C
+
+    void cdc_acm_data_send_with_dtr_test(uint8_t busid)
+    {
+        if (dtr_enable) {
+            ep_tx_busy_flag = true;
+            usbd_ep_start_write(busid, CDC_IN_EP, write_buffer, 2048);
+            while (ep_tx_busy_flag) {
+            }
+        }
+    }
+
+- Note that we set the length to 2048 for testing ZLP functionality. In actual use, the receive length should use CDC_MAX_MPS. See :ref:`usb_ext` for specific reasons.
+- For performance testing, use tools/test_srcipts/test_cdc_speed.py and remove the print statements in `usbd_cdc_acm_bulk_out` and `usbd_cdc_acm_bulk_in` before testing, otherwise it will affect the test results.
+
+
+In addition, for CDC ACM with OS, we usually use asynchronous read and store data in a ringbuffer, and use synchronous write with semaphore.

docs/en/demo/usbd_ecm.rst

@@ -0,0 +1,4 @@
+CDC ECM Device
+=================
+
+ECM demo refers to the `demo/cdc_ecm*.c` template. By default it interfaces with lwip protocol stack, and the upper layer can use lwip api.

docs/en/demo/usbd_hid.rst

@@ -0,0 +1,4 @@
+HID Device
+=================
+
+HID functionality is relatively simple, so no detailed explanation is needed. Note that when using the HID custom example, it needs to be used with `tools/test_srcipts/test_hid_inout.py` (with report ID functionality).

docs/en/demo/usbd_msc.rst

@@ -0,0 +1,39 @@
+MSC Device
+=================
+
+This section mainly demonstrates USB mass storage device functionality. By default, RAM is used as storage medium to simulate a USB drive.
+
+- Implement read/write and capacity acquisition interfaces for the USB drive. Note that the capacity block_num is virtual - there aren't actually that many blocks. Read/write data exceeding BLOCK_COUNT will be discarded.
+
+block_size is generally 512/2048/4096.
+
+.. code-block:: C
+
+    void usbd_msc_get_cap(uint8_t busid, uint8_t lun, uint32_t *block_num, uint32_t *block_size)
+    {
+        *block_num = 1000; //Pretend having so many buffer,not has actually.
+        *block_size = BLOCK_SIZE;
+    }
+    int usbd_msc_sector_read(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length)
+    {
+        if (sector < BLOCK_COUNT)
+            memcpy(buffer, mass_block[sector].BlockSpace, length);
+        return 0;
+    }
+
+    int usbd_msc_sector_write(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length)
+    {
+        if (sector < BLOCK_COUNT)
+            memcpy(mass_block[sector].BlockSpace, buffer, length);
+        return 0;
+    }
+
+- By default, the above APIs execute in interrupt context. If you need to execute in non-interrupt context, you can choose the following:
+
+1. In bare metal, enable `CONFIG_USBDEV_MSC_POLLING` and call `usbd_msc_polling` in while1, then read/write functions execute in while1.
+
+2. In OS, enable `CONFIG_USBDEV_MSC_THREAD`, then read/write functions execute in thread.
+
+- Modifying `CONFIG_USBDEV_MSC_BUFSIZE` will affect U disk read/write speed. It must be an integer multiple of block_size, of course, it will also increase RAM usage.
+
+- If RAM example works but doesn't work after changing medium to SD or FLASH, it must be a medium driver problem.

docs/en/demo/usbd_mtp.rst

@@ -0,0 +1,6 @@
+MTP Device
+=================
+
+MTP demo references the `demo/mtp_template.c` template. Adapted for FatFS file system by default (`platform/fatfs/usbd_fatfs_mtp.c`).
+
+.. note:: MTP is commercially charged and does not provide open source MTP driver code. Please contact official support to purchase authorization.

docs/en/demo/usbd_rndis.rst

@@ -0,0 +1,4 @@
+CDC RNDIS Device
+=================
+
+RNDIS demo refers to `demo/cdc_rndis*.c` template. By default it interfaces with lwip protocol stack, the upper layer can use lwip api.

docs/en/demo/usbd_vendor.rst

@@ -0,0 +1,44 @@
+Writing Vendor Device Driver
+============================================
+
+This section mainly introduces how to write a vendor device driver.
+
+- First copy a class/template/usbd_xxx.c file
+- Implement the following three callback functions. Generally speaking, vendor drivers only need to implement vendor_handlerDevice 驱动编写
+
+.. code-block:: C
+
+    intf->class_interface_handler = xxx_class_interface_request_handler;
+    intf->class_endpoint_handler = NULL;
+    intf->vendor_handler = NULL;
+    intf->notify_handler = xxx_notify_handler;
+
+- Example as follows
+
+case1 demonstrates processing of host IN data, copying data to *data and specifying the length of *len. The protocol stack will automatically send to the host without requiring users to manually call send API.
+
+case2 demonstrates processing of host OUT data. When this function is executed, it means all data has been received and can directly read data from *data with length *len.
+
+.. code-block:: C
+
+    static int xxx_vendor_request_handler(uint8_t busid, struct usb_setup_packet *setup, uint8_t **data, uint32_t *len)
+    {
+        USB_LOG_WRN("XXX Class request: "
+                    "bRequest 0x%02x\r\n",
+                    setup->bRequest);
+
+        switch (setup->bRequest) {
+            case 1:
+            memcpy(*data, xxx, sizeof(xxx));
+            *len = sizeof(xxx);
+            case 2:
+            hexdump(*data, *len);
+            default:
+                USB_LOG_WRN("Unhandled XXX Class bRequest 0x%02x\r\n", setup->bRequest);
+                return -1;
+        }
+
+        return 0;
+    }
+
+- Finally register the interface using the form usbd_add_interface(busid, usbd_xxx_init_intf(&intf))

docs/en/demo/usbd_video.rst

@@ -0,0 +1,83 @@
+USB Video Device
+=================
+
+This section mainly demonstrates USB UVC functionality, supporting YUYV, MJPEG, H264 formats. For demonstration convenience, static images are used throughout.
+
+The demo includes **video_static_yuyv_template**, **video_static_mjpeg_template**, **video_static_h264_template**, with only descriptors and image data being different.
+
+- In high-speed mode, the default maximum is 1024 bytes, but if the chip supports additional transactions, it can be configured up to 2048 bytes or 3072 bytes, which can improve transmission efficiency.
+
+.. code-block:: C
+
+    #ifdef CONFIG_USB_HS
+    #define MAX_PAYLOAD_SIZE  1024 // for high speed with one transcations every one micro frame
+    #define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 1)) | (0x00 << 11))
+
+    // #define MAX_PAYLOAD_SIZE  2048 // for high speed with two transcations every one micro frame
+    // #define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 2)) | (0x01 << 11))
+
+    // #define MAX_PAYLOAD_SIZE  3072 // for high speed with three transcations every one micro frame
+    // #define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 3)) | (0x02 << 11))
+
+    #else
+    #define MAX_PAYLOAD_SIZE  1020
+    #define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 1)) | (0x00 << 11))
+    #endif
+
+- Usually only need to modify WIDTH and HEIGHT
+
+.. code-block:: C
+
+    #define WIDTH  (unsigned int)(640)
+    #define HEIGHT (unsigned int)(480)
+
+    #define CAM_FPS        (30)
+    #define INTERVAL       (unsigned long)(10000000 / CAM_FPS)
+    #define MIN_BIT_RATE   (unsigned long)(WIDTH * HEIGHT * 16 * CAM_FPS) //16 bit
+    #define MAX_BIT_RATE   (unsigned long)(WIDTH * HEIGHT * 16 * CAM_FPS)
+    #define MAX_FRAME_SIZE (unsigned long)(WIDTH * HEIGHT * 2)
+
+- USB endpoint configuration, default interval is 1, which is 1ms in full-speed mode and 125us in high-speed mode. Synchronization type uses asynchronous mode.
+
+.. code-block:: C
+
+    /* 1.2.2.2 Standard VideoStream Isochronous Video Data Endpoint Descriptor */
+    USB_ENDPOINT_DESCRIPTOR_INIT(VIDEO_IN_EP, 0x05, VIDEO_PACKET_SIZE, 0x01),
+
+
+- Use `usbd_video_stream_start_write` to transfer data. The final **do_copy** option indicates whether to copy data to packet_buffer.
+If copy is not selected, header information will be directly filled in the original image data and sent directly, achieving zero copy functionality.
+
+- Because static data is provided and cannot be modified, a new frame_buffer needs to be allocated for image transmission. In actual camera integration scenarios, dynamic data is used and the camera's data buffer can be used directly.
+
+
+.. code-block:: C
+
+    void usbd_video_iso_callback(uint8_t busid, uint8_t ep, uint32_t nbytes)
+    {
+        if (usbd_video_stream_split_transfer(busid, ep)) {
+            /* one frame has done */
+            iso_tx_busy = false;
+        }
+    }
+
+    USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t packet_buffer[MAX_PAYLOAD_SIZE];
+    USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t frame_buffer[32 * 1024];
+
+    void video_test(uint8_t busid)
+    {
+        memset(packet_buffer, 0, sizeof(packet_buffer));
+
+        while (1) {
+            if (tx_flag) {
+                iso_tx_busy = true;
+                memcpy(frame_buffer, cherryusb_mjpeg, sizeof(cherryusb_mjpeg)); // cherryusb_mjpeg is a static MJPEG frame buffer, so we need copy it to frame_buffer
+                usbd_video_stream_start_write(busid, VIDEO_IN_EP, packet_buffer, (uint8_t *)frame_buffer, sizeof(cherryusb_mjpeg), false);
+                while (iso_tx_busy) {
+                    if (tx_flag == 0) {
+                        break;
+                    }
+                }
+            }
+        }
+    }

docs/en/demo/usbd_webusb.rst

@@ -0,0 +1,21 @@
+WebUSB Device
+=================
+
+This demo mainly demonstrates webusb functionality. Webusb is mainly used to pop up web pages and access USB devices. The example uses webusb_hid_template.c.
+
+- When registering descriptors, just register BOS, MSOSV2, WEBUSB descriptors.
+
+.. code-block:: C
+
+    usbd_bos_desc_register(busid, &bos_desc);
+    usbd_msosv2_desc_register(busid, &msosv2_desc);
+    usbd_webusb_desc_register(busid, &webusb_url_desc);
+
+- Add an interface descriptor for webusb
+
+.. code-block:: C
+
+    USB_INTERFACE_DESCRIPTOR_INIT(USBD_WEBUSB_INTF_NUM, 0x00, 0x00, 0xff, 0x00, 0x00, 0x00)
+
+- The rest use hid descriptors, no further elaboration
+- After enumeration is completed, webpage information will pop up in the lower right corner of the computer, click to open the webpage

docs/en/demo/usbd_winusb.rst

@@ -0,0 +1,55 @@
+WinUSB Device
+=================
+
+This section mainly introduces the winusb driver. Winusb is a general driver provided by Windows to allow users to access USB custom class devices in a user-friendly manner. It is essentially CDC ACM, but without baud rate setting commands.
+WINUSB versions are divided into V1/V2 versions according to USB versions. V2 version requires BOS descriptor, while V1 version does not. **V2 version requires setting USB2.1 version number in device descriptor**.
+
+.. note:: Changing any winusb descriptor configuration may result in successful enumeration but inability to recognize the device. You need to delete all registry entries under Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\usbflags, then unplug and replug the device to take effect.
+
+- V1 version descriptor registration
+
+.. code-block:: C
+
+    const struct usb_descriptor winusbv1_descriptor = {
+        .device_descriptor_callback = device_descriptor_callback,
+        .config_descriptor_callback = config_descriptor_callback,
+        .device_quality_descriptor_callback = device_quality_descriptor_callback,
+        .string_descriptor_callback = string_descriptor_callback,
+        .msosv1_descriptor = &msosv1_desc
+    };
+
+    OR
+
+    usbd_msosv1_desc_register(busid, &msosv1_desc);
+
+- V2 version descriptor registration
+
+.. code-block:: C
+
+    const struct usb_descriptor winusbv2_descriptor = {
+        .device_descriptor_callback = device_descriptor_callback,
+        .config_descriptor_callback = config_descriptor_callback,
+        .device_quality_descriptor_callback = device_quality_descriptor_callback,
+        .string_descriptor_callback = string_descriptor_callback,
+        .msosv2_descriptor = &msosv2_desc,
+        .bos_descriptor = &bos_desc,
+    };
+
+    OR
+
+    usbd_bos_desc_register(busid, &bos_desc);
+    usbd_msosv2_desc_register(busid, &msosv2_desc);
+
+
+- Interface descriptor registration
+
+.. code-block:: C
+
+    /* Interface 0 */
+    USB_INTERFACE_DESCRIPTOR_INIT(0x00, 0x00, 0x02, 0xFF, 0x00, 0x00, 0x02),
+    /* Endpoint OUT 2 */
+    USB_ENDPOINT_DESCRIPTOR_INIT(WINUSB_OUT_EP, USB_ENDPOINT_TYPE_BULK, WINUSB_EP_MPS, 0x00),
+    /* Endpoint IN 1 */
+    USB_ENDPOINT_DESCRIPTOR_INIT(WINUSB_IN_EP, USB_ENDPOINT_TYPE_BULK, WINUSB_EP_MPS, 0x00),
+
+- Read and write operations are the same as CDC ACM, no further elaboration

docs/en/demo/usbh_audio.rst

@@ -0,0 +1,4 @@
+Audio Host
+=================
+
+.. note:: Host UAC is commercially charged. Please contact the official for purchase authorization.

docs/en/demo/usbh_bluetooth.rst

@@ -0,0 +1,2 @@
+BTBLE Host
+=================

docs/en/demo/usbh_hid.rst

@@ -0,0 +1,55 @@
+HID Host
+=================
+
+This section mainly introduces the use of Host HID class.
+
+- Create a one-time thread in HID enumeration completion callback
+
+.. code-block:: C
+
+
+    void usbh_hid_run(struct usbh_hid *hid_class)
+    {
+        usb_osal_thread_create("usbh_hid", 2048, CONFIG_USBHOST_PSC_PRIO + 1, usbh_hid_thread, hid_class);
+    }
+
+    void usbh_hid_stop(struct usbh_hid *hid_class)
+    {
+    }
+
+
+- Here we use the asynchronous operation of usbh_submit_urb, process data in interrupt and continue to receive next data.
+
+.. code-block:: C
+
+    static void usbh_hid_thread(void *argument)
+    {
+        int ret;
+        struct usbh_hid *hid_class = (struct usbh_hid *)argument;
+        ;
+
+        /* test with only one buffer, if you have more hid class, modify by yourself */
+
+        /* Suggest you to use timer for int transfer and use ep interval */
+        usbh_int_urb_fill(&hid_class->intin_urb, hid_class->hport, hid_class->intin, hid_buffer, hid_class->intin->wMaxPacketSize, 0, usbh_hid_callback, hid_class);
+        ret = usbh_submit_urb(&hid_class->intin_urb);
+        if (ret < 0) {
+            goto delete;
+        }
+        // clang-format off
+    delete:
+        usb_osal_thread_delete(NULL);
+        // clang-format on
+    }
+
+- Of course, you can also not use asynchronous operations, but use synchronous operations with timeout.
+- HID uses interrupt transfer, so normally we need to set a timer based on **bInterval** to trigger interrupt transfer at regular intervals. This is not used in the demo. If you have precise time requirements, you can choose to use a timer to trigger asynchronous sending.
+- Taking hub communication as an example, a one-time timer is used, but a periodic timer can also be used.
+
+.. code-block:: C
+
+    hub->int_timer = usb_osal_timer_create("hubint_tim", USBH_GET_URB_INTERVAL(hub->intin->bInterval, hport->speed) / 1000, hub_int_timeout, hub, 0);
+
+.. note::
+
+    Here `USBH_GET_URB_INTERVAL` is a macro definition used to calculate the URB transfer interval time based on binterval. The unit is us, while the timer minimum is ms, so it needs to be divided by 1000. For intervals less than or equal to 1ms, no timer is needed.

docs/en/demo/usbh_msc.rst

@@ -0,0 +1,56 @@
+MSC Host
+=================
+
+This section mainly introduces the use of Host MSC. Read and write functions are implemented with the help of FATFS.
+
+- Register a thread in the callback after MSC enumeration is completed, used for read and write operations.
+
+.. code-block:: C
+
+    void usbh_msc_run(struct usbh_msc *msc_class)
+    {
+        usb_osal_thread_create("usbh_msc", 2048, CONFIG_USBHOST_PSC_PRIO + 1, usbh_msc_thread, msc_class);
+    }
+
+    void usbh_msc_stop(struct usbh_msc *msc_class)
+    {
+    }
+
+
+- Without using fatfs, directly use usbh_msc_scsi_read10 or usbh_msc_scsi_write10 functions for read and write operations.
+- If using fatfs, you need to call fatfs interfaces in usbh_msc_thread for read and write operations. For MSC read/write adaptation to fatfs, refer to `platform/fatfs/usbh_fatfs.c`
+
+.. code-block:: C
+
+    static void usbh_msc_thread(void *argument)
+    {
+        int ret;
+        struct usbh_msc *msc_class = (struct usbh_msc *)argument;
+
+        /* test with only one buffer, if you have more msc class, modify by yourself */
+    #if 1
+        /* get the partition table */
+        ret = usbh_msc_scsi_read10(msc_class, 0, partition_table, 1);
+        if (ret < 0) {
+            USB_LOG_RAW("scsi_read10 error,ret:%d\r\n", ret);
+            goto delete;
+        }
+        for (uint32_t i = 0; i < 512; i++) {
+            if (i % 16 == 0) {
+                USB_LOG_RAW("\r\n");
+            }
+            USB_LOG_RAW("%02x ", partition_table[i]);
+        }
+        USB_LOG_RAW("\r\n");
+    #endif
+
+    #if TEST_USBH_MSC_FATFS
+        usb_msc_fatfs_test();
+    #endif
+        // clang-format off
+    delete:
+        usb_osal_thread_delete(NULL);
+        // clang-format on
+    }
+
+- Finally, after processing is completed or failed, delete the thread.

docs/en/demo/usbh_net.rst

@@ -0,0 +1,167 @@
+Network Host
+=================
+
+This section mainly introduces the use of Host USB network cards. The following USB ne- Because the USB network card has been internally connected to LWIP, users can directly use LWIP APIs without worrying about USB implementation.
+
+USB Network Card LWIP Configuration Macro Related Notes
+-----------------------------------------------------------
+
+**LWIP_TCPIP_CORE_LOCKING_INPUT** is used to not use lwip built-in tcpip thread, but use USB's own receive processing thread.
+
+**LWIP_TCPIP_CORE_LOCKING** is enabled by default in current lwip versions, and it is also recommended to be mandatory.
+
+**PBUF_POOL_BUFSIZE** is recommended to be greater than 1600, used with LWIP_TCPIP_CORE_LOCKING_INPUT, because we provide zero copy method using static pbuf instead of copying data into pbuf.
+
+**TCPIP_THREAD_STACKSIZE** is recommended to be greater than 1K to prevent stack overflow.are currently supported and tested:
+
+- 4G network cards: EC20(ECM/RNDIS), mobile phones (RNDIS), SIMCOM7600(RNDIS), ML307R(RNDIS), AIR780(RNDIS)
+
+.. caution:: Please note that some 4G network cards do not have auto-dial functionality by default. Please replace the firmware or use AT commands to configure auto-dial, otherwise you cannot get an IP.
+
+- USB Ethernet cards: ASIX AX88772, REALTEK RTL8152
+- USB WIFI cards: Bouffalo Lab BL616 (RNDIS/ECM)
+
+USB Network Card Related Macros and Files
+--------------------------------------------------
+
+The network card related macros are as follows, mainly used to register network card drivers according to different network components:
+
+.. code-block:: C
+
+    // #define CONFIG_USBHOST_PLATFORM_CDC_ECM
+    // #define CONFIG_USBHOST_PLATFORM_CDC_RNDIS
+    // #define CONFIG_USBHOST_PLATFORM_CDC_NCM
+    // #define CONFIG_USBHOST_PLATFORM_ASIX
+    // #define CONFIG_USBHOST_PLATFORM_RTL8152
+
+.. note:: If Kconfig system is used, the above macros are automatically generated. For other platforms, please define manually.
+
+USB network card transmission layer has been connected to relevant network components, listed as follows:
+
+- Custom OS + LWIP please use **platform/lwip/usbh_lwip.c**, need to include this file yourself and enable the above relevant macros. Call `tcpip_init(NULL, NULL)` before initializing USB
+- RT-THREAD + LWIP please use **platform/rtthread/usbh_lwip.c**, automatically select this file after enabling corresponding network card driver in Kconfig, automatically call `tcpip_init(NULL, NULL)` after selecting rt-thread lwip
+- ESP-IDF + LWIP please use **platform/freertos/usbh_net.c**, automatically select this file after enabling corresponding network card driver in Kconfig, and call `esp_netif_init()` + `esp_event_loop_create_default()` before initializing USB
+- NUTTX + NUTTX network component please use **platform/nuttx/usbh_net.c**, automatically select this file after enabling corresponding network card driver in Kconfig, automatically call after selecting network component
+
+.. note:: If adding code yourself, don't forget to add USB network card driver related source files, such as **class/usbh_cdc_ecm.c**. So we recommend using with corresponding platforms to save the trouble of adding files yourself
+
+USB Network Card Connection Process
+---------------------------------------------
+
+The following example shows the LWIP connection process.
+
+- After USB network card enumeration is completed, the `usbh_xxx_run` function will be **automatically** called, at which time netif driver is registered, and DHCP client and IP acquisition timer are started.
+
+.. code-block:: C
+
+    void usbh_cdc_ecm_run(struct usbh_cdc_ecm *cdc_ecm_class)
+    {
+        struct netif *netif = &g_cdc_ecm_netif;
+
+        netif->hwaddr_len = 6;
+        memcpy(netif->hwaddr, cdc_ecm_class->mac, 6);
+
+        IP4_ADDR(&g_ipaddr, 0, 0, 0, 0);
+        IP4_ADDR(&g_netmask, 0, 0, 0, 0);
+        IP4_ADDR(&g_gateway, 0, 0, 0, 0);
+
+        netif = netif_add(netif, &g_ipaddr, &g_netmask, &g_gateway, NULL, usbh_cdc_ecm_if_init, tcpip_input);
+        netif_set_default(netif);
+        while (!netif_is_up(netif)) {
+        }
+
+        dhcp_handle = usb_osal_timer_create("dhcp", 200, dhcp_timeout, netif, true);
+        if (dhcp_handle == NULL) {
+            USB_LOG_ERR("timer creation failed! \r\n");
+            while (1) {
+            }
+        }
+
+        usb_osal_thread_create("usbh_cdc_ecm_rx", 2048, CONFIG_USBHOST_PSC_PRIO + 1, usbh_cdc_ecm_rx_thread, NULL);
+    #if LWIP_DHCP
+        dhcp_start(netif);
+        usb_osal_timer_start(dhcp_handle);
+    #endif
+    }
+
+- `usbh_lwip_eth_output_common` is used to assemble transmitted pbuf into USB network card data packets
+- `usbh_lwip_eth_input_common` is used to assemble USB network card data into pbuf
+- Actual network card transmission and reception processing
+
+.. code-block:: C
+
+    static err_t usbh_cdc_ecm_linkoutput(struct netif *netif, struct pbuf *p)
+    {
+        int ret;
+        (void)netif;
+
+        usbh_lwip_eth_output_common(p, usbh_cdc_ecm_get_eth_txbuf());
+        ret = usbh_cdc_ecm_eth_output(p->tot_len);
+        if (ret < 0) {
+            return ERR_BUF;
+        } else {
+            return ERR_OK;
+        }
+    }
+
+    void usbh_cdc_ecm_eth_input(uint8_t *buf, uint32_t buflen)
+    {
+        usbh_lwip_eth_input_common(&g_cdc_ecm_netif, buf, buflen);
+    }
+
+- After the USB network card is unplugged, the `usbh_xxx_stop` function will be **automatically** called, at which time you need to stop the DHCP client, delete the timer, and remove the netif.
+
+.. code-block:: C
+
+    void usbh_cdc_ecm_stop(struct usbh_cdc_ecm *cdc_ecm_class)
+    {
+        struct netif *netif = &g_cdc_ecm_netif;
+        (void)cdc_ecm_class;
+
+    #if LWIP_DHCP
+        dhcp_stop(netif);
+        dhcp_cleanup(netif);
+        usb_osal_timer_delete(dhcp_handle);
+    #endif
+        netif_set_down(netif);
+        netif_remove(netif);
+    }
+
+- Because the USB network card has been internally connected to LWIP, users can directly use LWIP APIs without worrying about USB implementation.
+
+USB Network Card LWIP Configuration Macro Related Notes
+--------------------------------------------------------------
+
+**LWIP_TCPIP_CORE_LOCKING_INPUT** is used to not use lwip built-in tcpip thread, but use USB's own receive processing thread.
+
+**LWIP_TCPIP_CORE_LOCKING** is enabled by default in current lwip versions, and it is also recommended to be mandatory.
+
+**PBUF_POOL_BUFSIZE** is recommended to be greater than 1600, used with LWIP_TCPIP_CORE_LOCKING_INPUT, because we provide zero copy method using static pbuf instead of copying data into pbuf.
+
+**TCPIP_THREAD_STACKSIZE** is recommended to be greater than 1K to prevent stack overflow.
+
+.. code-block:: C
+
+    #if LWIP_TCPIP_CORE_LOCKING_INPUT != 1
+    #warning suggest you to set LWIP_TCPIP_CORE_LOCKING_INPUT to 1, usb handles eth input with own thread
+    #endif
+
+    #if LWIP_TCPIP_CORE_LOCKING != 1
+    #error must set LWIP_TCPIP_CORE_LOCKING to 1
+    #endif
+
+    #if PBUF_POOL_BUFSIZE < 1600
+    #error PBUF_POOL_BUFSIZE must be larger than 1600
+    #endif
+
+    #if TCPIP_THREAD_STACKSIZE < 1024
+    #error TCPIP_THREAD_STACKSIZE must be >= 1024
+    #endif
+
+
+Summary
+--------------
+
+.. note:: Through the above content, we can see that CherryUSB's support for USB network cards is very comprehensive. Users only need to enable corresponding macros or check options to achieve automatic recognition and driver registration of USB network cards, without manually initializing network card related configurations. Users only need to focus on the application layer, which greatly facilitates user usage.
+
+For specific porting articles, please refer to developers' notes https://club.rt-thread.org/ask/article/5cf3e9e0b2d95800.html

docs/en/demo/usbh_serial.rst

@@ -0,0 +1,196 @@
+Serial Host
+=================
+
+This section mainly introduces the usage of the Host serial framework. The Serial framework currently supports CDC ACM, FTDI, CP210x, CH34x, PL2303, and GSM drivers.
+
+.. figure:: img/usbh_serial.png
+
+Currently supports two usage methods: one is using native CherryUSB usbhost serial API for operations, and the other is based on platform-wrapped APIs such as RT-Thread device API and NuttX POSIX API.
+
+The following demonstrates using CherryUSB usbhost serial API for serial loopback testing with blocking transmission and asynchronous reception:
+
+.. code-block:: C
+
+    struct usbh_serial *serial;
+
+    serial = usbh_serial_open("/dev/ttyACM0", USBH_SERIAL_O_RDWR | USBH_SERIAL_O_NONBLOCK);
+    if (serial == NULL) {
+        serial = usbh_serial_open("/dev/ttyUSB0", USBH_SERIAL_O_RDWR | USBH_SERIAL_O_NONBLOCK);
+        if (serial == NULL) {
+            USB_LOG_RAW("no serial device found\r\n");
+            goto delete;
+        }
+    }
+
+    struct usbh_serial_termios termios;
+
+    memset(&termios, 0, sizeof(termios));
+    termios.baudrate = 115200;
+    termios.stopbits = 0;
+    termios.parity = 0;
+    termios.databits = 8;
+    termios.rtscts = false;
+    termios.rx_timeout = 0;
+    ret = usbh_serial_control(serial, USBH_SERIAL_CMD_SET_ATTR, &termios);
+    if (ret < 0) {
+        USB_LOG_RAW("set serial attr error, ret:%d\r\n", ret);
+        goto delete_with_close;
+    }
+
+    serial_tx_bytes = 0;
+    while (1) {
+        ret = usbh_serial_write(serial, serial_tx_buffer, sizeof(serial_tx_buffer));
+        if (ret < 0) {
+            USB_LOG_RAW("serial write error, ret:%d\r\n", ret);
+            goto delete_with_close;
+        } else {
+            serial_tx_bytes += ret;
+
+            if (serial_tx_bytes == SERIAL_TEST_LEN) {
+                USB_LOG_RAW("send over\r\n");
+                break;
+            }
+        }
+    }
+
+    volatile uint32_t wait_timeout = 0;
+    serial_rx_bytes = 0;
+    while (1) {
+        ret = usbh_serial_read(serial, &serial_rx_data[serial_rx_bytes], SERIAL_TEST_LEN - serial_rx_bytes);
+        if (ret < 0) {
+            USB_LOG_RAW("serial read error, ret:%d\r\n", ret);
+            goto delete_with_close;
+        } else {
+            serial_rx_bytes += ret;
+
+            if (serial_rx_bytes == SERIAL_TEST_LEN) {
+                USB_LOG_RAW("receive over\r\n");
+                for (uint32_t i = 0; i < SERIAL_TEST_LEN; i++) {
+                    if (serial_rx_data[i] != 0xa5) {
+                        USB_LOG_RAW("serial loopback data error at index %d, data: 0x%02x\r\n", (unsigned int)i, serial_rx_data[i]);
+                        goto delete_with_close;
+                    }
+                }
+                serial_test_success = true;
+                break;
+            }
+        }
+        wait_timeout++;
+
+        if (wait_timeout > 500) { // 5s
+            USB_LOG_RAW("serial read timeout\r\n");
+            goto delete_with_close;
+        }
+
+        usb_osal_msleep(10);
+    }
+
+    usbh_serial_close(serial);
+
+.. caution:: Note that the example uses a simple send-then-read approach, so the total length sent cannot exceed CONFIG_USBHOST_SERIAL_RX_SIZE. For normal TX/RX usage, please perform them separately.
+
+Users need to consider the following three scenarios:
+
+- USB2TTL device + baud rate enabled (USB2TTL devices must enable baud rate), in this case you need to use `usbh_serial_write` and `usbh_serial_read` to send and receive data, **and read operations need to be timely to prevent ringbuf data overflow and packet loss**. Cannot use `usbh_serial_cdc_write_async` and `usbh_serial_cdc_read_async`
+
+- Pure USB device + baud rate not started, in this case you can use `usbh_serial_cdc_write_async` and `usbh_serial_cdc_read_async` for asynchronous send/receive data. For blocking, you can use `usbh_serial_write`, but cannot use `usbh_serial_read`.
+
+- Pure USB device + baud rate started, same as 1, but the reception rate will be discounted (because of an extra layer of ringbuf). In this case, `usbh_serial_cdc_write_async` and `usbh_serial_cdc_read_async` cannot be used either. **If it is a GSM device, please use the first scenario**.
+
+.. note:: Simply put, if receiving data requires going through a ringbuf layer, please use the first scenario.
+
+.. code-block:: C
+
+    [I/usbh_hub] New full-speed device on Bus 0, Hub 1, Port 1 connected
+    [I/usbh_core] New device found,idVendor:10c4,idProduct:ea60,bcdDevice:0100
+    [I/usbh_core] The device has 1 bNumConfigurations
+    [I/usbh_core] The device has 1 interfaces
+    [I/usbh_core] Enumeration success, start loading class driver
+    [I/usbh_core] Loading cp210x class driver on interface 0
+    [I/usbh_cp210x] chip partnum: 0x02
+    [I/usbh_cp210x] ulAmountInInQueue: 0, ulAmountInOutQueue: 0
+    [I/usbh_serial] Ep=81 Attr=02 Mps=64 Interval=00 Mult=00
+    [I/usbh_serial] Ep=01 Attr=02 Mps=64 Interval=00 Mult=00
+    [I/usbh_serial] Register Serial Class: /dev/ttyUSB0 (cp210x)
+    start serial loopback test, len: 1024
+    send over
+    receive over
+    serial loopback test success
+    [I/usbh_serial] Unregister Serial Class: /dev/ttyUSB0 (cp210x)
+    [I/usbh_core] Device on Bus 0, Hub 1, Port 1 disconnected
+    [I/usbh_hub] New high-speed device on Bus 0, Hub 1, Port 1 connected
+    [I/usbh_core] New device found,idVendor:0403,idProduct:6010,bcdDevice:0700
+    [I/usbh_core] The device has 1 bNumConfigurations
+    [I/usbh_core] The device has 2 interfaces
+    [I/usbh_core] Enumeration success, start loading class driver
+    [I/usbh_core] Loading ftdi class driver on interface 0
+    [I/usbh_ftdi] chip name: FT2232H
+    [I/usbh_serial] Ep=81 Attr=02 Mps=512 Interval=00 Mult=00
+    [I/usbh_serial] Ep=02 Attr=02 Mps=512 Interval=00 Mult=00
+    [I/usbh_serial] Register Serial Class: /dev/ttyUSB0 (ftdi)
+    [I/usbh_core] Loading ftdi class driver on interface 1
+    [I/usbh_ftdi] chip name: FT2232H
+    [I/usbh_serial] Ep=83 Attr=02 Mps=512 Interval=00 Mult=00
+    [I/usbh_serial] Ep=04 Attr=02 Mps=512 Interval=00 Mult=00
+    [I/usbh_serial] Register Serial Class: /dev/ttyUSB1 (ftdi)
+    start serial loopback test, len: 1024
+    send over
+    receive over
+    serial loopback test success
+    [I/usbh_serial] Unregister Serial Class: /dev/ttyUSB0 (ftdi)
+    [I/usbh_serial] Unregister Serial Class: /dev/ttyUSB1 (ftdi)
+    [I/usbh_core] Device on Bus 0, Hub 1, Port 1 disconnected
+    [I/usbh_hub] New full-speed device on Bus 0, Hub 1, Port 1 connected
+    [I/usbh_core] New device found,idVendor:067b,idProduct:2303,bcdDevice:0300
+    [I/usbh_core] The device has 1 bNumConfigurations
+    [I/usbh_core] The device has 1 interfaces
+    [I/usbh_core] Enumeration success, start loading class driver
+    [I/usbh_core] Loading pl2303 class driver on interface 0
+    [I/usbh_pl2303] Ep=81 Attr=03 Mps=10 Interval=01 Mult=00
+    [I/usbh_pl2303] chip type: PL2303HX
+    [I/usbh_serial] Ep=02 Attr=02 Mps=64 Interval=00 Mult=00
+    [I/usbh_serial] Ep=83 Attr=02 Mps=64 Interval=00 Mult=00
+    [I/usbh_serial] Register Serial Class: /dev/ttyUSB0 (pl2303)
+    start serial loopback test, len: 1024
+    send over
+    receive over
+    serial loopback test success
+    [I/usbh_serial] Unregister Serial Class: /dev/ttyUSB0 (pl2303)
+    [I/usbh_core] Device on Bus 0, Hub 1, Port 1 disconnected
+    [W/usbh_hub] Failed to enable port 1
+    [I/usbh_hub] New full-speed device on Bus 0, Hub 1, Port 1 connected
+    [I/usbh_core] New device found,idVendor:1a86,idProduct:7523,bcdDevice:0264
+    [I/usbh_core] The device has 1 bNumConfigurations
+    [I/usbh_core] The device has 1 interfaces
+    [I/usbh_core] Enumeration success, start loading class driver
+    [I/usbh_core] Loading ch34x class driver on interface 0
+    [I/usbh_ch43x] Ep=81 Attr=03 Mps=8 Interval=01 Mult=00
+    [I/usbh_ch43x] chip version: 0x31
+    [I/usbh_serial] Ep=82 Attr=02 Mps=32 Interval=00 Mult=00
+    [I/usbh_serial] Ep=02 Attr=02 Mps=32 Interval=00 Mult=00
+    [I/usbh_serial] Register Serial Class: /dev/ttyUSB0 (ch34x)
+    start serial loopback test, len: 1024
+    send over
+    receive over
+    serial loopback test success
+    [I/usbh_serial] Unregister Serial Class: /dev/ttyUSB0 (ch34x)
+    [I/usbh_core] Device on Bus 0, Hub 1, Port 1 disconnected
+    [I/usbh_hub] New full-speed device on Bus 0, Hub 1, Port 1 connected
+    [I/usbh_core] New device found,idVendor:42bf,idProduct:b210,bcdDevice:0217
+    [I/usbh_core] The device has 1 bNumConfigurations
+    [I/usbh_core] The device has 3 interfaces
+    [I/usbh_core] Enumeration success, start loading class driver
+    [E/usbh_core] Do not support Class:0xff, Subclass:0x01, Protocl:0x00 on interface 0
+    [I/usbh_core] Loading cdc_acm class driver on interface 1
+    [I/usbh_cdc_acm] Ep=85 Attr=03 Mps=64 Interval=00 Mult=00
+    [I/usbh_serial] Ep=04 Attr=02 Mps=64 Interval=00 Mult=00
+    [I/usbh_serial] Ep=83 Attr=02 Mps=64 Interval=00 Mult=00
+    [I/usbh_serial] Register Serial Class: /dev/ttyACM0 (cdc_acm)
+    [I/usbh_core] Loading cdc_data class driver on interface 2
+    start serial loopback test, len: 1024
+    send over
+    receive over
+    serial loopback test success
+    [I/usbh_serial] Unregister Serial Class: /dev/ttyACM0 (cdc_acm)
+    [I/usbh_core] Device on Bus 0, Hub 1, Port 1 disconnected
+

docs/en/demo/usbh_vendor.rst

@@ -0,0 +1,127 @@
+Writing Vendor Host Driver
+============================================
+
+This section mainly introduces how to write a vendor host driver.
+
+- First copy a class/template/usbh_xxx.c file
+
+- Define class driver and use CLASS_INFO_DEFINE prefix, so that after enumeration is completed, the protocol stack automatically finds the corresponding driver through usbd_class_find_driver.
+
+.. code-block:: C
+
+    static const struct usbh_class_driver xxx_class_driver = {
+        .driver_name = "xxx",
+        .connect = usbh_xxx_connect,
+        .disconnect = usbh_xxx_disconnect
+    };
+
+    CLASS_INFO_DEFINE const struct usbh_class_info xxx_class_info = {
+        .match_flags = USB_CLASS_MATCH_INTF_CLASS | USB_CLASS_MATCH_INTF_SUBCLASS | USB_CLASS_MATCH_INTF_PROTOCOL,
+        .bInterfaceClass = 0,
+        .bInterfaceSubClass = 0,
+        .bInterfaceProtocol = 0,
+        .id_table = NULL,
+        .class_driver = &xxx_class_driver
+    };
+
+
+- Implement connect and disconnect functions. In the connect function, you need to allocate an xxx_class structure. In the disconnect function, release the urb and xxx_class.
+
+.. code-block:: C
+
+    struct usbh_xxx {
+        struct usbh_hubport *hport;
+        struct usb_endpoint_descriptor *xxxin;
+        struct usb_endpoint_descriptor *xxxout;
+        struct usbh_urb xxxin_urb;
+        struct usbh_urb xxxout_urb;
+
+        uint8_t intf; /* interface number */
+        uint8_t minor;
+
+        void *user_data;
+    };
+
+    static int usbh_xxx_connect(struct usbh_hubport *hport, uint8_t intf)
+    {
+        struct usb_endpoint_descriptor *ep_desc;
+        int ret;
+
+        struct usbh_xxx *xxx_class = usbh_xxx_class_alloc();
+        if (xxx_class == NULL) {
+            USB_LOG_ERR("Fail to alloc xxx_class\r\n");
+            return -USB_ERR_NOMEM;
+        }
+
+        return ret;
+    }
+
+
+    static int usbh_xxx_disconnect(struct usbh_hubport *hport, uint8_t intf)
+    {
+        int ret = 0;
+
+        struct usbh_xxx *xxx_class = (struct usbh_xxx *)hport->config.intf[intf].priv;
+
+        if (xxx_class) {
+            if (xxx_class->xxxin) {
+                usbh_kill_urb(&xxx_class->xxxin_urb);
+            }
+
+            if (xxx_class->xxxout) {
+                usbh_kill_urb(&xxx_class->xxxout_urb);
+            }
+
+            if (hport->config.intf[intf].devname[0] != '\0') {
+                USB_LOG_INFO("Unregister xxx Class:%s\r\n", hport->config.intf[intf].devname);
+                usbh_xxx_stop(xxx_class);
+            }
+
+            usbh_xxx_class_free(xxx_class);
+        }
+
+        return ret;
+    }
+
+- Initialize endpoints
+
+.. code-block:: C
+
+        for (uint8_t i = 0; i < hport->config.intf[intf].altsetting[0].intf_desc.bNumEndpoints; i++) {
+        ep_desc = &hport->config.intf[intf].altsetting[0].ep[i].ep_desc;
+        if (ep_desc->bEndpointAddress & 0x80) {
+            USBH_EP_INIT(xxx_class->intin, ep_desc);
+        } else {
+            USBH_EP_INIT(xxx_class->intout, ep_desc);
+        }
+    }
+
+- Finally design send/receive APIs, design them as synchronous or asynchronous according to actual conditions.
+
+.. code-block:: C
+
+    int usbh_xxx_in_transfer(struct usbh_xxx *xxx_class, uint8_t *buffer, uint32_t buflen, uint32_t timeout)
+    {
+        int ret;
+        struct usbh_urb *urb = &xxx_class->xxxin_urb;
+
+        usbh_xxx_urb_fill(urb, xxx_class->hport, xxx_class->xxxin, buffer, buflen, timeout, NULL, NULL);
+        ret = usbh_submit_urb(urb);
+        if (ret == 0) {
+            ret = urb->actual_length;
+        }
+        return ret;
+    }
+
+    int usbh_xxx_out_transfer(struct usbh_xxx *xxx_class, uint8_t *buffer, uint32_t buflen, uint32_t timeout)
+    {
+        int ret;
+        struct usbh_urb *urb = &xxx_class->xxxout_urb;
+
+        usbh_xxx_urb_fill(urb, xxx_class->hport, xxx_class->xxxout, buffer, buflen, timeout, NULL, NULL);
+        ret = usbh_submit_urb(urb);
+        if (ret == 0) {
+            ret = urb->actual_length;
+        }
+        return ret;
+    }

docs/en/demo/usbh_video.rst

@@ -0,0 +1,4 @@
+Video Host
+=================
+
+.. note:: Host UVC is commercially charged. Please contact official support to purchase authorization.

docs/en/demo/usbh_wifi.rst

@@ -0,0 +1,2 @@
+WIFI Host
+=================

docs/en/index.rst

@@ -0,0 +1,160 @@
+.. CherryUSB User Guide documentation master file, created by
+   sphinx-quickstart on Thu Nov 21 10:50:33 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+CherryUSB User Guide
+====================================================================
+
+CherryUSB is a small, lightweight, portable USB host and device protocol stack for embedded systems. CherryUSB offers the following advantages:
+
+**Easy to Learn USB**
+
+To facilitate user learning of USB fundamentals, enumeration, driver loading, and IP drivers, the written code has the following advantages:
+
+- Streamlined code with simple logic and no complex C language syntax
+- Tree-structured programming with progressive code layers
+- Templated and simplified Class drivers and porting drivers
+- Clear API categorization (Device: initialization, class registration, command callbacks, data transmission; Host: initialization, class discovery, data transmission)
+
+**Easy to Use USB**
+
+To facilitate user interaction with USB interfaces, considering users' familiarity with UART and DMA, the designed data transmission interface has the following advantages:
+
+- Equivalent to using UART TX DMA/UART RX DMA
+- No length restrictions on transmission/reception; users don't need to worry about USB packetization (porting drivers handle packetization)
+
+**Easy to Achieve USB Performance**
+
+Considering USB performance requirements to reach theoretical USB hardware bandwidth, the designed data transmission interface has the following advantages:
+
+- Porting drivers directly interface with registers without abstraction layer encapsulation
+- Memory zero copy
+- DMA mode used when IP supports DMA (DMA provides hardware packetization functionality)
+- No length restrictions, facilitating hardware DMA interfacing and maximizing DMA advantages
+- Packetization handled in interrupt context
+
+**Device Protocol Stack Overall Execution Flow**
+
+.. figure:: usbdev.svg
+
+**Host Protocol Stack Overall Execution Flow**
+
+.. figure:: usbhost.svg
+
+**Other Related Links**
+
+- **Video Tutorial**:  https://www.bilibili.com/cheese/play/ss707687201
+- **GitHub**: https://github.com/sakumisu/CherryUSB
+- **CherryUSB Theoretical Analysis and Application Practice - Hans Journal**: https://www.hanspub.org/journal/paperinformation?paperid=126903
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Quick Start
+
+   quick_start/start
+   quick_start/demo
+   quick_start/transplant
+   quick_start/rtthread
+   quick_start/q&a
+   quick_start/migration
+   quick_start/share
+   quick_start/opensource
+
+.. toctree::
+   :maxdepth: 1
+   :caption: USB Basic Knowledge
+
+   usb/usb2.0_basic
+   usb/usb3.0_basic
+   usb/usb_desc
+   usb/usb_request
+   usb/usb_enum
+   usb/usb_ext
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API Manual
+
+   api/api_device
+   api/api_host
+   api/api_port
+   api/api_config
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Class Guide
+
+   class/class_cdc
+   class/class_hid
+   class/class_msc
+   class/class_audio
+   class/class_video
+   class/winusb
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Examples
+
+   demo/usbd_cdc_acm
+   demo/usbd_hid
+   demo/usbd_msc
+   demo/usbd_audiov1
+   demo/usbd_audiov2
+   demo/usbd_video
+   demo/usbd_winusb
+   demo/usbd_webusb
+   demo/usbd_rndis
+   demo/usbd_ecm
+   demo/usbd_adb
+   demo/usbd_mtp
+   demo/usbh_serial
+   demo/usbh_hid
+   demo/usbh_msc
+   demo/usbh_net
+   demo/usbh_bluetooth
+   demo/usbh_wifi
+   demo/usbh_audio
+   demo/usbh_video
+   demo/usb_otg
+   demo/usbd_vendor
+   demo/usbh_vendor
+
+.. toctree::
+   :maxdepth: 1
+   :caption: USB IP Introduction
+
+   usbip/ohci
+   usbip/ehci
+   usbip/xhci
+   usbip/chipidea
+   usbip/dwc2
+   usbip/musb
+   usbip/fotg210
+   usbip/cdns2
+   usbip/cdns3
+   usbip/dwc3
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Tools Usage
+
+   tools/index
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Version Information
+
+   version
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Performance Showcase
+
+   show/index
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Commercial Support
+
+   support/index

docs/en/quick_start/demo.rst

@@ -0,0 +1,313 @@
+Quick Verification Based on Existing Demos
+=============================================
+
+Before learning USB or CherryUSB code, we need to quickly verify based on existing demos. Why? To enhance interest in USB and build confidence for the next steps. If demos can't run, or if you explore writing code by yourself, or read USB basic concepts first, you may find that you can't understand anything in the end - there are so many concepts that you simply can't remember them, thus losing interest in USB. Therefore, running demos first is very important. Below I will list the currently supported demo repositories.
+
+Based on Bouffalolab Series Chips (Official SDK Support)
+--------------------------------------------------------------
+
+.. list-table::
+    :widths: 10 10 10
+    :header-rows: 1
+
+    * - Repo url
+      - USB IP
+      - Version
+    * - https://github.com/CherryUSB/cherryusb_bouffalolab
+      - FOTG210
+      - less than latest
+
+Based on HPMicro Series Chips (Official SDK Support)
+-----------------------------------------------------
+
+.. list-table::
+    :widths: 10 10 10
+    :header-rows: 1
+
+    * - Repo url
+      - USB IP
+      - Version
+    * - https://github.com/CherryUSB/cherryusb_hpmicro
+      - CHIPIDEA
+      - less than latest
+
+Based on esp32s2/s3/p4 Series Chips (Official SDK Support)
+-------------------------------------------------------------------------------
+
+.. list-table::
+    :widths: 10 10 10
+    :header-rows: 1
+
+    * - Repo url
+      - USB IP
+      - Version
+    * - https://github.com/CherryUSB/cherryusb_esp32
+      - DWC2
+      - less than latest
+
+Default demo uses component library installation form, can be searched at https://components.espressif.com/ for cherryusb
+
+ESP-Registry can refer to the official documentation, recommended to use vscode + esp-idf development environment.
+
+- ctrl + shift + p select ESP-IDF welcome interface, then select Component manager
+
+.. figure:: img/esp1.png
+
+- Find cherryusb and install
+
+.. figure:: img/esp2.png
+
+- Open menuconfig, and open cherryusb configuration, select host or device mode according to actual situation
+
+.. figure:: img/esp3.png
+.. figure:: img/esp4.png
+
+Based on Phytium Series Chips (Official SDK Support)
+-------------------------------------------------------
+
+.. list-table::
+    :widths: 10 10 10
+    :header-rows: 1
+
+    * - Repo url
+      - USB IP
+      - Version
+    * - https://gitee.com/phytium_embedded/phytium-free-rtos-sdk
+      - PUSB2/XHCI
+      - equal to v1.4.0
+
+Based on Essemi Series Chips (Official SDK Support)
+-------------------------------------------------------------
+
+.. list-table::
+    :widths: 10 10 10
+    :header-rows: 1
+
+    * - Repo url
+      - USB IP
+      - Version
+    * - https://github.com/CherryUSB/cherryusb_es32
+      - MUSB
+      - less than latest
+
+Based on Artinchip Series Chips (Official SDK Support)
+-------------------------------------------------------------------
+
+.. list-table::
+    :widths: 10 10 10
+    :header-rows: 1
+
+    * - Repo url
+      - USB IP
+      - Version
+    * - https://gitee.com/artinchip/luban-lite
+      - AIC/EHCI/OHCI
+      - less than latest
+
+Based on Kendryte canmv-k230 Chip (Official SDK Support)
+---------------------------------------------------------
+
+.. list-table::
+    :widths: 10 10 10
+    :header-rows: 1
+
+    * - Repo url
+      - USB IP
+      - Version
+    * - https://github.com/CherryUSB/k230_sdk
+      - DWC2
+      - less than latest
+
+Based on NXP MCX Series Chips
+-------------------------------------
+
+.. list-table::
+    :widths: 10 10 10
+    :header-rows: 1
+
+    * - Repo url
+      - USB IP
+      - Version
+    * - https://github.com/CherryUSB/cherryusb_mcx  https://github.com/RT-Thread/rt-thread/tree/master/bsp/nxp/mcx
+      - CHIPIDEA/kinetis
+      - less than latest
+
+Based on SiFli SF32 Series Chips (Official SDK Support)
+--------------------------------------------------------
+
+.. list-table::
+    :widths: 10 10 10
+    :header-rows: 1
+
+    * - Repo url
+      - USB IP
+      - Version
+    * - https://github.com/OpenSiFli/SiFli-SDK
+      - MUSB
+      - less than latest
+
+Based on RP2040/RP2035 Chips (Official SDK Support Coming Soon)
+--------------------------------------------------------------------------
+
+.. list-table::
+    :widths: 10 10 10
+    :header-rows: 1
+
+    * - Repo url
+      - USB IP
+      - Version
+    * - https://github.com/CherryUSB/pico-examples  https://github.com/CherryUSB/pico-sdk
+      - RP2040
+      - less than latest
+
+Based on Actionstech Series Chips (Official SDK Support)
+-----------------------------------------------------------
+
+Not opensource, please contact to Actionstech official
+
+Based on ST Series Chips
+---------------------------
+
+.. list-table::
+    :widths: 10 10 10
+    :header-rows: 1
+
+    * - Repo url
+      - USB IP
+      - Version
+    * - https://github.com/CherryUSB/cherryusb_stm32
+      - DWC2/FSDEV
+      - less than latest
+
+Default demo projects provided:
+
+- F103 uses fsdev ip
+- F429 host and device use USB1, pins pb14/pb15, default device does not enable DMA mode
+- H7 device uses USB0, pins pa11/pa12, DMA mode not enabled. Host uses USB1, pins pb14/pb15, and needs nocache processing
+
+Demo provides **stm32xxx.ioc** file, double click to open, click **Generate Code**.
+
+.. caution:: After generation, please use git reset function to restore the overwritten `main.c` and `stm32xxx_it.c` files, prohibit being overwritten by cubemx.
+
+Covers F1/F4/H7, other chips are basically similar and won't be repeated. Specific differences are:
+
+- usb ip difference: F1 uses fsdev, F4/H7 use dwc2
+- dwc2 ip difference: USB0 (pins PA11/PA12) and USB1 (pins PB14/PB15), where USB1 defaults to full-speed, can connect external PHY to form high-speed host, and has DMA functionality
+- F4 has no cache, H7 has cache
+
+If it's STM32F7/STM32H7 with cache functionality, you need to locate the ram used by usb to the no cache ram area. Example as follows
+
+.. code-block:: C
+
+    cpu_mpu_config(0, MPU_Normal_NonCache, 0x24070000, MPU_REGION_SIZE_64KB);
+
+Corresponding sct script modification in Keil:
+
+.. 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)
+    }
+    }
+
+USB Device Porting Points
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Use **stm32cubemx** to create project, configure basic RCC, UART (used as log)
+
+.. figure:: img/stm32_1.png
+.. figure:: img/stm32_2.png
+
+- If using fsdev ip, check **USB**. If using dwc2 ip, check **USB_OTG_FS** or **USB_OTG_HS**. Enable USB interrupt. Other configurations are useless to us, no ST USB library will be used in the code.
+
+.. figure:: img/stm32_3_1.png
+.. figure:: img/stm32_3_2.png
+
+- Configure usb clock to 48M
+
+.. figure:: img/stm32_4_1.png
+.. figure:: img/stm32_4_2.png
+
+- Select project, here we choose keil, set stack and heap properly. If using msc, it's recommended to set them larger, then click **Generate Code**.
+
+.. figure:: img/stm32_5.png
+
+- Add CherryUSB required source code (**usbd_core.c**, **dwc2/usb_dc_dwc2.c** or **fsdev/usb_dc_fsdev.c**), as well as the class drivers you want to use. You can add corresponding class templates for convenient testing.
+
+.. figure:: img/stm32_6.png
+
+- Add necessary header files
+
+.. figure:: img/stm32_7.png
+
+- Copy **cherryusb_config_template.h**, place it in the `Core/Inc` directory, and name it `usb_config.h`
+
+.. figure:: img/stm32_8.png
+
+- If using fsdev ip, (starting from V1.5.0, need to add **fsdev/usb_glue_st.c**) implement the following macro definition in `usb_config.h`. The specific value varies for different chips:
+
+.. code-block:: C
+
+    #define CONFIG_USBDEV_FSDEV_PMA_ACCESS 2
+
+- Compiler recommends using **AC6**. Check **Microlib**, and implement **printf** for convenient log viewing later.
+
+.. figure:: img/stm32_10.png
+.. figure:: img/stm32_11.png
+
+.. note :: Starting from V1.5.0, the following two steps are no longer needed because they are already implemented in **fsdev/usb_glue_st.c** and **dwc2/usb_glue_st.c** files
+
+- Copy the content of **HAL_PCD_MspInit** function in **xxx_msp.c** to **usb_dc_low_level_init** function, disable ST generated USB initialization
+
+.. figure:: img/stm32_12.png
+.. figure:: img/stm32_14.png
+
+- Call `USBD_IRQHandler` in interrupt function and pass in `busid`
+
+.. figure:: img/stm32_13.png
+
+- If the chip has cache, please refer to :ref:`usb_cache` chapter for cache modification
+
+- Call template content initialization and fill in `busid` and USB IP's `reg base`. `busid` starts from 0 and cannot exceed `CONFIG_USBDEV_MAX_BUS`
+
+.. figure:: img/stm32_15.png
+
+USB Host Porting Points
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The first 6 steps are the same as device side. Note that host driver only supports HS port with DMA (pins PB14/PB15), so FS port (pins PA11/PA12) is not supported (what's the point of a host without DMA).
+
+- Add CherryUSB required source code (**usbh_core.c**, **usbh_hub.c**, **usb_hc_dwc2.c**, **usb_glue_st.c** and adapter layer files in **osal** directory), as well as the class drivers you want to use, and you can add corresponding **usb host.c** for convenient testing.
+
+.. figure:: img/stm32_16.png
+
+- Compiler recommends using **AC6**. Check **Microlib**, and implement **printf** for convenient log viewing later.
+
+.. figure:: img/stm32_10.png
+.. figure:: img/stm32_11.png
+
+- Copy **cherryusb_config_template.h**, place it in the `Core/Inc` directory, and name it `usb_config.h`
+
+.. note :: Starting from V1.5.0, the following two steps are no longer needed because they are already implemented in **fsdev/usb_glue_st.c** and **dwc2/usb_glue_st.c** files
+
+- Copy the content of `HAL_HCD_MspInit` function in **xxx_msp.c** to `usb_hc_low_level_init` function, disable ST generated USB initialization
+- Call `USBH_IRQHandler` in interrupt function and pass in `busid`
+
+.. figure:: img/stm32_19.png
+
+- For linker script modifications, refer to :ref:`usbh_link_script` chapter
+- If the chip has cache, please refer to :ref:`usb_cache` chapter for cache modification
+- Call `usbh_initialize` and fill in `busid` and USB IP's `reg base` and `event_handler` (can be omitted as NULL). `busid` starts from 0 and cannot exceed `CONFIG_USBHOST_MAX_BUS`
+- Start thread
+
+.. figure:: img/stm32_18.png

docs/en/quick_start/migration.rst

@@ -0,0 +1,62 @@
+Partial Changes Migration Guide
+======================================
+
+usbh_initialize
+------------------
+
+usbh_initialize has added event_handler parameter starting from v1.6.0. Usually not needed, can pass NULL.
+
+dwc2 glue st
+----------------
+
+Starting from v1.5.0, dwc2 glue file has built-in low-level initialization, such as `usb_dc_low_level_init`, which depends on `HAL_PCD_MspInit` and `HAL_HCD_MspInit`. Must use stm32cubemx generation. Third-party platforms do not guarantee having these function implementations, check by yourself.
+
+
+dwc2 glue
+----------------
+
+Starting from v1.5.1, dwc2 adds `struct dwc2_user_params` for implementing different configurations for multiple dwc2 ports. It replaces `usbd_get_dwc2_gccfg_conf` and `usbh_get_dwc2_hccfg_conf` functions,
+and adds `dwc2_get_user_params` function implementation, example as follows:
+
+.. code-block:: C
+
+    #ifndef CONFIG_USB_DWC2_CUSTOM_PARAM
+    void dwc2_get_user_params(uint32_t reg_base, struct dwc2_user_params *params)
+    {
+        memcpy(params, &param_common, sizeof(struct dwc2_user_params));
+    #ifdef CONFIG_USB_DWC2_CUSTOM_FIFO
+        struct usb_dwc2_user_fifo_config s_dwc2_fifo_config;
+
+        dwc2_get_user_fifo_config(reg_base, &s_dwc2_fifo_config);
+
+        params->device_rx_fifo_size = s_dwc2_fifo_config.device_rx_fifo_size;
+        for (uint8_t i = 0; i < MAX_EPS_CHANNELS; i++) {
+            params->device_tx_fifo_size[i] = s_dwc2_fifo_config.device_tx_fifo_size[i];
+        }
+    #endif
+    }
+    #endif
+
+host serial
+----------------
+
+Starting from v1.6.0, host adds host serial framework for unifying all serial-like devices. The following APIs need to be replaced with new serial APIs:
+
+.. code-block:: C
+
+    int usbh_xxx_set_line_coding(struct usbh_xxx *xxx_class, struct cdc_line_coding *line_coding);
+    int usbh_xxx_get_line_coding(struct usbh_xxx *xxx_class, struct cdc_line_coding *line_coding);
+    int usbh_xxx_set_line_state(struct usbh_xxx *xxx_class, bool dtr, bool rts);
+
+    int usbh_xxx_bulk_in_transfer(struct usbh_xxx *xxx_class, uint8_t *buffer, uint32_t buflen, uint32_t timeout);
+    int usbh_xxx_bulk_out_transfer(struct usbh_xxx *xxx_class, uint8_t *buffer, uint32_t buflen, uint32_t timeout);
+
+Replace with:
+
+.. code-block:: C
+
+    struct usbh_serial *usbh_serial_open(const char *devname, uint32_t open_flags);
+    int usbh_serial_close(struct usbh_serial *serial);
+    int usbh_serial_control(struct usbh_serial *serial, int cmd, void *arg);
+    int usbh_serial_write(struct usbh_serial *serial, const void *buffer, uint32_t buflen);
+    int usbh_serial_read(struct usbh_serial *serial, void *buffer, uint32_t buflen);

docs/en/quick_start/opensource.rst

@@ -0,0 +1,61 @@
+Official Open Source Project Sharing
+=========================================
+
+In addition to basic vendor SDK support, we have also supported some popular open source projects to help developers better use these projects. Below are the adapted demo project links. For specific adaptation layers, refer to https://github.com/cherry-embedded/CherryUSB/tree/master/platform.
+
+DAPLINK
+--------------
+
+Adaptation link: https://github.com/cherry-embedded/CherryDAP
+
+Blackmagic
+--------------
+
+Adaptation link: https://github.com/zhangjiance/bmp-hpm-port
+
+RT-Thread
+--------------
+
+Adaptation link: https://github.com/RT-Thread/rt-thread
+
+NUTTX/VELA
+--------------
+
+Adaptation link: https://github.com/CherryUSB/cherryusb_nuttx
+
+Zephyr
+--------------
+
+Adaptation link: 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
+
+Host computer adaptation link: https://github.com/RCSN/cangaroo_hpmicro_canfd_analyzer
+Lower computer adaptation link: https://github.com/RCSN/hpm_sdk_extra/tree/main/demos/cangaroo_hpmicro
+
+LVGL
+--------------
+
+Adaptation link: 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.
+
+Adaptation link: To be released
+
+Klipper
+--------------
+
+Klipper is a 3D-printer firmware.
+
+Adaptation link: To be released
+
+MAKCU/KMBOX
+--------------
+
+Those who know, know - not released

docs/en/quick_start/q&a.rst

@@ -0,0 +1,135 @@
+Q & A
+============================================
+
+Porting Question Template
+------------------------------
+
+Please submit questions through the following channels:
+- RT-Thread Official Forum: https://club.rt-thread.org/ask/tag/5f5f851966917b14.html
+- Github issue: https://github.com/cherry-embedded/CherryUSB/issues/new/choose
+
+Please include the following information in your question:
+
+- Version being used
+- Board, pins, and USB IP being used
+- Whether USB interrupts, USB clock, USB pins, USB PHY configuration are configured, and whether USB register addresses are correct (include screenshots)
+- Whether USB interrupts are triggered
+- Whether the chip has cache functionality and whether no-cache processing has been implemented (include screenshots)
+- Whether USB circuit is drawn correctly, whether dupont wires are used for connection, whether direct connection is used; if normal, please explain why it's normal
+- If interrupts can be triggered, configure **#define CONFIG_USB_DBG_LEVEL USB_DBG_LOG** and provide logs (limited to commercial IPs only; other IPs are prohibited from enabling logs, otherwise enumeration will fail)
+- Whether the chip has been taped out and is being sold
+
+Other Question Template
+--------------------------------
+
+Specifically describe the phenomenon, reproduction method, test using my provided demo, and provide complete logs
+
+How Much Performance Can CherryUSB Achieve
+----------------------------------------------------------------
+
+Reference: :ref:`performace_show`
+
+ST IP Naming Issues
+-------------------------
+
+ST naming uses USB_OTG_FS, USB_OTG_HS, which doesn't indicate whether it's actually high-speed or full-speed, but represents the maximum speed it can support (high-speed). Both are actually full-speed and require external high-speed PHY. Therefore, please avoid using these terms in questions; use USB0(PA11/PA12), USB1(PB14/PB15) instead. The same applies to other domestic manufacturers.
+
+GD IP Issues
+------------------
+
+GD IP uses DWC2, but all hardware parameters read are 0 (I don't understand why they don't want people to know). Therefore, users need to know the hardware information themselves. Starting from version 1.5.0, because hardware information needs to be read, it cannot be used directly.
+
+Additionally, GD cannot use the EPDIS function to close endpoints after reset. Users need to delete the following code from the reset interrupt:
+
+.. 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);
+
+There may also be other unknown bugs; please test yourself.
+
+Cannot enumerate after enabling USB_LOG_DBG
+----------------------------------------------------------------
+
+Only commercial IPs can enumerate after enabling, other IPs are prohibited from enabling, otherwise enumeration will fail. Those who know, know.
+
+Which version to use for USB3 CV testing
+--------------------------------------------
+
+Version 1.4.3 and above
+
+Ep addr XXX fifo overflow
+------------------------------
+
+.. figure:: img/question1.png
+
+This error indicates that the default FIFO space setting for this endpoint is insufficient and needs to be increased. This is commonly seen in DWC2/MUSB IP. Refer to relevant glue files for FIFO settings.
+
+Ep addr XXX overflow
+------------------------------
+
+.. figure:: img/question2.png
+
+This error indicates that the IP hardware doesn't have that many endpoints. Please change IP or reduce endpoint usage.
+Of course, you can also modify to bidirectional endpoints. Considering that not all IPs support bidirectional endpoints, the default demo doesn't implement bidirectional functionality. For example, the default is 81 02 rather than 81 01. If supported, modify it yourself. Some IP bidirectional endpoints may occupy the same hardware information and may not be usable simultaneously, please check yourself.
+
+This dwc2 version does not support dma mode, so stop working
+----------------------------------------------------------------
+
+This DWC2 version doesn't support DMA mode, prohibited from use. Not using DMA mode will frequently trigger NAK interrupts (about every tens of microseconds), causing excessively high CPU usage.
+
+Which chips support OTG
+------------------------------
+
+Currently, only HPM chips support OTG functionality in the mainline, automatically switching between host/device modes via ID pin. For other chips, please use manual switching mode OR implement ID recognition driver yourself.
+
+How to change PC-recognized COM port name
+----------------------------------------------------------------
+
+This is a Microsoft CDC ACM driver issue that cannot be modified. If modification is needed, please contact Microsoft, pay fees, and write driver to make changes.
+
+Connect and disconnect events not triggering
+----------------------------------------------------------------
+
+Currently only HPM chips support connect and disconnect events. For other chips, please use USB VBUS detection circuit. DWC2 IP supports it, but because it requires pin usage and most are log ports, and different enabling configurations vary, support is not provided.
+
+__has_include error
+------------------------------------------------------------------
+If error occurs, compiler needs to support C99 syntax. If using Keil, please use AC6 compiler.
+
+When to use CONFIG_USB_HS
+----------------------------------------------------------------
+
+Enable when your chip hardware supports high speed and you want to initialize in high-speed mode. Related IP will configure internal or external high-speed PHY based on this macro.
+
+Failed to enable port
+----------------------------------------------------------------
+
+Insufficient power supply or hardware USB circuit issues
+
+Porting USB host encounters URB return -12/-14
+----------------------------------------------------------------
+
+Check PHY configuration, cache configuration (if any), power supply (recommend self-powered)
+
+USB_ERR_NAK explanation
+----------------------------------------------------------------
+
+USB_ERR_NAK only exists in DWC2 buffer DMA/slave mode (we don't use slave mode). DWC2 in buffer DMA mode doesn't support hardware handling of NAK interrupts for interrupt transfers, requiring software handling, resulting in very frequent NAK interrupts. Recommend using with timer.
+DWC2 scatter/gather DMA mode is fully handled by hardware but doesn't support split transfers. In summary, **tasteless to eat, pity to discard**.
+
+USB host connecting USB network adapter issues
+----------------------------------------------------------------
+
+Manifests as network adapter recognition and IP address allocation but inability to ping. This is because the network adapter itself needs to enable auto-dial, usually requiring AT port settings. Specifically for EC20/ML307 modules.
+
+When to enable CONFIG_USB_DCACHE_ENABLE
+-------------------------------------------------
+
+Enable this macro when chip has cache functionality and doesn't use no-cache RAM to ensure data consistency. **When using EHCI, nocache RAM is still needed internally**. Usually, for third-party platforms or components that don't use no-cache RAM macros but use global variables or malloc operations, this RAM typically goes through cache, requiring this macro. Recommend mandatory enabling for third-party platform usage.
+
+Which IPs have data alignment requirements
+-------------------------------------------------
+
+- When CONFIG_USB_DCACHE_ENABLE is not enabled, only DWC2/WCH/AIC IP requires 4-byte alignment, others need only 1-byte alignment.
+- When CONFIG_USB_DCACHE_ENABLE is enabled, all IPs need alignment to CONFIG_USB_ALIGN_SIZE bytes

docs/en/quick_start/rtthread.rst

@@ -0,0 +1,62 @@
+RT-Thread Software Package Development Guide
+=============================================
+
+.. note:: CherryUSB has been added to the RT-Thread mainline and you can choose to use the mainline version with the same configuration method.
+
+This section mainly introduces using the software package manager provided by RT-Thread to configure projects, demonstrated with env. The operations in this section are the same for different chips and won't be repeated later. After opening env, use menuconfig to enter the package manager and select CherryUSB in the path shown in the figure.
+
+.. figure:: img/env0.png
+
+Device Configuration
+--------------------------
+
+* Select Enable USB device mode and press Enter to enter.
+* The first configuration is to configure USB speed, divided into **FS, HS**, indicating whether to use full-speed or high-speed functionality. High-speed functionality requires built-in high-speed PHY or external PHY
+* The second configuration is to select the USB device IP. If you are not sure which IP your chip uses, refer to the README in the corresponding `port` directory.
+* Select the class you want to use
+* Choose whether to use a demo template
+
+.. figure:: img/env1.png
+
+* Finally exit and save.
+* Copy `cherryusb_config_template.h` file to your project directory, rename it to `usb_config.h`, add the corresponding header file path, and modify the following content:
+
+.. code-block:: C
+
+        #include "rtthread.h"
+
+        #define CONFIG_USB_PRINTF(...) rt_kprintf(__VA_ARGS__)
+
+* USB IP related config needs to be modified by the user according to the actual chip situation
+* Implement the `usb_dc_low_level_init` function in code
+* Call `USBD_IRQHandler` in the USB interrupt function and pass in `busid`
+* Call `usbd_initialize` and fill in `busid` and USB IP's `reg base`. `busid` starts from 0 and cannot exceed `CONFIG_USBDEV_MAX_BUS`
+* Use `scons --target=mdk5` or `scons` to compile. If using mdk, you need to use the AC6 compiler
+* If the chip has cache, refer to the :ref:`usb_cache` chapter for cache modifications
+
+Host Configuration
+--------------------------
+
+* Select Enable usb host mode and press Enter
+* Select USB host ip. If you're not sure which ip your chip uses, refer to the readme under the corresponding **port** directory
+* Check class drivers as needed
+* Choose whether to enable template demo, recommended not to use
+
+.. figure:: img/env2.png
+
+* Finally exit and save.
+* Copy `cherryusb_config_template.h` file to your project directory, rename it to `usb_config.h`, add the corresponding header file path, and implement the following content:
+
+.. code-block:: C
+
+        #include "rtthread.h"
+
+        #define CONFIG_USB_PRINTF(...) rt_kprintf(__VA_ARGS__)
+
+* USB IP related config needs to be modified by the user according to the actual chip situation
+* Implement the `usb_hc_low_level_init` function in code
+* Call `USBH_IRQHandler` in the USB interrupt function and pass in `busid`
+* Call `usbh_initialize` and fill in `busid` and USB IP's `reg base` and `event_handler` (can be omitted as NULL). `busid` starts from 0 and cannot exceed `CONFIG_USBHOST_MAX_BUS`
+* Use `scons --target=mdk5` or `scons` to compile. If using mdk, you need to use the AC6 compiler
+* For linker script modifications, refer to the :ref:`usbh_link_script` chapter
+* If the chip has cache, refer to the :ref:`usb_cache` chapter for cache modifications

docs/en/quick_start/share.rst

@@ -0,0 +1,27 @@
+Developer Experience/Open Source Project Sharing
+====================================================
+
+- `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>`_
+

docs/en/quick_start/start.rst

@@ -0,0 +1,52 @@
+Getting Started Guide
+=========================
+
+First of all, welcome to the world of USB. Here you can learn various USB knowledge and CherryUSB porting, usage, advanced features, etc. However, as a newcomer, you must be quite confused because USB is difficult (actually, once you learn CherryUSB, you'll find that USB is not difficult at all). So in this situation, what should your learning path be? Here, I recommend following my learning path, as this will be most helpful for your USB growth and you won't give up midway.
+
+First, don't start by looking at concepts. There's an ancient saying: **"What you read on paper is always shallow; to truly understand, you must practice"**. Just looking at written materials won't teach you much. Only when you practice yourself can you gain deeper understanding of these concepts. So as a beginner, what should you do? Please follow these steps.
+
+
+Step 1
+-------------
+
+You need to have learned C language, UART, and DMA - these are the basics. If you haven't learned them, please go learn them first, otherwise you'll struggle. You might ask: what's the relationship between USB and UART/DMA? I can only say two words: **equivalent**.
+
+Step 2
+-------------
+
+Download demo projects and get them running. **For slow learners, I recommend using the same chip model as the demo**. For fast learners, you can choose to port to supported chip models yourself. If you can't even get the demos running, what USB can you learn? Don't you agree?
+
+Step 3
+---------
+
+Excellent! By this step, you can already skillfully port and run all examples. So what should you learn next? **Transactions**, **Requests**, and **Descriptors** (in your USB learning journey, you only need to know these three things; you don't need to know anything else).
+
+Step 4
+----------
+
+First, we need to know that USB transactions include SETUP/IN/OUT, which are essentially equivalent to sending commands, sending data, and receiving data - very simple. As for the control phase, data phase, and status phase that you hear about in online discussions about enumeration, they are not transactions themselves; they are just multiple transactions representing a phase.
+
+Step 5
+----------
+
+Then look at the **USB Enumeration** section and learn about the concept of **descriptors**. At this point, you can briefly look at what descriptors are and what types exist. You need to remember and memorize **the composition of device, configuration, interface, and endpoint descriptors**. You don't need to know anything else because everything else is fixed and can be copy-pasted later. There are enumeration captures for various devices in the group files that you can download and review.
+
+Step 6
+----------
+
+Then you can look at what **requests** are, the composition of request structures, and what types of requests exist - just a basic understanding will suffice. Why? Because it's just an 8-byte data format. Everyone can write UART + custom protocol, and USB requests are the same, just predefined.
+
+Step 7
+----------
+
+At this point, you should familiarize yourself with some protocol stack APIs by referring to the **API Manual** section. You also need to know what conditions constitute interrupt completion, when reception is considered complete, and when transmission is considered complete. You can refer to the **USB Knowledge Extension** section.
+
+Step 8
+----------
+
+By this step, you're definitely very knowledgeable, and you can start working on some small functional projects. During this period, please repeatedly review the **USB Knowledge Extension** section until you truly understand it, because this content is very important and will affect the execution results of our code.
+
+Step 9
+----------
+
+You've reached this point - you shouldn't need me anymore! Now you can look at USB concepts, USB details, and CherryUSB code flow. Then it's just consolidation, consolidation, and more consolidation. Congratulations, you've graduated!

docs/en/quick_start/transplant.rst

@@ -0,0 +1,137 @@
+General Chip Porting Guide
+=======================================
+
+This section mainly introduces the general steps and precautions for porting CherryUSB host and device protocol stacks to all chips with USB IP. Before porting, you need to **prepare a basic project that can print helloworld**. Default printing uses `printf`. If it's host mode, **you need to prepare a basic project that can execute OS scheduling normally**.
+
+USB Device Porting Key Points
+-------------------------------------
+
+- Copy CherryUSB source code to the project directory and add source files and header file paths as needed. It's recommended to add all header file paths. Among them, `usbd_core.c` and `usb_dc_xxx.c` are required items. `usb_dc_xxx.c` is the USB IP DCD driver corresponding to the chip. If you don't know which USB IP your chip belongs to, refer to the readme of different USB IPs under the **port** directory. If the USB IP you're using is not supported, you'll have to implement it yourself
+- Copy `cherryusb_config_template.h` file to your project directory, rename it to `usb_config.h`, and add the corresponding directory header file path
+- Implement `usb_dc_low_level_init` function (this function is mainly responsible for USB clock, pin, and interrupt initialization). This function can be placed in any C file that participates in compilation. For USB clock, pin, interrupt initialization, please add them yourself according to the source code provided by your chip manufacturer.
+- Call `USBD_IRQHandler` in the interrupt function and pass `busid`. If `USBD_IRQHandler` already exists in the interrupt entry of your SDK, please change the name in the USB protocol stack
+- If the chip has cache, refer to the :ref:`usb_cache` section for cache modifications
+- Register descriptors and call `usbd_initialize`, fill in `busid` and USB IP's `reg base`. `busid` starts from 0 and cannot exceed `CONFIG_USBDEV_MAX_BUS`. You can directly use templates under the demo directory
+
+USB Host Porting Key Points
+-------------------------------------
+
+- Copy CherryUSB source code to project directory and add source files and header file paths as needed. It's recommended to add all header file paths. Among them, `usbh_core.c`, `usb_hc_xxx.c` and source files under the **osal** directory (choose corresponding source files according to different OS) are required. `usb_hc_xxx.c` is the USB IP HCD driver corresponding to the chip. If you don't know which USB IP your chip belongs to, refer to the readme of different USB IPs under the **port** directory. If the USB IP you're using is not supported, you'll have to implement it yourself
+- Copy `cherryusb_config_template.h` file to your project directory, rename it to `usb_config.h`, and add the corresponding directory header file path
+- Implement `usb_hc_low_level_init` function (this function is mainly responsible for USB clock, pin, and interrupt initialization). This function can be placed in any C file that participates in compilation. For USB clock, pin, interrupt initialization, please add them yourself according to the source code provided by your chip manufacturer.
+- Call `usbh_initialize` and fill in `busid`, USB IP's `reg base`, and `event_handler` (can be omitted as NULL). `busid` starts from 0 and cannot exceed `CONFIG_USBHOST_MAX_BUS`
+- Call `USBH_IRQHandler` in the interrupt function and pass `busid`. If `USBH_IRQHandler` already exists in the interrupt entry of your SDK, please change the name in the USB protocol stack
+- Refer to the :ref:`usbh_link_script` section for linker script modifications
+- If the chip has cache, refer to the :ref:`usb_cache` section for cache modifications
+- Call `usbh_initialize`, fill in `busid`, USB IP's `reg base`, and `event_handler` (can be omitted as NULL). `busid` starts from 0 and cannot exceed `CONFIG_USBHOST_MAX_BUS`. For basic CDC + HID + MSC, refer to the `usb_host.c` file. For others, refer to adaptations under the **platform** directory
+
+.. _usbh_link_script:
+
+Host Linker Script Modifications
+-------------------------------------
+
+When using the host, if you haven't modified the linker script, you will encounter `__usbh_class_info_start__` and `__usbh_class_info_end__` undefined errors. This is because the host protocol stack requires adding a section to the linker script to store class information.
+
+- No modification needed if using KEIL
+
+- If using GCC, add the following code to the linker script (needs to be placed in flash location, recommended at the end):
+
+.. code-block:: C
+
+        // Add the following code to the ld file
+        . = ALIGN(4);
+        __usbh_class_info_start__ = .;
+        KEEP(*(.usbh_class_info))
+        __usbh_class_info_end__ = .;
+
+GCC example:
+
+.. code-block:: C
+
+        /* The program code and other data into "FLASH" Rom type memory */
+        .text :
+        {
+        . = ALIGN(4);
+        *(.text)           /* .text sections (code) */
+        *(.text*)          /* .text* sections (code) */
+        *(.glue_7)         /* glue arm to thumb code */
+        *(.glue_7t)        /* glue thumb to arm code */
+        *(.eh_frame)
+
+        KEEP (*(.init))
+        KEEP (*(.fini))
+        . = ALIGN(4);
+        __usbh_class_info_start__ = .;
+        KEEP(*(.usbh_class_info))
+        __usbh_class_info_end__ = .;
+        . = ALIGN(4);
+        _etext = .;        /* define a global symbols at end of code */
+        } > FLASH
+
+- Segger Embedded Studio example:
+
+.. code-block:: C
+
+        define block cherryusb_usbh_class_info { section .usbh_class_info };
+
+        define exported symbol __usbh_class_info_start__  = start of block cherryusb_usbh_class_info;
+        define exported symbol __usbh_class_info_end__  = end of block cherryusb_usbh_class_info + 1;
+
+        place in AXI_SRAM                         { block cherryusb_usbh_class_info };
+        keep { section .usbh_class_info};
+
+
+.. _usb_cache:
+
+cache Configuration Modification
+--------------------------------------
+
+For chips with cache functionality, the protocol stack and port will not clean or invalidate RAM in the cache region, so a non-cache RAM area needs to be used for maintenance.
+`USB_NOCACHE_RAM_SECTION` macro specifies variables to be placed in non-cache RAM. By default, `USB_NOCACHE_RAM_SECTION` is defined as `__attribute__((section(".noncacheable")))`.
+Therefore, users need to add a no cache RAM section in the corresponding linker script, and the section must include `.noncacheable`.
+
+.. note:: Note that just modifying the nocache section in the linker script is not sufficient. You also need to configure the RAM in that section to be truly nocache, which typically requires configuring MPU attributes (for ARM, refer to the stm32h7 demo).
+
+GCC:
+
+.. code-block:: C
+
+        MEMORY
+        {
+        RAM    (xrw)    : ORIGIN = 0x20000000,   LENGTH = 256K - 64K
+        RAM_nocache    (xrw)    : ORIGIN = 0x20030000,   LENGTH = 64K
+        FLASH    (rx)    : ORIGIN = 0x8000000,   LENGTH = 512K
+        }
+
+        ._nocache_ram :
+        {
+        . = ALIGN(4);
+        *(.noncacheable)
+        } >RAM_nocache
+
+
+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