docs: update docs and add english version

Signed-off-by: sakumisu <[email protected]>

Author: sakumisu

.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,56 +176,32 @@ 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
+
+Refer to https://cherryusb.readthedocs.io/en/latest/support/index.html.
+
 ## Company Support
 
 Thanks to the following companies for their support (in no particular order):

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.readthedocs.yaml renamed to 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