diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 65af1f41..c02a0348 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.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 diff --git a/README.md b/README.md index d514f1fb..24b55277 100644 --- a/README.md +++ b/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) +### Descriptor Generator Tool + +Cherry Descriptor: https://desc.cherry-embedded.org/en + +### Contact + +CherryUSB discord: https://discord.com/invite/wFfvrSAey8 + ## Commercial Support -Refer to https://cherryusb.readthedocs.io/zh-cn/latest/support/index.html. - -## Contact - -CherryUSB discord: https://discord.com/invite/wFfvrSAey8. +Refer to https://cherryusb.readthedocs.io/en/latest/support/index.html ## Company Support diff --git a/README_zh.md b/README_zh.md index cf76f3ea..b4b60472 100644 --- a/README_zh.md +++ b/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 + ## 支持企业 感谢以下企业支持（顺序不分先后）： diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf1..3c4d6efb 100644 --- a/docs/Makefile +++ b/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) diff --git a/.readthedocs.yaml b/docs/en/.readthedocs.yaml similarity index 96% rename from .readthedocs.yaml rename to docs/en/.readthedocs.yaml index ed14f4de..31a7d30a 100644 --- a/.readthedocs.yaml +++ b/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 diff --git a/docs/en/api/api_config.rst b/docs/en/api/api_config.rst new file mode 100755 index 00000000..f1fed77a --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/en/api/api_device.rst b/docs/en/api/api_device.rst new file mode 100755 index 00000000..f44be9dd --- /dev/null +++ b/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 +----------------- diff --git a/docs/en/api/api_host.rst b/docs/en/api/api_host.rst new file mode 100755 index 00000000..7499d188 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en/api/api_port.rst b/docs/en/api/api_port.rst new file mode 100755 index 00000000..9f5fe5c1 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/source/api/img/api_device1.png b/docs/en/api/img/api_device1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/api/img/api_device1.png rename to docs/en/api/img/api_device1.png diff --git a/docs/source/api/img/api_host1.png b/docs/en/api/img/api_host1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/api/img/api_host1.png rename to docs/en/api/img/api_host1.png diff --git a/docs/source/api/img/api_host2.png b/docs/en/api/img/api_host2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/api/img/api_host2.png rename to docs/en/api/img/api_host2.png diff --git a/docs/en/class/class_audio.rst b/docs/en/class/class_audio.rst new file mode 100755 index 00000000..c706afd5 --- /dev/null +++ b/docs/en/class/class_audio.rst @@ -0,0 +1,4 @@ +UAC +======================================= + +Reference official audio-related PDFs \ No newline at end of file diff --git a/docs/en/class/class_cdc.rst b/docs/en/class/class_cdc.rst new file mode 100755 index 00000000..23826066 --- /dev/null +++ b/docs/en/class/class_cdc.rst @@ -0,0 +1,4 @@ +CDC +======================================= + +Reference official CDC-related PDFs \ No newline at end of file diff --git a/docs/en/class/class_hid.rst b/docs/en/class/class_hid.rst new file mode 100755 index 00000000..14253a9f --- /dev/null +++ b/docs/en/class/class_hid.rst @@ -0,0 +1,4 @@ +HID +======================================= + +Reference official HID-related PDFs \ No newline at end of file diff --git a/docs/en/class/class_msc.rst b/docs/en/class/class_msc.rst new file mode 100755 index 00000000..6eb14313 --- /dev/null +++ b/docs/en/class/class_msc.rst @@ -0,0 +1,4 @@ +MSC +======================================= + +Reference official MSC-related PDFs \ No newline at end of file diff --git a/docs/en/class/class_video.rst b/docs/en/class/class_video.rst new file mode 100755 index 00000000..a93c2fa2 --- /dev/null +++ b/docs/en/class/class_video.rst @@ -0,0 +1,4 @@ +UVC +======================================= + +Reference official video-related PDFs \ No newline at end of file diff --git a/docs/en/class/winusb.rst b/docs/en/class/winusb.rst new file mode 100755 index 00000000..11041c5c --- /dev/null +++ b/docs/en/class/winusb.rst @@ -0,0 +1,2 @@ +WINUSB +======================================= \ No newline at end of file diff --git a/docs/source/conf.py b/docs/en/conf.py old mode 100644 new mode 100755 similarity index 95% rename from docs/source/conf.py rename to docs/en/conf.py index 6174f623..22427158 --- a/docs/source/conf.py +++ b/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' diff --git a/docs/source/demo/img/cherryadb.png b/docs/en/demo/img/cherryadb.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/demo/img/cherryadb.png rename to docs/en/demo/img/cherryadb.png diff --git a/docs/source/demo/img/otg.png b/docs/en/demo/img/otg.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/demo/img/otg.png rename to docs/en/demo/img/otg.png diff --git a/docs/source/demo/img/rtt_adb_shell1.png b/docs/en/demo/img/rtt_adb_shell1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/demo/img/rtt_adb_shell1.png rename to docs/en/demo/img/rtt_adb_shell1.png diff --git a/docs/source/demo/img/rtt_adb_shell2.png b/docs/en/demo/img/rtt_adb_shell2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/demo/img/rtt_adb_shell2.png rename to docs/en/demo/img/rtt_adb_shell2.png diff --git a/docs/source/demo/img/usbh_serial.png b/docs/en/demo/img/usbh_serial.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/demo/img/usbh_serial.png rename to docs/en/demo/img/usbh_serial.png diff --git a/docs/en/demo/usb_otg.rst b/docs/en/demo/usb_otg.rst new file mode 100755 index 00000000..3d206ec5 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en/demo/usbd_adb.rst b/docs/en/demo/usbd_adb.rst new file mode 100755 index 00000000..e11e784d --- /dev/null +++ b/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 diff --git a/docs/en/demo/usbd_audiov1.rst b/docs/en/demo/usbd_audiov1.rst new file mode 100755 index 00000000..5bf0629c --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/en/demo/usbd_audiov2.rst b/docs/en/demo/usbd_audiov2.rst new file mode 100755 index 00000000..8a66d10f --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/en/demo/usbd_cdc_acm.rst b/docs/en/demo/usbd_cdc_acm.rst new file mode 100755 index 00000000..28d9affa --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en/demo/usbd_ecm.rst b/docs/en/demo/usbd_ecm.rst new file mode 100755 index 00000000..de148621 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en/demo/usbd_hid.rst b/docs/en/demo/usbd_hid.rst new file mode 100755 index 00000000..71147dfa --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/en/demo/usbd_msc.rst b/docs/en/demo/usbd_msc.rst new file mode 100755 index 00000000..02b05add --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en/demo/usbd_mtp.rst b/docs/en/demo/usbd_mtp.rst new file mode 100755 index 00000000..0c9bd191 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en/demo/usbd_rndis.rst b/docs/en/demo/usbd_rndis.rst new file mode 100755 index 00000000..623c9208 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en/demo/usbd_vendor.rst b/docs/en/demo/usbd_vendor.rst new file mode 100755 index 00000000..c5a0b3c8 --- /dev/null +++ b/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)) \ No newline at end of file diff --git a/docs/en/demo/usbd_video.rst b/docs/en/demo/usbd_video.rst new file mode 100755 index 00000000..548e68b7 --- /dev/null +++ b/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; + } + } + } + } + } \ No newline at end of file diff --git a/docs/en/demo/usbd_webusb.rst b/docs/en/demo/usbd_webusb.rst new file mode 100755 index 00000000..3a6d3418 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/en/demo/usbd_winusb.rst b/docs/en/demo/usbd_winusb.rst new file mode 100755 index 00000000..059ff1f3 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/en/demo/usbh_audio.rst b/docs/en/demo/usbh_audio.rst new file mode 100755 index 00000000..387271f6 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en/demo/usbh_bluetooth.rst b/docs/en/demo/usbh_bluetooth.rst new file mode 100755 index 00000000..5b06f502 --- /dev/null +++ b/docs/en/demo/usbh_bluetooth.rst @@ -0,0 +1,2 @@ +BTBLE Host +================= diff --git a/docs/en/demo/usbh_hid.rst b/docs/en/demo/usbh_hid.rst new file mode 100755 index 00000000..7929179d --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en/demo/usbh_msc.rst b/docs/en/demo/usbh_msc.rst new file mode 100755 index 00000000..b47abdc8 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en/demo/usbh_net.rst b/docs/en/demo/usbh_net.rst new file mode 100755 index 00000000..13069563 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/en/demo/usbh_serial.rst b/docs/en/demo/usbh_serial.rst new file mode 100755 index 00000000..03d89f04 --- /dev/null +++ b/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 + diff --git a/docs/en/demo/usbh_vendor.rst b/docs/en/demo/usbh_vendor.rst new file mode 100755 index 00000000..09afe1cd --- /dev/null +++ b/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; + } \ No newline at end of file diff --git a/docs/en/demo/usbh_video.rst b/docs/en/demo/usbh_video.rst new file mode 100755 index 00000000..646b2c27 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en/demo/usbh_wifi.rst b/docs/en/demo/usbh_wifi.rst new file mode 100755 index 00000000..588e8131 --- /dev/null +++ b/docs/en/demo/usbh_wifi.rst @@ -0,0 +1,2 @@ +WIFI Host +================= diff --git a/docs/en/index.rst b/docs/en/index.rst new file mode 100755 index 00000000..25a7cc4f --- /dev/null +++ b/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 diff --git a/docs/en/quick_start/demo.rst b/docs/en/quick_start/demo.rst new file mode 100755 index 00000000..4168d870 --- /dev/null +++ b/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 diff --git a/docs/source/quick_start/img/env0.png b/docs/en/quick_start/img/env0.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/env0.png rename to docs/en/quick_start/img/env0.png diff --git a/docs/source/quick_start/img/env1.png b/docs/en/quick_start/img/env1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/env1.png rename to docs/en/quick_start/img/env1.png diff --git a/docs/source/quick_start/img/env2.png b/docs/en/quick_start/img/env2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/env2.png rename to docs/en/quick_start/img/env2.png diff --git a/docs/source/quick_start/img/esp1.png b/docs/en/quick_start/img/esp1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/esp1.png rename to docs/en/quick_start/img/esp1.png diff --git a/docs/source/quick_start/img/esp2.png b/docs/en/quick_start/img/esp2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/esp2.png rename to docs/en/quick_start/img/esp2.png diff --git a/docs/source/quick_start/img/esp3.png b/docs/en/quick_start/img/esp3.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/esp3.png rename to docs/en/quick_start/img/esp3.png diff --git a/docs/source/quick_start/img/esp4.png b/docs/en/quick_start/img/esp4.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/esp4.png rename to docs/en/quick_start/img/esp4.png diff --git a/docs/source/quick_start/img/question1.png b/docs/en/quick_start/img/question1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/question1.png rename to docs/en/quick_start/img/question1.png diff --git a/docs/source/quick_start/img/question2.png b/docs/en/quick_start/img/question2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/question2.png rename to docs/en/quick_start/img/question2.png diff --git a/docs/source/quick_start/img/stm32_1.png b/docs/en/quick_start/img/stm32_1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_1.png rename to docs/en/quick_start/img/stm32_1.png diff --git a/docs/source/quick_start/img/stm32_10.png b/docs/en/quick_start/img/stm32_10.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_10.png rename to docs/en/quick_start/img/stm32_10.png diff --git a/docs/source/quick_start/img/stm32_11.png b/docs/en/quick_start/img/stm32_11.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_11.png rename to docs/en/quick_start/img/stm32_11.png diff --git a/docs/source/quick_start/img/stm32_12.png b/docs/en/quick_start/img/stm32_12.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_12.png rename to docs/en/quick_start/img/stm32_12.png diff --git a/docs/source/quick_start/img/stm32_13.png b/docs/en/quick_start/img/stm32_13.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_13.png rename to docs/en/quick_start/img/stm32_13.png diff --git a/docs/source/quick_start/img/stm32_14.png b/docs/en/quick_start/img/stm32_14.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_14.png rename to docs/en/quick_start/img/stm32_14.png diff --git a/docs/source/quick_start/img/stm32_15.png b/docs/en/quick_start/img/stm32_15.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_15.png rename to docs/en/quick_start/img/stm32_15.png diff --git a/docs/source/quick_start/img/stm32_16.png b/docs/en/quick_start/img/stm32_16.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_16.png rename to docs/en/quick_start/img/stm32_16.png diff --git a/docs/source/quick_start/img/stm32_18.png b/docs/en/quick_start/img/stm32_18.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_18.png rename to docs/en/quick_start/img/stm32_18.png diff --git a/docs/source/quick_start/img/stm32_19.png b/docs/en/quick_start/img/stm32_19.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_19.png rename to docs/en/quick_start/img/stm32_19.png diff --git a/docs/source/quick_start/img/stm32_2.png b/docs/en/quick_start/img/stm32_2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_2.png rename to docs/en/quick_start/img/stm32_2.png diff --git a/docs/source/quick_start/img/stm32_3_1.png b/docs/en/quick_start/img/stm32_3_1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_3_1.png rename to docs/en/quick_start/img/stm32_3_1.png diff --git a/docs/source/quick_start/img/stm32_3_2.png b/docs/en/quick_start/img/stm32_3_2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_3_2.png rename to docs/en/quick_start/img/stm32_3_2.png diff --git a/docs/source/quick_start/img/stm32_4_1.png b/docs/en/quick_start/img/stm32_4_1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_4_1.png rename to docs/en/quick_start/img/stm32_4_1.png diff --git a/docs/source/quick_start/img/stm32_4_2.png b/docs/en/quick_start/img/stm32_4_2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_4_2.png rename to docs/en/quick_start/img/stm32_4_2.png diff --git a/docs/source/quick_start/img/stm32_5.png b/docs/en/quick_start/img/stm32_5.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_5.png rename to docs/en/quick_start/img/stm32_5.png diff --git a/docs/source/quick_start/img/stm32_6.png b/docs/en/quick_start/img/stm32_6.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_6.png rename to docs/en/quick_start/img/stm32_6.png diff --git a/docs/source/quick_start/img/stm32_7.png b/docs/en/quick_start/img/stm32_7.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_7.png rename to docs/en/quick_start/img/stm32_7.png diff --git a/docs/source/quick_start/img/stm32_8.png b/docs/en/quick_start/img/stm32_8.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/quick_start/img/stm32_8.png rename to docs/en/quick_start/img/stm32_8.png diff --git a/docs/en/quick_start/migration.rst b/docs/en/quick_start/migration.rst new file mode 100755 index 00000000..2ea61df7 --- /dev/null +++ b/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, ¶m_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); diff --git a/docs/en/quick_start/opensource.rst b/docs/en/quick_start/opensource.rst new file mode 100755 index 00000000..ed8af520 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/en/quick_start/q&a.rst b/docs/en/quick_start/q&a.rst new file mode 100755 index 00000000..3780b578 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/en/quick_start/rtthread.rst b/docs/en/quick_start/rtthread.rst new file mode 100755 index 00000000..d01f2673 --- /dev/null +++ b/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 diff --git a/docs/en/quick_start/share.rst b/docs/en/quick_start/share.rst new file mode 100755 index 00000000..e4ebdae8 --- /dev/null +++ b/docs/en/quick_start/share.rst @@ -0,0 +1,27 @@ +Developer Experience/Open Source Project Sharing +==================================================== + +- `RT-Thread-CherryUSB - RT-Thread `_ + +- `[HPM-DIY]hpm6750 USB开源协议栈性能对比-cherryusb or tinyusb？ `_ + +- `RT-Thread-CherryUSB移植笔记(一)：APM32F407VGT6 DWC2移植 Port.A Full-Speed + Por.B High-SpeedRT-Thread问答社区 - RT-Thread `_ + +- `华大HC32F460XXX移植cherryusb协议栈，实现USB CDC ACM_cherryusb移植教程-CSDN博客 `_ + +- `rt-thread使用cherryusb实现虚拟串口-CSDN博客 `_ + +- `F1C100S+rtt+CherryUSB的USB HOST成功读到U盘 / 全志 SOC / WhyCan Forum(哇酷开发者社区) `_ + +- `模仿stm32标准库风格写的库文件（f1c100s/f1c200s)，且已移植了rt-thread、lvgl、fatfs、cherryusb / 全志 SOC / WhyCan Forum(哇酷开发者社区) `_ + +- `printalyzer-timer: F-Stop enlarging timer and print exposure meter `_ + +- `MiSTeryNano: Atari STE MiSTery core for the Tang Nano 20k FPGA `_ + +- `Cherryuf2 `_ + +- `PicoPiFi: Driverless RNDIS USB WIFI Dongle `_ + +- `phobia: Phobia Motor Controller `_ + diff --git a/docs/en/quick_start/start.rst b/docs/en/quick_start/start.rst new file mode 100755 index 00000000..a19ffe4a --- /dev/null +++ b/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! diff --git a/docs/en/quick_start/transplant.rst b/docs/en/quick_start/transplant.rst new file mode 100755 index 00000000..eefb0a7a --- /dev/null +++ b/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 diff --git a/docs/source/show/img/usbdev_msc.png b/docs/en/show/img/usbdev_msc.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbdev_msc.png rename to docs/en/show/img/usbdev_msc.png diff --git a/docs/source/show/img/usbdev_rndis_linux.png b/docs/en/show/img/usbdev_rndis_linux.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbdev_rndis_linux.png rename to docs/en/show/img/usbdev_rndis_linux.png diff --git a/docs/source/show/img/usbdev_rndis_lwip.png b/docs/en/show/img/usbdev_rndis_lwip.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbdev_rndis_lwip.png rename to docs/en/show/img/usbdev_rndis_lwip.png diff --git a/docs/source/show/img/usbdev_rndis_lwip2.png b/docs/en/show/img/usbdev_rndis_lwip2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbdev_rndis_lwip2.png rename to docs/en/show/img/usbdev_rndis_lwip2.png diff --git a/docs/source/show/img/usbdev_rndis_wifi.png b/docs/en/show/img/usbdev_rndis_wifi.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbdev_rndis_wifi.png rename to docs/en/show/img/usbdev_rndis_wifi.png diff --git a/docs/source/show/img/usbdev_rndis_wifi2.png b/docs/en/show/img/usbdev_rndis_wifi2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbdev_rndis_wifi2.png rename to docs/en/show/img/usbdev_rndis_wifi2.png diff --git a/docs/source/show/img/usbdev_rndis_win.png b/docs/en/show/img/usbdev_rndis_win.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbdev_rndis_win.png rename to docs/en/show/img/usbdev_rndis_win.png diff --git a/docs/source/show/img/usbdev_uvc_mjpeg.png b/docs/en/show/img/usbdev_uvc_mjpeg.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbdev_uvc_mjpeg.png rename to docs/en/show/img/usbdev_uvc_mjpeg.png diff --git a/docs/source/show/img/usbdev_uvc_yuv.png b/docs/en/show/img/usbdev_uvc_yuv.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbdev_uvc_yuv.png rename to docs/en/show/img/usbdev_uvc_yuv.png diff --git a/docs/source/show/img/usbhost_ax88772_1.png b/docs/en/show/img/usbhost_ax88772_1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbhost_ax88772_1.png rename to docs/en/show/img/usbhost_ax88772_1.png diff --git a/docs/source/show/img/usbhost_ax88772_2.png b/docs/en/show/img/usbhost_ax88772_2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbhost_ax88772_2.png rename to docs/en/show/img/usbhost_ax88772_2.png diff --git a/docs/source/show/img/usbhost_hub.png b/docs/en/show/img/usbhost_hub.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbhost_hub.png rename to docs/en/show/img/usbhost_hub.png diff --git a/docs/source/show/img/usbhost_hub2.png b/docs/en/show/img/usbhost_hub2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbhost_hub2.png rename to docs/en/show/img/usbhost_hub2.png diff --git a/docs/source/show/img/usbhost_msc.png b/docs/en/show/img/usbhost_msc.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbhost_msc.png rename to docs/en/show/img/usbhost_msc.png diff --git a/docs/source/show/img/usbhost_msc_xhci.png b/docs/en/show/img/usbhost_msc_xhci.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbhost_msc_xhci.png rename to docs/en/show/img/usbhost_msc_xhci.png diff --git a/docs/source/show/img/usbhost_rndis.png b/docs/en/show/img/usbhost_rndis.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbhost_rndis.png rename to docs/en/show/img/usbhost_rndis.png diff --git a/docs/source/show/img/usbhost_uvc.gif b/docs/en/show/img/usbhost_uvc.gif old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbhost_uvc.gif rename to docs/en/show/img/usbhost_uvc.gif diff --git a/docs/source/show/img/usbhost_wifi.png b/docs/en/show/img/usbhost_wifi.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/show/img/usbhost_wifi.png rename to docs/en/show/img/usbhost_wifi.png diff --git a/docs/en/show/index.rst b/docs/en/show/index.rst new file mode 100755 index 00000000..2e8d4417 --- /dev/null +++ b/docs/en/show/index.rst @@ -0,0 +1,103 @@ +.. _performace_show: + +Performance Showcase +============================================ + +The following demonstrates the performance of CherryUSB in different applications. Mainly demonstrates high-speed mode, as full-speed shows no significant performance difference. + +CDC ACM Communication +----------------------- + +Can achieve hardware limit performance. Of course, the hardware needs to theoretically support this speed, and CherryUSB supports it accordingly. Examples are as follows: + +- HPM Series (Device can reach 42MB/S, Host 44MB/S, already reached hardware limit) +- BL Series (Device 32MB/S, Host 25MB/S, already reached hardware limit) +- STM32F4 Full-speed (Device 900KB/S, Host 1.12MB/S, already reached hardware limit) + +Device speed test demo: cdc_acm_template.c with log disabled, script uses `tools/test_srcipts/test_cdc_speed.py` +Host speed test demo: usb_host.c with TEST_USBH_CDC_SPEED=1 + +USB Device MSC +----------------- + +Demonstrates USB Device MSC using SDXC3.0 + EMMC testing. + +.. figure:: img/usbdev_msc.png + +USB Device RNDIS +----------------------- + +.. note:: By default, RNDIS only supports single packets, so the speeds below are minimum speeds. Multi-packet support requires contacting the author. + +Demonstrates USB Device RNDIS speed in LAN with lwip. + +As client + +.. figure:: img/usbdev_rndis_lwip.png + +As server + +.. figure:: img/usbdev_rndis_lwip2.png + +Demonstrates USB Device RNDIS + WIFI passthrough testing. + +.. figure:: img/usbdev_rndis_wifi.png +.. figure:: img/usbdev_rndis_wifi2.png + +Demonstrates USB Device RNDIS + 100Mbps Ethernet passthrough testing. + +.. figure:: img/usbdev_rndis_win.png +.. figure:: img/usbdev_rndis_linux.png + +USB Device UVC +----------------------- + +Demonstrates USB Device UVC + camera transmission of YUYV/MJPEG 640 * 480 images. 30 FPS. + +.. figure:: img/usbdev_uvc_mjpeg.png +.. figure:: img/usbdev_uvc_yuv.png + +USB Host HUB +----------------------- + +Multi-level hub support, demonstrates 1-to-7 HUB. + +.. figure:: img/usbhost_hub.png +.. figure:: img/usbhost_hub2.png + +USB Host MSC +----------------------- + +Demonstrates USB Host MSC speed under USB2.0 and USB3.0. Solid-state USB drives are recommended for testing. + +.. figure:: img/usbhost_msc.png +.. figure:: img/usbhost_msc_xhci.png + +USB Host UVC +----------------------- + +Demonstrates USB Host UVC driving 648 * 480 YUV camera. 30 FPS. + +.. figure:: img/usbhost_uvc.gif + +USB Host ASIX Network Card +------------------------------------------------- + +Demonstrates USB Host driving AX88772 USB Ethernet module. + +.. figure:: img/usbhost_ax88772_1.png +.. figure:: img/usbhost_ax88772_2.png + +USB Host RNDIS Network Card +------------------------------------------------- + +Demonstrates USB Host driving mobile phone. Enable USB network sharing on the phone to use RNDIS. + +.. figure:: img/usbhost_rndis.png + +USB Host WIFI +----------------------- + +Demonstrates USB Host driving BL616 USB WIFI. + +.. figure:: img/usbhost_wifi.png diff --git a/docs/source/support/img/dwc2_hostuac.png b/docs/en/support/img/dwc2_hostuac.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/dwc2_hostuac.png rename to docs/en/support/img/dwc2_hostuac.png diff --git a/docs/source/support/img/dwc2_hostuvc1.png b/docs/en/support/img/dwc2_hostuvc1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/dwc2_hostuvc1.png rename to docs/en/support/img/dwc2_hostuvc1.png diff --git a/docs/source/support/img/dwc2_hostuvc2.png b/docs/en/support/img/dwc2_hostuvc2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/dwc2_hostuvc2.png rename to docs/en/support/img/dwc2_hostuvc2.png diff --git a/docs/source/support/img/dwc2_hostuvc3.png b/docs/en/support/img/dwc2_hostuvc3.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/dwc2_hostuvc3.png rename to docs/en/support/img/dwc2_hostuvc3.png diff --git a/docs/source/support/img/ehci_hostuvc1.png b/docs/en/support/img/ehci_hostuvc1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/ehci_hostuvc1.png rename to docs/en/support/img/ehci_hostuvc1.png diff --git a/docs/source/support/img/ehci_hostuvc2.png b/docs/en/support/img/ehci_hostuvc2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/ehci_hostuvc2.png rename to docs/en/support/img/ehci_hostuvc2.png diff --git a/docs/source/support/img/mtpdev.png b/docs/en/support/img/mtpdev.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/mtpdev.png rename to docs/en/support/img/mtpdev.png diff --git a/docs/source/support/img/ohci.png b/docs/en/support/img/ohci.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/ohci.png rename to docs/en/support/img/ohci.png diff --git a/docs/source/support/img/rndisrx.png b/docs/en/support/img/rndisrx.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/rndisrx.png rename to docs/en/support/img/rndisrx.png diff --git a/docs/source/support/img/rndistx.png b/docs/en/support/img/rndistx.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/rndistx.png rename to docs/en/support/img/rndistx.png diff --git a/docs/source/support/img/tmcdev1.png b/docs/en/support/img/tmcdev1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/tmcdev1.png rename to docs/en/support/img/tmcdev1.png diff --git a/docs/source/support/img/tmcdev2.png b/docs/en/support/img/tmcdev2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/tmcdev2.png rename to docs/en/support/img/tmcdev2.png diff --git a/docs/source/support/img/usbhost_uvc.gif b/docs/en/support/img/usbhost_uvc.gif old mode 100644 new mode 100755 similarity index 100% rename from docs/source/support/img/usbhost_uvc.gif rename to docs/en/support/img/usbhost_uvc.gif diff --git a/docs/en/support/index.rst b/docs/en/support/index.rst new file mode 100755 index 00000000..cc49dc4a --- /dev/null +++ b/docs/en/support/index.rst @@ -0,0 +1,43 @@ +Commercial Support +============================================ + +The following content is commercially charged. For support, please email 1203593632@qq.com. + +- OHCI Driver + +.. figure:: img/ohci.png + +- ISO driver and UAC/UVC framework in EHCI IP, used with host UVC & UAC classes (this part is open source). ISO supports 1/2/3 packets per microframe, supports MJPEG and YUV cameras + +.. figure:: img/ehci_hostuvc1.png +.. figure:: img/ehci_hostuvc2.png + +Demonstrates USB Host UVC driver with 648 * 480 YUV camera. FPS 30. + +.. figure:: img/usbhost_uvc.gif + +- ISO driver and UAC/UVC framework in DWC2 IP, used with host UVC & UAC classes (this part is open source). ISO supports 1/2/3 packets per microframe, supports MJPEG and YUV cameras + +.. figure:: img/dwc2_hostuvc1.png +.. figure:: img/dwc2_hostuvc2.png +.. figure:: img/dwc2_hostuvc3.png +.. figure:: img/dwc2_hostuac.png + +- ISO driver and UAC/UVC framework in MUSB IP, used with host UVC & UAC classes (this part is open source). MUSB requires standard IP specified by Mentor Graphics company + +- Device MTP class driver, supports multiple files and folders, supports MCU-side file addition/deletion and synchronization with PC + +.. figure:: img/mtpdev.png + +- Device TMC class driver + +.. figure:: img/tmcdev1.png +.. figure:: img/tmcdev2.png + +- USB network class high-performance version optimization, includes CDC-NCM, CDC-RNDIS, proprietary class drivers (supports multi-packet transmission and reception), RNDIS example shown below + +.. figure:: img/rndistx.png +.. figure:: img/rndisrx.png + +- Customized class driver or IP driver adaptation +- Technical support services \ No newline at end of file diff --git a/docs/source/tools/img/chrytool1.png b/docs/en/tools/img/chrytool1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/tools/img/chrytool1.png rename to docs/en/tools/img/chrytool1.png diff --git a/docs/source/tools/img/chrytool2.png b/docs/en/tools/img/chrytool2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/tools/img/chrytool2.png rename to docs/en/tools/img/chrytool2.png diff --git a/docs/source/tools/img/chrytool3.png b/docs/en/tools/img/chrytool3.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/tools/img/chrytool3.png rename to docs/en/tools/img/chrytool3.png diff --git a/docs/source/tools/img/chrytool4.png b/docs/en/tools/img/chrytool4.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/tools/img/chrytool4.png rename to docs/en/tools/img/chrytool4.png diff --git a/docs/source/tools/img/chrytool5.png b/docs/en/tools/img/chrytool5.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/tools/img/chrytool5.png rename to docs/en/tools/img/chrytool5.png diff --git a/docs/source/tools/img/chrytool6.png b/docs/en/tools/img/chrytool6.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/tools/img/chrytool6.png rename to docs/en/tools/img/chrytool6.png diff --git a/docs/source/tools/img/chrytool7.png b/docs/en/tools/img/chrytool7.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/tools/img/chrytool7.png rename to docs/en/tools/img/chrytool7.png diff --git a/docs/en/tools/index.rst b/docs/en/tools/index.rst new file mode 100755 index 00000000..f6728b62 --- /dev/null +++ b/docs/en/tools/index.rst @@ -0,0 +1,49 @@ +chryusb_configurator +-------------------------- + +`chryusb_configurator `_ mainly serves to generate descriptor arrays when using the device protocol stack, which are then registered using `usbd_desc_register`. + +- First, we download chryusb_configurator.exe from GitHub, then install it all the way through. Then double-click to open it, click `Project`, and click `New Project` + +.. figure:: img/chrytool1.png + +- After creation, default descriptor configuration will be generated, including **Device Descriptor**, **Configuration Descriptor**, **String Descriptor**, and **String Descriptor** supports three by default + +.. figure:: img/chrytool2.png + +- Then we can modify the information of related descriptors as needed, such as VID and PID in **Device Descriptor**, class parameters, **Power** in **Configuration Descriptor**, etc. + +- Then for class addition, you need to click `File` and click `New File` + +.. figure:: img/chrytool3.png + +- Then the right side provides some class descriptor templates. Select one for initialization + +.. figure:: img/chrytool4.png + +- If there are multiple classes, repeat the above two steps + +- Then we modify the parameters of related endpoints as needed, such as direction, address, size, interval + +.. figure:: img/chrytool5.png + +- Finally click `File` and save the file with extension `.chry` +- Switch to the project file with extension `.chrybase`, then click `Add Group Configuration` to import the just configured class file + +.. figure:: img/chrytool6.png + +- Click `Project` and click `Save Project` +- Click `Compile` to generate descriptor arrays + +.. figure:: img/chrytool7.png + +- Copy the compiled files to your own project for use + +Lecroy USB Protocol Suite +-------------------------- + +Wireshark +-------------------------- + +Audacity +-------------------------- diff --git a/docs/source/usb/img/1.png b/docs/en/usb/img/1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/1.png rename to docs/en/usb/img/1.png diff --git a/docs/source/usb/img/10.png b/docs/en/usb/img/10.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/10.png rename to docs/en/usb/img/10.png diff --git a/docs/source/usb/img/11.png b/docs/en/usb/img/11.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/11.png rename to docs/en/usb/img/11.png diff --git a/docs/source/usb/img/12.png b/docs/en/usb/img/12.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/12.png rename to docs/en/usb/img/12.png diff --git a/docs/source/usb/img/13.png b/docs/en/usb/img/13.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/13.png rename to docs/en/usb/img/13.png diff --git a/docs/source/usb/img/14.png b/docs/en/usb/img/14.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/14.png rename to docs/en/usb/img/14.png diff --git a/docs/source/usb/img/15.png b/docs/en/usb/img/15.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/15.png rename to docs/en/usb/img/15.png diff --git a/docs/source/usb/img/16.png b/docs/en/usb/img/16.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/16.png rename to docs/en/usb/img/16.png diff --git a/docs/source/usb/img/17.png b/docs/en/usb/img/17.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/17.png rename to docs/en/usb/img/17.png diff --git a/docs/source/usb/img/18.png b/docs/en/usb/img/18.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/18.png rename to docs/en/usb/img/18.png diff --git a/docs/source/usb/img/19.png b/docs/en/usb/img/19.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/19.png rename to docs/en/usb/img/19.png diff --git a/docs/source/usb/img/2.png b/docs/en/usb/img/2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/2.png rename to docs/en/usb/img/2.png diff --git a/docs/source/usb/img/20.png b/docs/en/usb/img/20.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/20.png rename to docs/en/usb/img/20.png diff --git a/docs/source/usb/img/21.png b/docs/en/usb/img/21.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/21.png rename to docs/en/usb/img/21.png diff --git a/docs/source/usb/img/22.png b/docs/en/usb/img/22.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/22.png rename to docs/en/usb/img/22.png diff --git a/docs/source/usb/img/23.png b/docs/en/usb/img/23.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/23.png rename to docs/en/usb/img/23.png diff --git a/docs/source/usb/img/24.png b/docs/en/usb/img/24.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/24.png rename to docs/en/usb/img/24.png diff --git a/docs/source/usb/img/25.png b/docs/en/usb/img/25.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/25.png rename to docs/en/usb/img/25.png diff --git a/docs/source/usb/img/26.png b/docs/en/usb/img/26.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/26.png rename to docs/en/usb/img/26.png diff --git a/docs/source/usb/img/27.png b/docs/en/usb/img/27.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/27.png rename to docs/en/usb/img/27.png diff --git a/docs/source/usb/img/28.png b/docs/en/usb/img/28.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/28.png rename to docs/en/usb/img/28.png diff --git a/docs/source/usb/img/29.png b/docs/en/usb/img/29.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/29.png rename to docs/en/usb/img/29.png diff --git a/docs/source/usb/img/3.png b/docs/en/usb/img/3.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/3.png rename to docs/en/usb/img/3.png diff --git a/docs/source/usb/img/30.png b/docs/en/usb/img/30.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/30.png rename to docs/en/usb/img/30.png diff --git a/docs/source/usb/img/4.png b/docs/en/usb/img/4.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/4.png rename to docs/en/usb/img/4.png diff --git a/docs/source/usb/img/5.png b/docs/en/usb/img/5.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/5.png rename to docs/en/usb/img/5.png diff --git a/docs/source/usb/img/6.png b/docs/en/usb/img/6.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/6.png rename to docs/en/usb/img/6.png diff --git a/docs/source/usb/img/7.png b/docs/en/usb/img/7.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/7.png rename to docs/en/usb/img/7.png diff --git a/docs/source/usb/img/8.png b/docs/en/usb/img/8.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/8.png rename to docs/en/usb/img/8.png diff --git a/docs/source/usb/img/9.png b/docs/en/usb/img/9.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/9.png rename to docs/en/usb/img/9.png diff --git a/docs/source/usb/img/overview1.png b/docs/en/usb/img/overview1.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/overview1.png rename to docs/en/usb/img/overview1.png diff --git a/docs/source/usb/img/overview2.png b/docs/en/usb/img/overview2.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/overview2.png rename to docs/en/usb/img/overview2.png diff --git a/docs/source/usb/img/usb_enum.png b/docs/en/usb/img/usb_enum.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/usb_enum.png rename to docs/en/usb/img/usb_enum.png diff --git a/docs/source/usb/img/usb_request.png b/docs/en/usb/img/usb_request.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/usb_request.png rename to docs/en/usb/img/usb_request.png diff --git a/docs/source/usb/img/usbstruct.png b/docs/en/usb/img/usbstruct.png old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usb/img/usbstruct.png rename to docs/en/usb/img/usbstruct.png diff --git a/docs/en/usb/usb2.0_basic.rst b/docs/en/usb/usb2.0_basic.rst new file mode 100755 index 00000000..76dca6d2 --- /dev/null +++ b/docs/en/usb/usb2.0_basic.rst @@ -0,0 +1,294 @@ +USB Basic Concepts (2.0 Focus) +========================================= + +This document mainly explains Chapters 5, 7, 8, and 9 provided in the official USB manual `usb2.0.pdf `_. +If you are a beginner to USB, it's recommended not to read this section first, but to get the example demos running and become familiar with usage before reading. + +Introduction +----------------- + +What is USB? What is it used for? What are its advantages? You can search for these online, so I won't mention them. Let me first talk about USB interfaces and speed classifications according to different USB versions, as shown in the figure: + +.. figure:: img/overview1.png + +Next is the voltage level standard that USB needs to meet. With the voltage level standard, the signal states mentioned below can be classified. The voltage ranges and maximum currents supported by USB2.0 and USB3.0 are as follows: + +.. figure:: img/overview2.png + +USB Signal States +--------------------- + +First, we need to understand the Signaling Level in USB electrical characteristics, which refers to signal states. USB mainly relies on D+ and D- to achieve different signal states for communication. The official manual section 7.1.7 lists the requirements that D+ and D- need to meet for signal states corresponding to low-speed, full-speed, and high-speed operations. + +.. figure:: img/1.png +.. figure:: img/2.png +.. figure:: img/3.png + +- **Differential 0 and Differential 1**: These two states are used for general data communication through USB. When the D+ line is high and the D- line is low, this state is differential 1. When the D+ line is low and the D- line is high, this state is differential 0. +- **J State and K State**: In addition to differential signals, the USB specification also defines two other differential states: J state and K state. Their definitions are determined by device speed. On full-speed and high-speed devices, J state is differential 1 and K state is differential 0. On low-speed devices, this situation is reversed. +- **Single-Ended 0 (SE0)**: The state that occurs when both D+ and D- are at low level. This state indicates a reset, disconnection, or end of a data packet. +- **Single-Ended 1 (SE1)**: The state that occurs when both D+ and D- are at high level. This state is not intentionally generated and should not appear in USB design. +- **Idle**: A state that must occur before and after sending a data packet. If one data line is at low level and the other data line is at high level, it indicates an idle state. The definition of high and low levels is determined by the device speed. On full-speed devices, the idle state means D+ is high and D- is low. On low-speed devices, this situation is reversed. +- **Resume**: Used to wake up a device from suspended state. This operation is achieved by sending a K state. +- **Start of Packet (SOP)**: When the D+ and D- lines transition from idle state to K state, this will occur before starting a low-speed or full-speed data packet. +- **End of Packet (EOP)**: Occurs at the end of a low-speed or full-speed data packet. EOP occurs when the SE0 state lasts for two bit times (bit time will be introduced later) and the J state lasts for 1 bit time. +- **Reset**: Occurs when the SE0 state lasts for 10 ms. After SE0 lasts for at least 2.5 ms, the device will reset and begin entering the reset state. +- **Keep Alive**: A signal used in low-speed devices. Low-speed devices lack a start-of-frame packet (used to prevent suspended state). Every 1 ms, they use an EOP to prevent the device from entering suspended state. + +.. note:: It should be noted that for low-speed devices, the J and K states and differential 0/1 are opposite to those of full-speed/high-speed devices. + +Below, we use a waveform to distinguish these signal states: + +.. figure:: img/4.png + +- In the first red box, we can see the start of a data packet. Assuming this is a full-speed device, D+ is high and D- is low, which is an idle state. +- In the second red box, D+ is low and D- is high, indicating a K state. The transition from idle to K state indicates this is an SOP. +- Starting from the third red box represents data, showing JKJKJKJKJK. +- The fourth red box represents SE0, because both D+ and D- are at low level. +- In the fifth red box, after SE0 lasted for a period of time, it became D+ high and D- low, indicating it is a J state. The transition from SE0 to J state indicates this is an EOP. + +USB Speed Detection +------------------------- + +How is USB speed determined? This is described in manual section 7.1.5.1. USB speed detection mainly relies on 1.5K pull-up resistors on D+ and D- lines. If D+ has a 1.5k pull-up, the device is a full-speed device. If D- has a 1.5k pull-up, it is a low-speed device. High-speed devices initially appear as full-speed devices, with a 1.5k pull-up resistor on the D+ line just like full-speed devices. The USB2.0 hub treats it as a full-speed device. Subsequently, the hub and device confirm each other's identity through a series of handshake signals, ultimately determining the device as high-speed. + +.. figure:: img/5.png + +USB Connection and Disconnection Detection +--------------------------------------------- + +So when we plug our device into a USB host, how does the host know that a device has been inserted or removed? Manual section 7.1.7.3 provides the answer, as shown in the figure: + +.. figure:: img/6.png +.. figure:: img/7.png + +First is connection detection. The host detects that a data line level has been pulled high and maintained for a period of time, and considers that a device has been connected. When a low-speed device connects, the host will detect that the D- line is pulled high. When a full-speed/high-speed device connects, the host will detect that the D+ line is pulled high. +For disconnection detection, the pull-down resistors on the D+ and D- data lines on the host side take effect. After disconnection, both lines are at low level. When the low level persists for TDDIS time, it will be considered a disconnected state by the host. In the above figure, TDDIS is between 2 and 2.5us. + +USB Power +--------------------- + +As USB power, USB devices can be divided into two device types: bus-powered and self-powered. + +- Bus power is an advantage of USB design. Since devices are powered through the bus, they do not need to use bulky internal or external power supplies and can still maintain their own operation. The bus can be powered by the host or hub. When using a bus-powered device, users must consider its power consumption before configuring the device to a certain state. +- Self-powered devices power themselves by using external power sources (such as DC power adapters or batteries). Self-powered devices need to consider some precautions during the design process. The USB specification requires self-powered devices to continuously monitor their own VBUS line. During the time when VBUS is not present, the device must disconnect the power supplied to the pull-up resistors on the D+/D- lines, thereby preventing power supply to the host or hub. Otherwise, it will cause USB compliance testing to fail. However, self-powered hubs can obtain up to 100 mA of current from the bus. + +USB Device States +--------------------- + +At the moment when a USB device is plugged into the host, the device state of the USB device itself will change. This device state, as we will learn later in the enumeration process, actually describes the enumeration process. This part is described in manual section 9.1.1. + +.. figure:: img/9.png + +- **Attached**: This state occurs when a device is plugged into the host/hub, but the host/hub is not supplying power to the VBUS line. It usually occurs when the hub detects an overcurrent event. Although the device is still connected, the host has removed the power supply to it. +- **Powered**: A device is connected to USB and receiving power, but has not yet received a reset request. +- **Default**: A device is connected to USB, receiving power, and has been reset by the host. At this time, the device has no device address and will respond to address 0. +- **Address**: A device is connected to USB, receiving power, has been reset, and has a unique address. However, the device is still not configured. +- **Configured**: The device is connected to USB, receiving power, has been reset, has a unique address, and is configured, but has not yet entered suspended state. At this time, bus-powered devices can consume more than 100 mA of current. +- **Suspended**: As described above, the device has established connection and is configured, but will not perform any bus operations within 3 ms. + +The diagram translated into English is: + +.. figure:: img/10.png + +USB Encoding and Bit Stuffing +----------------------------------- + +First, USB data is transmitted serially, just like UART, I2C, SPI, etc. Continuous 01 signals are sent to the receiver through only one data line. However, because the sender and receiver operate at different frequencies, signal synchronization becomes an issue. For example, when the receiver receives a low level that lasts for a period of time, it cannot determine whether this represents 5 zeros or 1000 zeros. One solution is to add a clock signal while transmitting the data signal to synchronize transmission at both ends. The receiver samples the data signal with the assistance of the clock signal to correctly parse the transmitted data. I2C does this, with SDA transmitting data and SCL transmitting the synchronization clock: + +.. figure:: img/11.png + +Although this solves the problem, it requires an additional clock signal line to transmit the clock. Since USB has no clock signal, is there a way to maintain synchronization at both ends without needing an additional clock signal? +Yes, this is RZ encoding (Return-to-zero Code), also called return-to-zero encoding. + +RZ Encoding (Return-to-zero Code) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +RZ encoding (Return-to-zero Code) is also called return-to-zero encoding. In RZ encoding, positive level represents logic 1, negative level represents logic 0, and after each bit of data is transmitted, the signal returns to zero level. That is, three voltage levels appear on the signal line: positive level, negative level, and zero level. + +.. figure:: img/12.png + +As can be seen from the diagram, because each bit is reset to zero after transmission, the receiver only needs to sample after the signal is reset to zero, thus eliminating the need for a separate clock signal. In fact, RZ encoding is equivalent to encoding the clock signal into the data using a reset-to-zero method. Such a signal is also called a self-clocking signal. +While this saves on clock and data lines, it still has drawbacks because in RZ encoding, most of the data bandwidth is wasted on transmitting "return to zero". +NRZ Encoding (Non-return-to-zero Code) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Removing this return-to-zero step, NRZ encoding (Non-return-to-zero Code) emerged. The difference from RZ is that NRZ does not require return to zero. + +.. figure:: img/13.png + +NRZI Encoding (Non-Return-to-Zero Inverted Code) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The difference between NRZI encoding (Non-Return-to-Zero Inverted Code) and NRZ is that NRZI uses signal transitions to represent one logic and signal maintenance to represent another logic. This is described in manual section 7.1.8. + +.. figure:: img/14.png + +As shown in the figure, we can derive a simple memory method: when encountering a 0 edge, the level flips; when encountering a 1 edge, it remains unchanged. + +Bit Stuffing +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +However, there is still a problem. Although the receiver can actively match the sender's frequency, there will always be errors between them. If the data signal consists of 1000 logic 1s, after USB NRZI encoding, it becomes a very long period without level changes. In this situation, even if the receiver's frequency differs from the sender by one thousandth, it will cause the data to be sampled as 1001 or 999 ones. +USB's solution to this problem is forced bit insertion, also known as bit stuffing. If the data to be transmitted contains 6 consecutive 1s, a 0 is forcibly inserted after the 6th 1 before transmission, forcing the transmitted signal to transition and thereby forcing the receiver to adjust frequency. +The receiver only needs to delete the 0 after 6 consecutive 1s to restore the original data. This is described in manual section 7.1.9. + +.. figure:: img/15.png +.. figure:: img/16.png +.. figure:: img/17.png + +Before data is NRZI encoded, a zero is inserted after every six consecutive ones in the data stream to force transitions in the NRZI data stream, which gives the receiver logic at least one data transition every seven bits to ensure data and clock lock. Bit stuffing is enabled starting from sync pattern. The data "one" that ends the sync pattern is counted as the first "one" in the sequence. Transmitter bit stuffing is always enforced except during high-speed EOP. If required by bit stuffing rules, a zero bit will be inserted even if it is the last bit before the end of packet (EOP) signal. The receiver must decode NRZI data, identify stuffed bits, and discard them. + +.. caution:: The following content can be summarized in one diagram. Understanding it is sufficient; there is no need to memorize it. + +.. figure:: img/usbstruct.png + +USB Fields +--------------------- + +USB fields constitute the most basic and smallest unit in USB communication. Later packets and transactions are fundamentally composed of fields, while fields are composed of bits. The fields section is described in manual section 8.1. + +.. note:: USB's bit transmission mode follows the LSB-first principle. + +Sync Field +^^^^^^^^^^^^^^^^^^^^^^^^ + +In USB systems, the host and device do not share a clock, which makes it impossible for the receiver to accurately know when the sender is sending data. Although SOP can be detected, this is far from sufficient. Therefore, a sync field is needed to keep the receiver and sender synchronized during the transmission process, so every packet must start with a sync field. The sync field is 0x01, which after encoding becomes 10101000B. + +.. figure:: img/18.png + +Packet Identifier Field +^^^^^^^^^^^^^^^^^^^^^^^^ + +PID consists of a four-bit packet type field and a four-bit check field, occupying 8 bits, as shown in the figure. PID indicates the packet type and, by inference, the packet format and the type of error detection applied to the packet. The four-bit check field of PID is generated by performing a one's complement of the packet type field, ensuring reliable decoding of PID so that the rest of the packet can be correctly interpreted. If the four PID check bits are not the complement of their respective packet identifier bits, a PID error exists. + +.. figure:: img/19.png + +Since there are 4 bits, this means PID types can be divided into 16 types. These 16 types are further subdivided into 4 categories: Token PID, Data PID, Handshake PID, and Special PID. + +.. figure:: img/20.png + +Address Field +^^^^^^^^^^^^^^^^^^^^^^^^ + +The address field is divided into device address field and endpoint address field. The device address field occupies 7 bits. Excluding address 0, the host can allocate 127 addresses. + +.. figure:: img/21.png + +The endpoint address field occupies 4 bits, providing a total of 16 endpoints. + +.. figure:: img/22.png + +Frame Number Field +^^^^^^^^^^^^^^^^^^^^^^^^ + +The frame number field occupies 11 bits. Each time the host sends a frame, the frame number increases by 1, as shown in the figure. In high-speed devices, frames contain microframes. 1 frame = 8 microframes, and microframes increment by 0.1. The concepts of frames and microframes will be supplemented later. + +.. figure:: img/23.png + +Data Field +^^^^^^^^^^^^^^^^^^^^^^^^ + +Depending on the transmission type, the data length in the data field varies from 0-1024 bytes. + +.. figure:: img/24.png + +CRC Field +^^^^^^^^^^^^^^^^^^^^^^^^ + +Cyclic Redundancy Check (CRC) is used to protect all non-PID fields in token and data packets. PID is not included in the CRC check of packets containing CRC. All CRCs are generated on individual fields in the transmitter before bit stuffing is performed. Similarly, CRC is decoded in the receiver after stuffed bits are removed. Token and data packet CRCs provide 100% coverage for all single-bit and double-bit errors. CRC failure is considered to indicate that one or more protected fields have been corrupted and causes the receiver to ignore those fields and, in most cases, ignore the entire packet. + +.. figure:: img/24.png + +- Token CRC + +A five-bit CRC field is provided for tokens and covers the ADDR and ENDP fields of IN, SETUP, and OUT tokens or the timestamp field of SOF tokens. PING and SPLIT special tokens also include a five-bit CRC field. + +The generator polynomial is: G(X) = X^5 + X^2 + 1 +The binary bit pattern representing this polynomial is 00101B. If all token bits are received without error, the five-bit checksum at the receiver will be 01100B. + +- Data CRC + +Data CRC is a 16-bit polynomial applied to the data field of data packets. + +The generator polynomial is: G(X) = X^16 + X^15 + X^2 + 1 +The binary bit pattern representing this polynomial is 1000000000000101B. If all data and CRC bits are received without error, the 16-bit checksum will be 1000000000001101B. + +USB Packets +--------------------- + +Packets are composed of fields. According to PID type, packets are divided into four major categories: Token packets, Data packets, Handshake packets, and Special packets. This section is described in official section 8.4.1. + +.. figure:: img/25.png + +Including SOP, as shown in the figure, forms a complete packet. + +.. figure:: img/26.png + +Token Packets +^^^^^^^^^^^^^^^^^^^^^^^^ + +Token packets are divided into: SETUP, IN, OUT, SOF. Among them, SETUP, IN, and OUT have the same field composition, as shown: + +.. figure:: img/27.png + +- PID field: Defines the data transfer direction from USB host to USB device. +- ADDR field: Specifies the USB device address. +- ENDP field: Specifies the endpoint number for receiving data. +- CRC field: Performs cyclic redundancy check for ADDR and ENDP fields. + +SOF packet field composition, as shown: + +.. figure:: img/28.png + +- PID field: Defines the data transfer direction from USB host to USB device. +- Frame Number field: Specifies the frame number of USB transmission, which is 11 bits. +- CRC field: Performs cyclic redundancy check for ADDR and ENDP fields. + +Data Packets +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. figure:: img/29.png + +- PID field: Used to specify different data packet types. Supports 4 types of data packets: DATA0, DATA1, DATA2, and MDATA. +- Data field: Contains the transmitted data. The data size depends on the data transfer type and user requirements. According to USB protocol specifications, for low-speed USB data transmission, the maximum length is 8 bytes; for full-speed USB data transmission, the maximum length is 1023 bytes; for high-speed USB data transmission, the maximum data length is 1024 bytes. +- CRC field: Uses 16-bit cyclic redundancy check to protect the data field. + +Handshake Packets +^^^^^^^^^^^^^^^^^^^^^^^^ + +Handshake packets consist of an 8-bit PID and are used at the end of data transmission to report the status of this data transmission. The handshake packet is followed by the EOP signal that marks the end of the entire transaction. + +.. figure:: img/30.png + +Special Packets +^^^^^^^^^^^^^^^^^^^^^^^^ + +USB Transactions +--------------------- + +There are three commonly used USB transactions: SETUP, IN, OUT. Except for control transfers which use three transactions, other transfers use two transactions. Special transactions are transactions that do not carry data. + +SETUP Transaction +^^^^^^^^^^^^^^^^^^^^^^^^ + +IN Transaction +^^^^^^^^^^^^^^^^^^^^^^^^ + +OUT Transaction +^^^^^^^^^^^^^^^^^^^^^^^^ + +Special Transaction +^^^^^^^^^^^^^^^^^^^^^^^^ + +USB Transfers +--------------------- + +Control Transfer +^^^^^^^^^^^^^^^^^^^^^^^^ + +Bulk Transfer +^^^^^^^^^^^^^^^^^^^^^^^^ + +Interrupt Transfer +^^^^^^^^^^^^^^^^^^^^^^^^ + +Isochronous Transfer +^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/usb/usb3.0_basic.rst b/docs/en/usb/usb3.0_basic.rst new file mode 100755 index 00000000..ccd03d08 --- /dev/null +++ b/docs/en/usb/usb3.0_basic.rst @@ -0,0 +1,32 @@ +USB Basic Concepts (3.0 Focus) +========================================= + +Introduction +------------ + + + +Similarities and Differences with USB 2.0 +-------------------------- + + +Link Layer +-------------------- + +LCW +^^^^^^^^^^ + +Protocol Layer +-------------------- + +LMP +^^^^^^^^^^^^^^^^^^^^^^^^ + +TP +^^^^^^^^^^^^^^^^^^^^^^^^ + +DP +^^^^^^^^^^^^^^^^^^^^^^^^ + +ITP +^^^^^^^^^^^^^^^^^^^^^^^^ \ No newline at end of file diff --git a/docs/en/usb/usb_desc.rst b/docs/en/usb/usb_desc.rst new file mode 100755 index 00000000..e4014d5f --- /dev/null +++ b/docs/en/usb/usb_desc.rst @@ -0,0 +1,37 @@ +USB Descriptors +========================================= + +This section references the official USB 2.0 PDF section 9.5. + +Device Descriptor +------------------------------------------------------------ + +Configuration Descriptor +------------------------------------------------------------ + +Interface Descriptor +------------------------------------------------------------ + +Endpoint Descriptor +------------------------------------------------------------ + +String Descriptor +------------------------------------------------------------ + +Interface Association Descriptor +------------------------------------------------------------ + +Device Qualifier Descriptor +------------------------------------------------------------ + +Other Speed Descriptor +------------------------------------------------------------ + +BOS Descriptor +------------------------------------------------------------ + +SuperSpeed Endpoint Companion Descriptor +------------------------------------------------------------ + +Enhanced SuperSpeed Isochronous Endpoint Companion Descriptor +---------------------------------------------------------------------- diff --git a/docs/en/usb/usb_enum.rst b/docs/en/usb/usb_enum.rst new file mode 100755 index 00000000..45cf297c --- /dev/null +++ b/docs/en/usb/usb_enum.rst @@ -0,0 +1,22 @@ +USB Enumeration +========================================= + +After understanding USB device requests, we can learn about the entire enumeration process of USB devices and see how devices like serial ports, mice, and USB drives are enumerated. During enumeration, the host will send device requests to obtain relevant information (i.e., descriptors). For specific requests sent, refer to the diagram below. + +.. figure:: img/usb_enum.png + +- First, connect the device to the USB cable, then plug it into the computer +- After the device is plugged in, it powers up and enters a powered state +- The host detects device insertion through D+/D- +- Reset the device +- Host sends **Get Device Descriptor Request** +- Optional reset operation +- Host sends **Set Device Address Request** +- Host sends **Get Configuration Descriptor Request**, may be obtained multiple times, which doesn't matter +- Host sends **Get String Descriptor Request**, normally obtains 3 strings, and continues to obtain specified strings if they are specified in subsequent descriptors +- Host sends **Get Device Qualifier Descriptor Request**, used to obtain requests when the device operates at other speeds. If the device can only work in full-speed mode, it must reply with stall, and the protocol stack will definitely print this request to inform you that the device does not support this command. +- Host sends **Set Configuration Request**, configures device endpoints, usually based on the configuration in endpoint descriptors. +- Standard device requests end here +- Host loads corresponding supported class drivers based on interface descriptors. If the host doesn't support them, it will prompt that no driver is found for the device +- After loading is complete, begins executing related requests for that class +- Finally performs class data flow transmission \ No newline at end of file diff --git a/docs/en/usb/usb_ext.rst b/docs/en/usb/usb_ext.rst new file mode 100755 index 00000000..b2250437 --- /dev/null +++ b/docs/en/usb/usb_ext.rst @@ -0,0 +1,39 @@ +.. _usb_ext: + +USB Knowledge Extension +========================================= + +What is Packetization +------------------------- + +Due to USB protocol specifications defining the maximum length of each packet, when we send data that exceeds the maximum packet length, we need to send it in packets - this is packetization. For example, if EP MPS is 64 and data length is 129, USB will transmit in the form of 64 + 64 + 1. +For USB IP, packetization is divided into software packetization and hardware packetization. Software packetization means user code handles packetization itself - this type of IP generally uses FIFO because FIFO depth is limited. The second type +uses hardware packetization. This type of USB IP generally comes with DMA or descriptor DMA functionality, making this type of IP undoubtedly the most efficient. CherryUSB fully utilizes this point, enabling USB speed to reach its maximum. + +For software packetization, even if the transmission length is 16K at once, **it is internally handled through software packetization. In this case, the transmission length has no impact on speed improvement**. +For hardware packetization, the transmission length affects speed because hardware packetization is performed through DMA, **the larger the transmission length at one time, the higher the DMA efficiency and the faster the speed**. (Of course, although other protocol stacks use DMA, some code implementations still process one packet at a time, which is equivalent to not using it, and this is also a reason for low speed) + +What is a Short Packet +---------------------------- + +Based on what we discussed about packetization above, a short packet is the last packet in the packetization (and its length is less than EP MPS). For example, when sending 129 bytes of data, USB will transmit it in the form of 64 + 64 + 1, where the last packet is 1 byte, and this 1 byte is the short packet. + +What is ZLP +------------- + +ZLP, as the name suggests, is a Zero-Length Packet, which is a short packet with data length of 0. It's used by USB devices at the end of data transmission. If the data length is exactly a multiple of the maximum packet length, then a ZLP packet needs to be sent to inform the other party that data transmission has ended. + +.. caution:: ZLP functionality is limited to CONTROL and BULK transfers + +When is an Interrupt Considered Complete +-------------------------------------------- + +Device reception: The received length equals the set length; the last received packet is a short packet. +Device transmission: The transmitted length equals the set length. If the transmitted length is a multiple of EP MPS, **usually** a ZLP needs to be sent additionally (limited to control and bulk transfers). + +.. note:: For device reception and bulk transfers, the reception length is usually designed as EP MPS. The following three cases can be modified to multiple EP MPS: fixed length; custom protocol with length information (e.g., MSC); host manually sends ZLP or short packet (e.g., RNDIS) + +.. note:: For device transmission and bulk transfers, there is no limit on transmission length, but if it is a multiple of EP MPS, ZLP usually needs to be sent. Custom protocols do not need to send ZLP, such as MSC. + +Host reception: Same as device reception +Host transmission: The transmitted length equals the set length diff --git a/docs/en/usb/usb_request.rst b/docs/en/usb/usb_request.rst new file mode 100755 index 00000000..75b29c15 --- /dev/null +++ b/docs/en/usb/usb_request.rst @@ -0,0 +1,6 @@ +USB Device Requests +========================================= + +This section references official USB 2.0 PDF sections 9.3 and 9.4. + +.. figure:: img/usb_request.png diff --git a/docs/source/usbdev.svg b/docs/en/usbdev.svg old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbdev.svg rename to docs/en/usbdev.svg diff --git a/docs/source/usbhost.svg b/docs/en/usbhost.svg old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbhost.svg rename to docs/en/usbhost.svg diff --git a/docs/source/usbip/cdns2.rst b/docs/en/usbip/cdns2.rst old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbip/cdns2.rst rename to docs/en/usbip/cdns2.rst diff --git a/docs/source/usbip/cdns3.rst b/docs/en/usbip/cdns3.rst old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbip/cdns3.rst rename to docs/en/usbip/cdns3.rst diff --git a/docs/source/usbip/chipidea.rst b/docs/en/usbip/chipidea.rst old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbip/chipidea.rst rename to docs/en/usbip/chipidea.rst diff --git a/docs/source/usbip/dwc2.rst b/docs/en/usbip/dwc2.rst old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbip/dwc2.rst rename to docs/en/usbip/dwc2.rst diff --git a/docs/source/usbip/dwc3.rst b/docs/en/usbip/dwc3.rst old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbip/dwc3.rst rename to docs/en/usbip/dwc3.rst diff --git a/docs/source/usbip/ehci.rst b/docs/en/usbip/ehci.rst old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbip/ehci.rst rename to docs/en/usbip/ehci.rst diff --git a/docs/source/usbip/fotg210.rst b/docs/en/usbip/fotg210.rst old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbip/fotg210.rst rename to docs/en/usbip/fotg210.rst diff --git a/docs/source/usbip/musb.rst b/docs/en/usbip/musb.rst old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbip/musb.rst rename to docs/en/usbip/musb.rst diff --git a/docs/source/usbip/ohci.rst b/docs/en/usbip/ohci.rst old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbip/ohci.rst rename to docs/en/usbip/ohci.rst diff --git a/docs/source/usbip/xhci.rst b/docs/en/usbip/xhci.rst old mode 100644 new mode 100755 similarity index 100% rename from docs/source/usbip/xhci.rst rename to docs/en/usbip/xhci.rst diff --git a/docs/en/version.rst b/docs/en/version.rst new file mode 100755 index 00000000..b4e6b680 --- /dev/null +++ b/docs/en/version.rst @@ -0,0 +1,180 @@ +Version Information +============================================ +If there are no special circumstances, please use the latest version. The following lists only important updates. For detailed update information, please refer to https://github.com/cherry-embedded/CherryUSB/releases. + +<= v0.10.2 Initial Version +--------------------------- + +- **Used to establish basic host/device framework, supporting only single USB IP**. +- **Host driver where each EP occupies one hardware pipe, does not support dynamic hardware pipe usage**. +- Related porting requires this version, no longer supported in subsequent versions (such as ch32, rp2040), as well as old versions of pusb2 and xhci (new versions no longer provide source code). + +v1.0.0 Transition Version +--------------------------- + +- **Host supports dynamic hardware pipe usage, no longer fixed** + +v1.1.0 Transition Version +--------------------------- + +- **Host and device support multiple USB IPs of the same type** +- **Host adds bluetooth, ch340, ftdi, cp210x, asix drivers** +- Device MSC supports multiple LUN, and CONFIG_USBDEV_MSC_BLOCK_SIZE changed to CONFIG_USBDEV_MSC_MAX_BUFSIZE + +v1.2.0 +--------------------------- + +- **Host adds rtl8152, cdc ncm drivers** +- Host adds timer to control interrupt transfers (hub modified to use timer control) +- Porting adds esp, aic host drivers +- **Optimize DWC2 code for easier reading, and add some FIFO configuration macros for users (because dwc2 fifo size is limited and there are many configuration methods, so exported to users for reasonable performance control)** +- Optimize ehci driver (qtd no longer uses dynamic allocation, bound to qh), for faster code execution + +v1.3.0 +--------------------------- + +- **Device supports automatic selection of multiple speed descriptors (enable CONFIG_USBDEV_ADVANCE_DESC)** +- Device core code unifies ep0 buffer usage for code beautification +- Host adds pl2303 driver; uses id table to support multiple VID/PID; adds user_data for user use +- Host network class driver adds TX/RX buffer macros, adds LWIP_TCPIP_CORE_LOCKING_INPUT usage for data zero-copy implementation +- Porting imports bouffalo, aic, stm32f723 device drivers +- **Fixed issue in porting host section where urb->timeout clearing had problems (no pipe alloc exception during large data transfers, mainly because transfer completed just after starting, timeout was modified to 0 before checking, didn't enter take sem flow), fixed in this version** +- EHCI enables IAAD in usbh_kill_urb, reads EHCI HCOR offset from HCCR caplength, enables OHCI for EHCI +- Adapted for NuttX OS + +v1.3.1 +--------------------------- + +- Bugfix (audio, video, CDC ECM related macros, structures, APIs) +- **Host hub enumeration thread removed, uses PSC thread, enumeration method changed to queue mode, canceled simultaneous enumeration of multiple devices functionality** +- Host scan driver information and instance uses recursive mode, removes linked list scanning +- Host network class driver optimization, supports receiving data above 16K (CDC ECM not supported), uses advanced memcpy API +- **Device protocol stack printing removed (no more printing in interrupts)** +- Porting MUSB FIFO configuration changed to obtain from FIFO table (this code references Linux), adapted for ES32, SUNXI, BEKEN + +v1.4.0 +--------------------------- + +- **Device starts supporting remote wakeup functionality, HID request(0x21), improved GET STATUS request (starting from this version can pass USB3CV testing)** +- Device adds UF2, ADB, WEBUSB functionality; MSC adds bare-metal read/write polling functionality, puts read/write in while1 execution; usbd_cdc renamed to usbd_cdc_acm +- Host adds USB WiFi(bl616), Xbox drivers; **restructured USB3.0 enumeration logic** +- **Host CDC_ACM, HID, MSC, serial transmission shared buffer, would have issues if multiple identical devices exist, changed to separate buffers** +- **Porting restructured XHCI/PUSB2 drivers, not open source**; EHCI and OHCI files renamed; added remote wakeup API +- ESP component library support +- **ChipIdea device driver support, NXP MCX series host/device support** +- ThreadX OS support + +v1.4.1 +--------------------------- + +- **Fixed device mode issue with repeated endpoint closure when using multiple altsettings, changed to close when altsetting is 0** +- **Restructured host audio descriptor parsing** +- **Added Kinetis USB IP** +- Host usbh_msc_get_maxlun request not supported by some USB drives, no error return +- Host usbh_hid_get_report_descriptor exported for user calls +- Static code checking +- GitHub action functionality + +v1.4.2 +--------------------------- + +- Device implements USB_REQUEST_GET_INTERFACE request +- **Device video transmission restructured, added dual buffering functionality** +- Device ECM restructured, maintains similar API to RNDIS +- Device and host audio volume configuration functionality restructured +- Host adds AOA driver +- C++ compatibility related modifications +- FSDEV doesn't support ISO and DWC2 high-speed hub doesn't support full-speed/low-speed checking +- **General OHCI code updates** + +v1.4.3 +--------------------------- + +- **Device EP0 processing adds thread mode** +- Device audio feedback macros and demo +- Device RNDIS adds passthrough functionality (without LWIP) +- **Host MSC moves SCSI initialization out of enumeration thread, calls it during mount phase, and adds testunit retries multiple times to be compatible with some USB drives** +- RP2040 host/device support +- **NuttX FS, serial, net component support** +- DWC2, EHCI, OHCI host DCache functionality support (improved in v1.5.0) +- T113, MCXA156, CH585, **STM32H7R support** +- Fixed issue in v1.4.1 where altsetting 0 should close all endpoints + +v1.5.0 +--------------------------- + +- **Protocol stack internal global buffer needs to use USB_ALIGN_UP alignment, for use when DCache is enabled and nocache is not enabled** +- **Improved EHCI/OHCI DCache mode handling**, add CONFIG_USB_EHCI_DESC_DCACHE_ENABLE for qh&qtd&itd, add CONFIG_USB_OHCI_DESC_DCACHE_ENABLE for ed&td +- **Platform code updates, platform-related moved to platform, added LVGL keyboard/mouse support, blackmagic support, FileX support, Zephyr disk support, ESP-IDF netif support** +- **Device SOF callback support** +- **DWC2, FSDEV ST implements low-level API and interrupts, directly calls HAL_PCD_MSP and HAL_HCD_MSP, no need for user copy-paste** +- **DWC2 implements SPLIT functionality, supports external high-speed hub interfacing with FS/LS devices in high-speed mode** +- LiteOS-M, Zephyr OS support +- Device MSC bare-metal read/write uses variable mode instead of ringbuffer +- EHCI QTD uses qtd alloc & free, saves memory, currently QH carries QTD +- RNDIS/ECM device, MSC demo updates, supports modification-free under RT-Thread +- **All memcpy replaced with usb_memcpy, ARM library has non-aligned access issues** +- **Restructured device MTP driver (commercial use)** +- **Device TMC driver (commercial use)** +- **Restructured device video transmission, directly fills UVC header in image data, achieving zero memcpy** +- **Added usb_osal_thread_schedule_other API for releasing all class threads before releasing class resources, avoiding threads still using class resources after class resources are released** +- **DWC2 device adds DCache functionality, usable for Cortex-M7/ESP32P4** +- **Bouffalo/HPM/ESP/ST/NXP DCache API support** +- CH32 device ISO updates, IP directory reclassification +- CMake, SCons, Kconfig updates +- Use USB_ASSERT_MSG for partial code checking, comprehensive warning fixes +- N32H4/MM32F5 device support +- Default enable CONFIG_USBDEV_ADVANCE_DESC + +v1.5.1 +--------------------------- + +- Support using ADB shell under RT-Thread, host serial/device CDC_ACM interfaces with RTDevice framework +- **DWC2 adds multiple USB port configuration functionality with different parameters, e.g., one full-speed and one high-speed, with different FIFO and PHY configurations** +- **EHCI control transfer memory leak when no data phase causes data QTD not to be released** +- **DWC2 reads setup using usbd_get_next_ep0_state to judge, avoiding conflict between setup and EP0 out usage under USB_OTG_DOEPINT_XFRC state** +- SIFLI USB device preliminary support + +v1.5.2 +--------------------------- + +- Some bugfixes for RT-Thread components under 1.5.1 +- IDF timer OSAL replaced with ESP timer, FreeRTOS timer may fail to start; xTaskCreate replaced with xTaskCreatePinnedToCore for multi-core convenience +- In host enumeration, removed descriptor overflow related ASSERT operations, changed to return error. String descriptor acquisition changed to only get if supported. 2ms delay changed to 10ms because some OS use 100Hz, causing delay invalidation +- **DWC2 EP mult support, split transfer code optimization, modified split-related cache handling** +- **DWC2 halt cannot clear USB_OTG_HCCHAR_EPDIR, reset port uses timeout mechanism to prevent deadlock due to disconnection during enumeration** +- Updated DWC2 AT32, STM32, Kendryte, Espressif glue code +- MUSB for standard IP structure uses independent EP control register groups, not using EPIDX register for control +- Removed all CONFIG_USBDEV_EP_NUM & CONFIG_USBHOST_PIPE_NUM, no longer used because IP itself carries this information or manufacturer SDK provides corresponding macros +- CONFIG_USBHOST_MAX_INTF_ALTSETTINGS defaults to 2 to reduce memory, only UVC and UAC use it (commercial charging), so no need to set it large +- URB interval changed from u8 to u32, maximum support 2^15 * 125us + +v1.5.3 +--------------------------- + +- Added mongoose demo +- **Device supports custom EP0 MPS, only supports commercial IPs** +- Host adds UVC bulk support, **interface number matching driver functionality**, **host address allocation changed to cyclic increment mode**, restructured lsusb command +- Host control transfer adds retry mechanism, some devices have unstable communication, retry count references Linux +- **Host RNDIS driver adds non-standard 02/02/ff interface driver matching** +- MUSB IP disables multipoint feature support +- HPMicro, ChipIdea DCache support +- IDF host MSC support +- OTG framework restructured, current port only supports HPMicro +- CI compilation functionality, supports HPMicro/Espressif/BouffaloLab + +v1.5.3.99 +--------------------------- + +Bugfix for v1.5.3 + +v1.6.0 +--------------------------- + +- **Host adds serial framework, unifies all serial-like drivers** +- **Host HID adds report descriptor parsing functionality** +- usbh_initialize adds event callback to notify users of host event changes, usually not needed, can be set to NULL +- Support gamepad device +- Added TI XMC, Infineon Edge E8x port support +- DWC2 adds usbd_dwc2_get_system_clock to replace SystemCoreClock; removes __UNALIGNED_UINT32_READ and __UNALIGNED_UINT32_WRITE macros; setup count set to 1; first setup read moved to USB_OTG_GINTSTS_ENUMDNE interrupt +- DWC2/EHCI adds root hub speed setting \ No newline at end of file diff --git a/docs/zh/.readthedocs.yaml b/docs/zh/.readthedocs.yaml new file mode 100644 index 00000000..e94ddd80 --- /dev/null +++ b/docs/zh/.readthedocs.yaml @@ -0,0 +1,35 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + # You can also specify other tool versions: + # nodejs: "20" + # rust: "1.70" + # golang: "1.20" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/zh/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 + # fail_on_warning: true + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/source/api/api_config.rst b/docs/zh/api/api_config.rst similarity index 100% rename from docs/source/api/api_config.rst rename to docs/zh/api/api_config.rst diff --git a/docs/source/api/api_device.rst b/docs/zh/api/api_device.rst similarity index 99% rename from docs/source/api/api_device.rst rename to docs/zh/api/api_device.rst index bc8cb100..4c6617b1 100644 --- a/docs/source/api/api_device.rst +++ b/docs/zh/api/api_device.rst @@ -260,6 +260,7 @@ MSC usbd_msc_init_intf """""""""""""""""""""""""""""""""""" + ``usbd_msc_init_intf`` 用来初始化 MSC 类接口，并实现该接口相关函数，并且注册端点回调函数。（因为 msc bot 协议是固定的，所以不需要用于实现，因此端点回调函数自然不需要用户实现）。 - ``msc_storage_class_interface_request_handler`` 用于处理 USB MSC Setup 中断请求。 @@ -326,6 +327,7 @@ UAC usbd_audio_init_intf """""""""""""""""""""""""""""""""""" + ``usbd_audio_init_intf`` 用来初始化 USB Audio 类接口，并实现该接口相关的函数： - ``audio_class_interface_request_handler`` 用于处理 USB Audio Setup 接口接收者中断请求。 @@ -424,6 +426,7 @@ UVC usbd_video_init_intf """""""""""""""""""""""""""""""""""" + ``usbd_video_init_intf`` 用来初始化 USB Video 类接口，并实现该接口相关的函数： - ``video_class_interface_request_handler`` 用于处理 USB Video Setup 中断请求。 diff --git a/docs/source/api/api_host.rst b/docs/zh/api/api_host.rst similarity index 100% rename from docs/source/api/api_host.rst rename to docs/zh/api/api_host.rst diff --git a/docs/source/api/api_port.rst b/docs/zh/api/api_port.rst similarity index 100% rename from docs/source/api/api_port.rst rename to docs/zh/api/api_port.rst diff --git a/docs/zh/api/img/api_device1.png b/docs/zh/api/img/api_device1.png new file mode 100644 index 00000000..ba218b65 Binary files /dev/null and b/docs/zh/api/img/api_device1.png differ diff --git a/docs/zh/api/img/api_host1.png b/docs/zh/api/img/api_host1.png new file mode 100644 index 00000000..82932f50 Binary files /dev/null and b/docs/zh/api/img/api_host1.png differ diff --git a/docs/zh/api/img/api_host2.png b/docs/zh/api/img/api_host2.png new file mode 100644 index 00000000..7f6d60b8 Binary files /dev/null and b/docs/zh/api/img/api_host2.png differ diff --git a/docs/source/class/class_audio.rst b/docs/zh/class/class_audio.rst similarity index 100% rename from docs/source/class/class_audio.rst rename to docs/zh/class/class_audio.rst diff --git a/docs/source/class/class_cdc.rst b/docs/zh/class/class_cdc.rst similarity index 100% rename from docs/source/class/class_cdc.rst rename to docs/zh/class/class_cdc.rst diff --git a/docs/source/class/class_hid.rst b/docs/zh/class/class_hid.rst similarity index 100% rename from docs/source/class/class_hid.rst rename to docs/zh/class/class_hid.rst diff --git a/docs/source/class/class_msc.rst b/docs/zh/class/class_msc.rst similarity index 100% rename from docs/source/class/class_msc.rst rename to docs/zh/class/class_msc.rst diff --git a/docs/source/class/class_video.rst b/docs/zh/class/class_video.rst similarity index 100% rename from docs/source/class/class_video.rst rename to docs/zh/class/class_video.rst diff --git a/docs/source/class/winusb.rst b/docs/zh/class/winusb.rst similarity index 100% rename from docs/source/class/winusb.rst rename to docs/zh/class/winusb.rst diff --git a/docs/zh/conf.py b/docs/zh/conf.py new file mode 100644 index 00000000..22427158 --- /dev/null +++ b/docs/zh/conf.py @@ -0,0 +1,37 @@ +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = 'CherryUSB' +copyright = '2022 ~ 2026, sakumisu' +author = 'sakumisu' + +release = '1.6.0' +version = '1.6.0' + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'recommonmark', + 'sphinx_markdown_tables' +] + +intersphinx_mapping = { +# 'python': ('https://docs.python.org/3/', None), +# 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# -- Options for EPUB output +epub_show_urls = 'footnote' diff --git a/docs/zh/demo/img/cherryadb.png b/docs/zh/demo/img/cherryadb.png new file mode 100644 index 00000000..512586b9 Binary files /dev/null and b/docs/zh/demo/img/cherryadb.png differ diff --git a/docs/zh/demo/img/otg.png b/docs/zh/demo/img/otg.png new file mode 100644 index 00000000..9605176a Binary files /dev/null and b/docs/zh/demo/img/otg.png differ diff --git a/docs/zh/demo/img/rtt_adb_shell1.png b/docs/zh/demo/img/rtt_adb_shell1.png new file mode 100644 index 00000000..df4964a2 Binary files /dev/null and b/docs/zh/demo/img/rtt_adb_shell1.png differ diff --git a/docs/zh/demo/img/rtt_adb_shell2.png b/docs/zh/demo/img/rtt_adb_shell2.png new file mode 100644 index 00000000..88d99a6a Binary files /dev/null and b/docs/zh/demo/img/rtt_adb_shell2.png differ diff --git a/docs/zh/demo/img/usbh_serial.png b/docs/zh/demo/img/usbh_serial.png new file mode 100644 index 00000000..da929c4a Binary files /dev/null and b/docs/zh/demo/img/usbh_serial.png differ diff --git a/docs/source/demo/usb_otg.rst b/docs/zh/demo/usb_otg.rst similarity index 94% rename from docs/source/demo/usb_otg.rst rename to docs/zh/demo/usb_otg.rst index 78692cc0..5cb371c6 100644 --- a/docs/source/demo/usb_otg.rst +++ b/docs/zh/demo/usb_otg.rst @@ -1,5 +1,5 @@ -OTG 功能的使用 -========================= +USB OTG +================= 如果需要使用 OTG 功能，首先使用的芯片需要支持 ID 检测功能，然后使能 ``CONFIG_USB_OTG_ENABLE`` 宏，将之前的例程中 ``usbh_initialize`` 或者 ``usbh_initialize`` 替换成 ``usbotg_initialize`` 即可。 diff --git a/docs/source/demo/usbd_adb.rst b/docs/zh/demo/usbd_adb.rst similarity index 67% rename from docs/source/demo/usbd_adb.rst rename to docs/zh/demo/usbd_adb.rst index 92a3043e..6855135d 100644 --- a/docs/source/demo/usbd_adb.rst +++ b/docs/zh/demo/usbd_adb.rst @@ -1,7 +1,7 @@ -usbd_adb -=============== +ADB Device +================= -本节主要介绍如何使用 adb device。支持 **cherrysh** 和 rt-thread **msh**，只需要在 main 中添加以下初始化即可。 +adb device demo 参考 `demo/adb/usbd_adb_template.c` 模板。默认适配 **cherrysh** (`platform/demo/adb/cherrysh_port.c`) 和 **rt-thread msh** (`platform/rtthread/usbd_adb_shell.c`)，只需要在 main 中添加以下初始化即可。 .. code-block:: C diff --git a/docs/source/demo/usbd_audiov1.rst b/docs/zh/demo/usbd_audiov1.rst similarity index 61% rename from docs/source/demo/usbd_audiov1.rst rename to docs/zh/demo/usbd_audiov1.rst index 794ac8f6..875db6a0 100644 --- a/docs/source/demo/usbd_audiov1.rst +++ b/docs/zh/demo/usbd_audiov1.rst @@ -1,7 +1,10 @@ -usbd_audiov1 -=============== +AudioV1 Device +================= + +UAC1 demo 参考 `demo/audio_v1_*.c` 模板。 在使用 UAC1.0 时，需要注意以下几点： - 在使用windows 时，当修改描述符任意参数时，必须同步修改字符串描述符，并且卸载驱动，否则windows会认为设备未更改，继续使用旧的驱动，导致无法识别设备。Linux 不受此限制。 -- QQ 群文件中下载 RemoveGhostDev64.exe 可以自动删除所有 USB 注册的驱动信息，无需第一步 \ No newline at end of file +- QQ 群文件中下载 RemoveGhostDev64.exe 可以自动删除所有 USB 注册的驱动信息，无需第一步 +- 禁止在中断中添加打印和耗时操作，否则会影响 USB 按照 interval 传输 \ No newline at end of file diff --git a/docs/source/demo/usbd_audiov2.rst b/docs/zh/demo/usbd_audiov2.rst similarity index 85% rename from docs/source/demo/usbd_audiov2.rst rename to docs/zh/demo/usbd_audiov2.rst index 0390f17d..d329a29a 100644 --- a/docs/source/demo/usbd_audiov2.rst +++ b/docs/zh/demo/usbd_audiov2.rst @@ -1,5 +1,5 @@ -usbd_audiov2 -=============== +AudioV2 Device +================= 在使用 UAC2.0 时，需要注意以下几点： @@ -7,3 +7,4 @@ usbd_audiov2 - QQ 群文件中下载 RemoveGhostDev64.exe 可以自动删除所有 USB 注册的驱动信息，无需第一步 - windows 10 uac2.0 功能不完善，请使用 windows 11 测试uac2.0 功能。Linux 不受此限制 - windows 中设置的采样率表范围在多通道时（通道数大于2）计算有误，比如设置 8K~96K，那么实际是大于等于8K 小于96K，而非小于等于96K。Linux 不受此限制 +- 禁止在中断中添加打印和耗时操作，否则会影响 USB 按照 interval 传输 \ No newline at end of file diff --git a/docs/source/demo/usbd_cdc_acm.rst b/docs/zh/demo/usbd_cdc_acm.rst similarity index 95% rename from docs/source/demo/usbd_cdc_acm.rst rename to docs/zh/demo/usbd_cdc_acm.rst index be330b4c..46bdc195 100644 --- a/docs/source/demo/usbd_cdc_acm.rst +++ b/docs/zh/demo/usbd_cdc_acm.rst @@ -1,7 +1,7 @@ -usbd_cdc_acm -=============== +CDC ACM Device +================= -本 demo 主要用于演示 cdc acm 功能，包含收发测试，DTR 控制，ZLP 测试，性能测试。 +本 demo 主要用于演示 cdc acm 功能，参考 `demo/cdc_acm_template.c` 模板。包含收发测试，DTR 控制，ZLP 测试，性能测试。 - 开辟读写 buffer，用于收发数据，并且buffer需要用 nocache 修饰，这里我们读写都是用 2048字节，是为了后面的 ZLP 测试和性能测试使用。 diff --git a/docs/zh/demo/usbd_ecm.rst b/docs/zh/demo/usbd_ecm.rst new file mode 100644 index 00000000..faf736f8 --- /dev/null +++ b/docs/zh/demo/usbd_ecm.rst @@ -0,0 +1,4 @@ +CDC ECM Device +================= + +ECM demo 参考 `demo/cdc_ecm*.c` 模板。 默认对接 lwip 协议栈，上层使用 lwip api 即可。 \ No newline at end of file diff --git a/docs/source/demo/usbd_hid.rst b/docs/zh/demo/usbd_hid.rst similarity index 61% rename from docs/source/demo/usbd_hid.rst rename to docs/zh/demo/usbd_hid.rst index 68b6b285..acc1c5bb 100644 --- a/docs/source/demo/usbd_hid.rst +++ b/docs/zh/demo/usbd_hid.rst @@ -1,4 +1,4 @@ -usbd_hid -=============== +HID Device +================= -HID 功能比较简单，因此不作赘述，需要注意，使用 hid custom 例程时，需要搭配 `tools/test_srcipts/test_hid_inout.py` 使用。 \ No newline at end of file +HID 功能比较简单，因此不作赘述，需要注意，使用 hid custom 例程时，需要搭配 `tools/test_srcipts/test_hid_inout.py` 使用（携带 report id功能）。 \ No newline at end of file diff --git a/docs/source/demo/usbd_msc.rst b/docs/zh/demo/usbd_msc.rst similarity index 98% rename from docs/source/demo/usbd_msc.rst rename to docs/zh/demo/usbd_msc.rst index ff59aada..1b09a7d2 100644 --- a/docs/source/demo/usbd_msc.rst +++ b/docs/zh/demo/usbd_msc.rst @@ -1,5 +1,5 @@ -usbd_msc -=============== +MSC Device +================= 本节主要演示 USB 模拟 U 盘功能。默认使用RAM 作为存储介质模拟 U 盘。 diff --git a/docs/zh/demo/usbd_mtp.rst b/docs/zh/demo/usbd_mtp.rst new file mode 100644 index 00000000..13a5ceb8 --- /dev/null +++ b/docs/zh/demo/usbd_mtp.rst @@ -0,0 +1,6 @@ +MTP Device +================= + +MTP demo 参考 `demo/mtp_template.c` 模板。 默认适配 fatfs 文件系统(`platform/fatfs/usbd_fatfs_mtp.c`)。 + +.. note:: MTP 为商用收费，不开放 MTP 驱动源码，请联系官方购买授权。 \ No newline at end of file diff --git a/docs/zh/demo/usbd_rndis.rst b/docs/zh/demo/usbd_rndis.rst new file mode 100644 index 00000000..c90df8f8 --- /dev/null +++ b/docs/zh/demo/usbd_rndis.rst @@ -0,0 +1,4 @@ +CDC RNDIS Device +================= + +RNDIS demo 参考 `demo/cdc_rndis*.c` 模板。 默认对接 lwip 协议栈，上层使用 lwip api 即可。 \ No newline at end of file diff --git a/docs/source/demo/usbd_vendor.rst b/docs/zh/demo/usbd_vendor.rst similarity index 98% rename from docs/source/demo/usbd_vendor.rst rename to docs/zh/demo/usbd_vendor.rst index b38631b1..47c9ff41 100644 --- a/docs/source/demo/usbd_vendor.rst +++ b/docs/zh/demo/usbd_vendor.rst @@ -1,4 +1,4 @@ -vendor device 驱动编写 +Vendor Device 驱动编写 =========================== 本节主要介绍如何编写一个 vendor device 驱动。 diff --git a/docs/source/demo/usbd_video.rst b/docs/zh/demo/usbd_video.rst similarity index 99% rename from docs/source/demo/usbd_video.rst rename to docs/zh/demo/usbd_video.rst index e215abde..2709c2e8 100644 --- a/docs/source/demo/usbd_video.rst +++ b/docs/zh/demo/usbd_video.rst @@ -1,5 +1,5 @@ -usbd_video -=============== +USB Video Device +================= 本节主要演示 USB UAC 功能，支持 YUYV, MJPEG, H264 格式。为了方便演示，都采用的静态图。 diff --git a/docs/source/demo/usbd_webusb.rst b/docs/zh/demo/usbd_webusb.rst similarity index 95% rename from docs/source/demo/usbd_webusb.rst rename to docs/zh/demo/usbd_webusb.rst index 0df9bef6..fab7850b 100644 --- a/docs/source/demo/usbd_webusb.rst +++ b/docs/zh/demo/usbd_webusb.rst @@ -1,5 +1,5 @@ -usbd_webusb -=============== +WebUSB Device +================= 本 demo 主要演示 webusb 功能，webusb 主要用于弹出网页并对 USB 设备进行访问。示例使用 webusb_hid_template.c。 diff --git a/docs/source/demo/usbd_winusb.rst b/docs/zh/demo/usbd_winusb.rst similarity index 98% rename from docs/source/demo/usbd_winusb.rst rename to docs/zh/demo/usbd_winusb.rst index 0a6d4de9..aab0ad17 100644 --- a/docs/source/demo/usbd_winusb.rst +++ b/docs/zh/demo/usbd_winusb.rst @@ -1,5 +1,5 @@ -usbd_winusb -=============== +WinUSB Device +================= 本节主要介绍 winusb 驱动。winusb 是 windows 为了让用户友好的访问 USB 自定义类设备提供的一套通用驱动，其实本质就是 CDC ACM，只不过没有设置波特率的命令。 WINUSB 版本根据 USB 版本分为 V1/V2 版本，V2 版本需要包含 BOS 描述符，V1 版本不需要。 **V2 版本需要在设备描述符中设置为 USB2.1 的版本号**。 diff --git a/docs/zh/demo/usbh_audio.rst b/docs/zh/demo/usbh_audio.rst new file mode 100644 index 00000000..18933801 --- /dev/null +++ b/docs/zh/demo/usbh_audio.rst @@ -0,0 +1,4 @@ +Audio Host +================= + +.. note:: Host UAC 为商用收费，请联系官方购买授权。 \ No newline at end of file diff --git a/docs/zh/demo/usbh_bluetooth.rst b/docs/zh/demo/usbh_bluetooth.rst new file mode 100644 index 00000000..5b06f502 --- /dev/null +++ b/docs/zh/demo/usbh_bluetooth.rst @@ -0,0 +1,2 @@ +BTBLE Host +================= diff --git a/docs/source/demo/usbh_hid.rst b/docs/zh/demo/usbh_hid.rst similarity index 96% rename from docs/source/demo/usbh_hid.rst rename to docs/zh/demo/usbh_hid.rst index 6d519319..2719bf70 100644 --- a/docs/source/demo/usbh_hid.rst +++ b/docs/zh/demo/usbh_hid.rst @@ -1,7 +1,7 @@ -usbh_hid -=============== +HID Host +================= -本节主要介绍 HID 类的使用。 +本节主要介绍 Host HID 类的使用。 - HID 枚举完成回调中创建一次性线程 diff --git a/docs/source/demo/usbh_msc.rst b/docs/zh/demo/usbh_msc.rst similarity index 93% rename from docs/source/demo/usbh_msc.rst rename to docs/zh/demo/usbh_msc.rst index 83956cc2..524dc5c1 100644 --- a/docs/source/demo/usbh_msc.rst +++ b/docs/zh/demo/usbh_msc.rst @@ -1,7 +1,7 @@ -usbh_msc -=============== +MSC Host +================= -本节主要介绍主机 MSC 使用。借助 FATFS 实现读写功能。 +本节主要介绍 Host MSC 的使用。借助 FATFS 实现读写功能。 - 在 msc 枚举完成的回调中注册一个线程，用于读写操作。 diff --git a/docs/source/demo/usbh_net.rst b/docs/zh/demo/usbh_net.rst similarity index 98% rename from docs/source/demo/usbh_net.rst rename to docs/zh/demo/usbh_net.rst index 8757991e..1516f397 100644 --- a/docs/source/demo/usbh_net.rst +++ b/docs/zh/demo/usbh_net.rst @@ -1,7 +1,7 @@ -usbh_net -=============== +Network Host +================= -本节主要介绍 USB 网卡的使用，当前已经支持和测试以下 USB 网卡: +本节主要介绍 Host USB 网卡的使用，当前已经支持和测试以下 USB 网卡: - 4G 网卡：EC20(ECM/RNDIS)、手机（RNDIS）、SIMCOM7600(RNDIS)、ML307R(RNDIS)、AIR780(RNDIS) diff --git a/docs/source/demo/usbh_serial.rst b/docs/zh/demo/usbh_serial.rst similarity index 98% rename from docs/source/demo/usbh_serial.rst rename to docs/zh/demo/usbh_serial.rst index 619545c6..e37a6959 100644 --- a/docs/source/demo/usbh_serial.rst +++ b/docs/zh/demo/usbh_serial.rst @@ -1,7 +1,7 @@ -usbh_serial -=============== +Serial Host +================= -Serial 框架当前支持 cdc acm, ftdi, cp210x, ch34x, pl2303，gsm 驱动。 +本节主要介绍 Host serial 框架的使用。Serial 框架当前支持 cdc acm, ftdi, cp210x, ch34x, pl2303，gsm 驱动。 .. figure:: img/usbh_serial.png diff --git a/docs/source/demo/usbh_vendor.rst b/docs/zh/demo/usbh_vendor.rst similarity index 99% rename from docs/source/demo/usbh_vendor.rst rename to docs/zh/demo/usbh_vendor.rst index b86bda60..a0b0bb7b 100644 --- a/docs/source/demo/usbh_vendor.rst +++ b/docs/zh/demo/usbh_vendor.rst @@ -1,4 +1,4 @@ -vendor host 驱动编写 +Vendor Host 驱动编写 =========================== 本节主要介绍如何编写一个 vendor host 驱动。 diff --git a/docs/zh/demo/usbh_video.rst b/docs/zh/demo/usbh_video.rst new file mode 100644 index 00000000..7de4b457 --- /dev/null +++ b/docs/zh/demo/usbh_video.rst @@ -0,0 +1,4 @@ +Video Host +================= + +.. note:: Host UVC 为商用收费，请联系官方购买授权。 \ No newline at end of file diff --git a/docs/zh/demo/usbh_wifi.rst b/docs/zh/demo/usbh_wifi.rst new file mode 100644 index 00000000..588e8131 --- /dev/null +++ b/docs/zh/demo/usbh_wifi.rst @@ -0,0 +1,2 @@ +WIFI Host +================= diff --git a/docs/source/index.rst b/docs/zh/index.rst similarity index 97% rename from docs/source/index.rst rename to docs/zh/index.rst index 831de0a1..343fe322 100644 --- a/docs/source/index.rst +++ b/docs/zh/index.rst @@ -94,28 +94,31 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 .. toctree:: :maxdepth: 1 - :caption: 例程说明 + :caption: 例程 demo/usbd_cdc_acm demo/usbd_hid demo/usbd_msc - demo/usbd_rndis - demo/usbd_ecm 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 - demo/usb_otg .. toctree:: :maxdepth: 1 @@ -154,4 +157,4 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 :maxdepth: 1 :caption: 商业支持 - support/index \ No newline at end of file + support/index diff --git a/docs/source/quick_start/demo.rst b/docs/zh/quick_start/demo.rst similarity index 69% rename from docs/source/quick_start/demo.rst rename to docs/zh/quick_start/demo.rst index e51a2e3e..2cadfb13 100644 --- a/docs/source/quick_start/demo.rst +++ b/docs/zh/quick_start/demo.rst @@ -7,27 +7,46 @@ 基于 bouffalolab 系列芯片（官方 SDK 支持） ------------------------------------------ -仓库参考：https://github.com/CherryUSB/cherryusb_bouffalolab +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 -- BL616/BL808：USB2.0 内置 HS phy 芯片，支持主从机。device 支持 5 个端点（包括端点0），不支持双向同时使用。 -- USB 的相关应用位于 `examples/usbdev` 和 `examples/usbhost` 目录下，根据官方环境搭建完成后，即可编译使用。 + * - Repo url + - USB IP + - Version + * - https://github.com/CherryUSB/cherryusb_bouffalolab + - FOTG210 + - less than latest 基于 HPMicro 系列芯片（官方 SDK 支持） ----------------------------------------------------- -仓库参考：https://github.com/CherryUSB/cherryusb_hpmicro +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 -- HPM 系列: USB2.0 内置 HS phy 芯片，支持主从机。device 支持 8/16 端点（包括端点0），并且可以同时使用双向，不同芯片个数有差异。 -- USB 的相关应用位于 `samples/cherryusb` ，根据官方环境搭建完成后，即可编译使用。 + * - Repo url + - USB IP + - Version + * - https://github.com/CherryUSB/cherryusb_hpmicro + - CHIPIDEA + - less than latest -基于 esp32s2/s3/p4 系列芯片（官方 SDK 即将支持） +基于 esp32s2/s3/p4 系列芯片（官方 SDK 支持） ------------------------------------------------- -仓库参考：https://github.com/CherryUSB/cherryusb_esp32 +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 -- esp32s2/s3：USB2.0 内置全速 PHY 芯片，支持主从机，device 支持 7 个端点（包括端点0），并且可以同时使用双向。 -- esp32p4：一个 USB2.0 内置全速 PHY 芯片，一个 USB2.0 内置高速 PHY 芯片，支持主从机。 -- 默认 demo 采用组件库安装的形式，在 https://components.espressif.com/ 中搜索 cherryusb 即可 + * - Repo url + - USB IP + - Version + * - https://github.com/CherryUSB/cherryusb_esp32 + - DWC2 + - less than latest + +默认 demo 采用组件库安装的形式，在 https://components.espressif.com/ 中搜索 cherryusb 即可。也可使用官方 idf 仓库下的 cherryusb demo。 ESP-Registry 可以参考官方文档，推荐使用 vscode + esp-idf 的开发环境。 @@ -44,51 +63,122 @@ ESP-Registry 可以参考官方文档，推荐使用 vscode + esp-idf 的开发 .. figure:: img/esp3.png .. figure:: img/esp4.png -基于飞腾派系列芯片（官方 SDK 支持） ------------------------------------ +基于 Phytium 系列芯片（官方 SDK 支持） +--------------------------------------- -仓库参考：https://gitee.com/phytium_embedded/phytium-free-rtos-sdk +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 -- 飞腾派支持两个 USB3.0 主机（采用 XHCI）， 两个 USB2.0 主从机 -- USB 的相关应用位于 `example/peripheral/usb` ，根据官方环境搭建完成后，即可编译使用。 + * - Repo url + - USB IP + - Version + * - https://gitee.com/phytium_embedded/phytium-free-rtos-sdk + - PUSB2/XHCI + - equal to v1.4.0 基于 Essemi 系列芯片（官方 SDK 支持） ----------------------------------------- -仓库参考：https://github.com/CherryUSB/cherryusb_es32 +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 -- 支持全速和高速主从机。device 支持 6 个端点（包括端点0），并且可以同时使用双向。 + * - Repo url + - USB IP + - Version + * - https://github.com/CherryUSB/cherryusb_es32 + - MUSB + - less than latest 基于 Artinchip 系列芯片（官方 SDK 支持） ----------------------------------------------- -仓库参考：https://gitee.com/artinchip/luban-lite +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 -- 支持全速和高速主从机，主机采用 EHCI + OHCI。device 支持 8 个端点（包括端点0），并且可以同时使用双向。 + * - Repo url + - USB IP + - Version + * - https://gitee.com/artinchip/luban-lite + - AIC/EHCI/OHCI + - less than latest -基于 canmv-k230 芯片（官方 SDK 支持） ---------------------------------------------- +基于 Kendryte canmv-k230 系列（官方 SDK 支持） +----------------------------------------------- -仓库参考：https://github.com/CherryUSB/k230_sdk +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 -- K230: 两个 USB2.0 内置 HS PHY 芯片，支持主从机。device 支持 16 个端点（包括端点0），并且可以同时使用双向。 + * - Repo url + - USB IP + - Version + * - https://github.com/CherryUSB/k230_sdk + - DWC2 + - less than latest -基于 NXP MCX系列芯片 +基于 NXP MCX 系列芯片 --------------------------- -仓库参考：https://github.com/CherryUSB/cherryusb_mcx 或者 https://github.com/RT-Thread/rt-thread/tree/master/bsp/nxp/mcx +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 -- 支持全速 IP 和高速 IP， 高速 IP 支持主机和从机。device 支持 8 个端点（包括端点0），并且可以同时使用双向。 + * - 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 + +基于 SiFli SF32 系列芯片（官方 SDK 支持） +-------------------------------------------- + +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 + + * - Repo url + - USB IP + - Version + * - https://github.com/OpenSiFli/SiFli-SDK + - MUSB + - less than latest 基于 RP2040/RP2035 芯片（官方 SDK 即将支持） -------------------------------------------- -仓库参考： https://github.com/CherryUSB/pico-examples 和 https://github.com/CherryUSB/pico-sdk +.. 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 + +基于 Actionstech 系列芯片（官方 SDK 支持） +------------------------------------------------------ + +Not opensource， 请联系 Actionstech 官方 基于 ST 系列芯片 --------------------------- -仓库参考：https://github.com/CherryUSB/cherryusb_stm32 +.. 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 默认提供以下 demo 工程： diff --git a/docs/zh/quick_start/img/env0.png b/docs/zh/quick_start/img/env0.png new file mode 100644 index 00000000..c0a8b03f Binary files /dev/null and b/docs/zh/quick_start/img/env0.png differ diff --git a/docs/zh/quick_start/img/env1.png b/docs/zh/quick_start/img/env1.png new file mode 100644 index 00000000..2a68e052 Binary files /dev/null and b/docs/zh/quick_start/img/env1.png differ diff --git a/docs/zh/quick_start/img/env2.png b/docs/zh/quick_start/img/env2.png new file mode 100644 index 00000000..ee37101a Binary files /dev/null and b/docs/zh/quick_start/img/env2.png differ diff --git a/docs/zh/quick_start/img/esp1.png b/docs/zh/quick_start/img/esp1.png new file mode 100644 index 00000000..1f059e71 Binary files /dev/null and b/docs/zh/quick_start/img/esp1.png differ diff --git a/docs/zh/quick_start/img/esp2.png b/docs/zh/quick_start/img/esp2.png new file mode 100644 index 00000000..fd20e9ce Binary files /dev/null and b/docs/zh/quick_start/img/esp2.png differ diff --git a/docs/zh/quick_start/img/esp3.png b/docs/zh/quick_start/img/esp3.png new file mode 100644 index 00000000..82a7162f Binary files /dev/null and b/docs/zh/quick_start/img/esp3.png differ diff --git a/docs/zh/quick_start/img/esp4.png b/docs/zh/quick_start/img/esp4.png new file mode 100644 index 00000000..ffb2882a Binary files /dev/null and b/docs/zh/quick_start/img/esp4.png differ diff --git a/docs/zh/quick_start/img/question1.png b/docs/zh/quick_start/img/question1.png new file mode 100644 index 00000000..a852e6aa Binary files /dev/null and b/docs/zh/quick_start/img/question1.png differ diff --git a/docs/zh/quick_start/img/question2.png b/docs/zh/quick_start/img/question2.png new file mode 100644 index 00000000..e00b3bfa Binary files /dev/null and b/docs/zh/quick_start/img/question2.png differ diff --git a/docs/zh/quick_start/img/stm32_1.png b/docs/zh/quick_start/img/stm32_1.png new file mode 100644 index 00000000..b91044a5 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_1.png differ diff --git a/docs/zh/quick_start/img/stm32_10.png b/docs/zh/quick_start/img/stm32_10.png new file mode 100644 index 00000000..d55b38e7 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_10.png differ diff --git a/docs/zh/quick_start/img/stm32_11.png b/docs/zh/quick_start/img/stm32_11.png new file mode 100644 index 00000000..3ad5b074 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_11.png differ diff --git a/docs/zh/quick_start/img/stm32_12.png b/docs/zh/quick_start/img/stm32_12.png new file mode 100644 index 00000000..84aaffe8 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_12.png differ diff --git a/docs/zh/quick_start/img/stm32_13.png b/docs/zh/quick_start/img/stm32_13.png new file mode 100644 index 00000000..f12fad75 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_13.png differ diff --git a/docs/zh/quick_start/img/stm32_14.png b/docs/zh/quick_start/img/stm32_14.png new file mode 100644 index 00000000..e5aa5b19 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_14.png differ diff --git a/docs/zh/quick_start/img/stm32_15.png b/docs/zh/quick_start/img/stm32_15.png new file mode 100644 index 00000000..7c293287 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_15.png differ diff --git a/docs/zh/quick_start/img/stm32_16.png b/docs/zh/quick_start/img/stm32_16.png new file mode 100644 index 00000000..70f2e63c Binary files /dev/null and b/docs/zh/quick_start/img/stm32_16.png differ diff --git a/docs/zh/quick_start/img/stm32_18.png b/docs/zh/quick_start/img/stm32_18.png new file mode 100644 index 00000000..456df189 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_18.png differ diff --git a/docs/zh/quick_start/img/stm32_19.png b/docs/zh/quick_start/img/stm32_19.png new file mode 100644 index 00000000..a796dc75 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_19.png differ diff --git a/docs/zh/quick_start/img/stm32_2.png b/docs/zh/quick_start/img/stm32_2.png new file mode 100644 index 00000000..671b1b82 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_2.png differ diff --git a/docs/zh/quick_start/img/stm32_3_1.png b/docs/zh/quick_start/img/stm32_3_1.png new file mode 100644 index 00000000..9e42196d Binary files /dev/null and b/docs/zh/quick_start/img/stm32_3_1.png differ diff --git a/docs/zh/quick_start/img/stm32_3_2.png b/docs/zh/quick_start/img/stm32_3_2.png new file mode 100644 index 00000000..492d6739 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_3_2.png differ diff --git a/docs/zh/quick_start/img/stm32_4_1.png b/docs/zh/quick_start/img/stm32_4_1.png new file mode 100644 index 00000000..e81437bc Binary files /dev/null and b/docs/zh/quick_start/img/stm32_4_1.png differ diff --git a/docs/zh/quick_start/img/stm32_4_2.png b/docs/zh/quick_start/img/stm32_4_2.png new file mode 100644 index 00000000..dd90f5b8 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_4_2.png differ diff --git a/docs/zh/quick_start/img/stm32_5.png b/docs/zh/quick_start/img/stm32_5.png new file mode 100644 index 00000000..5bec9878 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_5.png differ diff --git a/docs/zh/quick_start/img/stm32_6.png b/docs/zh/quick_start/img/stm32_6.png new file mode 100644 index 00000000..f0ad9a0b Binary files /dev/null and b/docs/zh/quick_start/img/stm32_6.png differ diff --git a/docs/zh/quick_start/img/stm32_7.png b/docs/zh/quick_start/img/stm32_7.png new file mode 100644 index 00000000..8aef0bfa Binary files /dev/null and b/docs/zh/quick_start/img/stm32_7.png differ diff --git a/docs/zh/quick_start/img/stm32_8.png b/docs/zh/quick_start/img/stm32_8.png new file mode 100644 index 00000000..08d2e724 Binary files /dev/null and b/docs/zh/quick_start/img/stm32_8.png differ diff --git a/docs/source/quick_start/migration.rst b/docs/zh/quick_start/migration.rst similarity index 100% rename from docs/source/quick_start/migration.rst rename to docs/zh/quick_start/migration.rst diff --git a/docs/source/quick_start/opensource.rst b/docs/zh/quick_start/opensource.rst similarity index 100% rename from docs/source/quick_start/opensource.rst rename to docs/zh/quick_start/opensource.rst diff --git a/docs/source/quick_start/q&a.rst b/docs/zh/quick_start/q&a.rst similarity index 100% rename from docs/source/quick_start/q&a.rst rename to docs/zh/quick_start/q&a.rst diff --git a/docs/source/quick_start/rtthread.rst b/docs/zh/quick_start/rtthread.rst similarity index 100% rename from docs/source/quick_start/rtthread.rst rename to docs/zh/quick_start/rtthread.rst diff --git a/docs/source/quick_start/share.rst b/docs/zh/quick_start/share.rst similarity index 100% rename from docs/source/quick_start/share.rst rename to docs/zh/quick_start/share.rst diff --git a/docs/source/quick_start/start.rst b/docs/zh/quick_start/start.rst similarity index 100% rename from docs/source/quick_start/start.rst rename to docs/zh/quick_start/start.rst diff --git a/docs/source/quick_start/transplant.rst b/docs/zh/quick_start/transplant.rst similarity index 100% rename from docs/source/quick_start/transplant.rst rename to docs/zh/quick_start/transplant.rst diff --git a/docs/zh/show/img/usbdev_msc.png b/docs/zh/show/img/usbdev_msc.png new file mode 100644 index 00000000..30f22383 Binary files /dev/null and b/docs/zh/show/img/usbdev_msc.png differ diff --git a/docs/zh/show/img/usbdev_rndis_linux.png b/docs/zh/show/img/usbdev_rndis_linux.png new file mode 100644 index 00000000..94b97312 Binary files /dev/null and b/docs/zh/show/img/usbdev_rndis_linux.png differ diff --git a/docs/zh/show/img/usbdev_rndis_lwip.png b/docs/zh/show/img/usbdev_rndis_lwip.png new file mode 100644 index 00000000..f4cfd0b3 Binary files /dev/null and b/docs/zh/show/img/usbdev_rndis_lwip.png differ diff --git a/docs/zh/show/img/usbdev_rndis_lwip2.png b/docs/zh/show/img/usbdev_rndis_lwip2.png new file mode 100644 index 00000000..3fde91f9 Binary files /dev/null and b/docs/zh/show/img/usbdev_rndis_lwip2.png differ diff --git a/docs/zh/show/img/usbdev_rndis_wifi.png b/docs/zh/show/img/usbdev_rndis_wifi.png new file mode 100644 index 00000000..d6817876 Binary files /dev/null and b/docs/zh/show/img/usbdev_rndis_wifi.png differ diff --git a/docs/zh/show/img/usbdev_rndis_wifi2.png b/docs/zh/show/img/usbdev_rndis_wifi2.png new file mode 100644 index 00000000..dba9f3dd Binary files /dev/null and b/docs/zh/show/img/usbdev_rndis_wifi2.png differ diff --git a/docs/zh/show/img/usbdev_rndis_win.png b/docs/zh/show/img/usbdev_rndis_win.png new file mode 100644 index 00000000..5293023a Binary files /dev/null and b/docs/zh/show/img/usbdev_rndis_win.png differ diff --git a/docs/zh/show/img/usbdev_uvc_mjpeg.png b/docs/zh/show/img/usbdev_uvc_mjpeg.png new file mode 100644 index 00000000..a2321c15 Binary files /dev/null and b/docs/zh/show/img/usbdev_uvc_mjpeg.png differ diff --git a/docs/zh/show/img/usbdev_uvc_yuv.png b/docs/zh/show/img/usbdev_uvc_yuv.png new file mode 100644 index 00000000..a630cd67 Binary files /dev/null and b/docs/zh/show/img/usbdev_uvc_yuv.png differ diff --git a/docs/zh/show/img/usbhost_ax88772_1.png b/docs/zh/show/img/usbhost_ax88772_1.png new file mode 100644 index 00000000..a267b292 Binary files /dev/null and b/docs/zh/show/img/usbhost_ax88772_1.png differ diff --git a/docs/zh/show/img/usbhost_ax88772_2.png b/docs/zh/show/img/usbhost_ax88772_2.png new file mode 100644 index 00000000..fc6e96fc Binary files /dev/null and b/docs/zh/show/img/usbhost_ax88772_2.png differ diff --git a/docs/zh/show/img/usbhost_hub.png b/docs/zh/show/img/usbhost_hub.png new file mode 100644 index 00000000..011468c7 Binary files /dev/null and b/docs/zh/show/img/usbhost_hub.png differ diff --git a/docs/zh/show/img/usbhost_hub2.png b/docs/zh/show/img/usbhost_hub2.png new file mode 100644 index 00000000..00c09d6f Binary files /dev/null and b/docs/zh/show/img/usbhost_hub2.png differ diff --git a/docs/zh/show/img/usbhost_msc.png b/docs/zh/show/img/usbhost_msc.png new file mode 100644 index 00000000..ec546a8d Binary files /dev/null and b/docs/zh/show/img/usbhost_msc.png differ diff --git a/docs/zh/show/img/usbhost_msc_xhci.png b/docs/zh/show/img/usbhost_msc_xhci.png new file mode 100644 index 00000000..084250f2 Binary files /dev/null and b/docs/zh/show/img/usbhost_msc_xhci.png differ diff --git a/docs/zh/show/img/usbhost_rndis.png b/docs/zh/show/img/usbhost_rndis.png new file mode 100644 index 00000000..12ab1a4e Binary files /dev/null and b/docs/zh/show/img/usbhost_rndis.png differ diff --git a/docs/zh/show/img/usbhost_uvc.gif b/docs/zh/show/img/usbhost_uvc.gif new file mode 100644 index 00000000..c4df04e0 Binary files /dev/null and b/docs/zh/show/img/usbhost_uvc.gif differ diff --git a/docs/zh/show/img/usbhost_wifi.png b/docs/zh/show/img/usbhost_wifi.png new file mode 100644 index 00000000..e57fd85b Binary files /dev/null and b/docs/zh/show/img/usbhost_wifi.png differ diff --git a/docs/source/show/index.rst b/docs/zh/show/index.rst similarity index 100% rename from docs/source/show/index.rst rename to docs/zh/show/index.rst diff --git a/docs/zh/support/img/dwc2_hostuac.png b/docs/zh/support/img/dwc2_hostuac.png new file mode 100644 index 00000000..6050f531 Binary files /dev/null and b/docs/zh/support/img/dwc2_hostuac.png differ diff --git a/docs/zh/support/img/dwc2_hostuvc1.png b/docs/zh/support/img/dwc2_hostuvc1.png new file mode 100644 index 00000000..70b4dd1a Binary files /dev/null and b/docs/zh/support/img/dwc2_hostuvc1.png differ diff --git a/docs/zh/support/img/dwc2_hostuvc2.png b/docs/zh/support/img/dwc2_hostuvc2.png new file mode 100644 index 00000000..8885e90e Binary files /dev/null and b/docs/zh/support/img/dwc2_hostuvc2.png differ diff --git a/docs/zh/support/img/dwc2_hostuvc3.png b/docs/zh/support/img/dwc2_hostuvc3.png new file mode 100644 index 00000000..fb3e1eef Binary files /dev/null and b/docs/zh/support/img/dwc2_hostuvc3.png differ diff --git a/docs/zh/support/img/ehci_hostuvc1.png b/docs/zh/support/img/ehci_hostuvc1.png new file mode 100644 index 00000000..2bd6590a Binary files /dev/null and b/docs/zh/support/img/ehci_hostuvc1.png differ diff --git a/docs/zh/support/img/ehci_hostuvc2.png b/docs/zh/support/img/ehci_hostuvc2.png new file mode 100644 index 00000000..f44fa68c Binary files /dev/null and b/docs/zh/support/img/ehci_hostuvc2.png differ diff --git a/docs/zh/support/img/mtpdev.png b/docs/zh/support/img/mtpdev.png new file mode 100644 index 00000000..513b8ac9 Binary files /dev/null and b/docs/zh/support/img/mtpdev.png differ diff --git a/docs/zh/support/img/ohci.png b/docs/zh/support/img/ohci.png new file mode 100644 index 00000000..171f77be Binary files /dev/null and b/docs/zh/support/img/ohci.png differ diff --git a/docs/zh/support/img/rndisrx.png b/docs/zh/support/img/rndisrx.png new file mode 100644 index 00000000..ce1133ed Binary files /dev/null and b/docs/zh/support/img/rndisrx.png differ diff --git a/docs/zh/support/img/rndistx.png b/docs/zh/support/img/rndistx.png new file mode 100644 index 00000000..69e45db8 Binary files /dev/null and b/docs/zh/support/img/rndistx.png differ diff --git a/docs/zh/support/img/tmcdev1.png b/docs/zh/support/img/tmcdev1.png new file mode 100644 index 00000000..1eaf7155 Binary files /dev/null and b/docs/zh/support/img/tmcdev1.png differ diff --git a/docs/zh/support/img/tmcdev2.png b/docs/zh/support/img/tmcdev2.png new file mode 100644 index 00000000..97c8297b Binary files /dev/null and b/docs/zh/support/img/tmcdev2.png differ diff --git a/docs/zh/support/img/usbhost_uvc.gif b/docs/zh/support/img/usbhost_uvc.gif new file mode 100644 index 00000000..c4df04e0 Binary files /dev/null and b/docs/zh/support/img/usbhost_uvc.gif differ diff --git a/docs/source/support/index.rst b/docs/zh/support/index.rst similarity index 100% rename from docs/source/support/index.rst rename to docs/zh/support/index.rst diff --git a/docs/zh/tools/img/chrytool1.png b/docs/zh/tools/img/chrytool1.png new file mode 100644 index 00000000..8717316a Binary files /dev/null and b/docs/zh/tools/img/chrytool1.png differ diff --git a/docs/zh/tools/img/chrytool2.png b/docs/zh/tools/img/chrytool2.png new file mode 100644 index 00000000..a0eb4192 Binary files /dev/null and b/docs/zh/tools/img/chrytool2.png differ diff --git a/docs/zh/tools/img/chrytool3.png b/docs/zh/tools/img/chrytool3.png new file mode 100644 index 00000000..52a3556b Binary files /dev/null and b/docs/zh/tools/img/chrytool3.png differ diff --git a/docs/zh/tools/img/chrytool4.png b/docs/zh/tools/img/chrytool4.png new file mode 100644 index 00000000..8ad68400 Binary files /dev/null and b/docs/zh/tools/img/chrytool4.png differ diff --git a/docs/zh/tools/img/chrytool5.png b/docs/zh/tools/img/chrytool5.png new file mode 100644 index 00000000..17849324 Binary files /dev/null and b/docs/zh/tools/img/chrytool5.png differ diff --git a/docs/zh/tools/img/chrytool6.png b/docs/zh/tools/img/chrytool6.png new file mode 100644 index 00000000..931ccad8 Binary files /dev/null and b/docs/zh/tools/img/chrytool6.png differ diff --git a/docs/zh/tools/img/chrytool7.png b/docs/zh/tools/img/chrytool7.png new file mode 100644 index 00000000..283a7fc9 Binary files /dev/null and b/docs/zh/tools/img/chrytool7.png differ diff --git a/docs/source/tools/index.rst b/docs/zh/tools/index.rst similarity index 100% rename from docs/source/tools/index.rst rename to docs/zh/tools/index.rst diff --git a/docs/zh/usb/img/1.png b/docs/zh/usb/img/1.png new file mode 100644 index 00000000..e85ddf7a Binary files /dev/null and b/docs/zh/usb/img/1.png differ diff --git a/docs/zh/usb/img/10.png b/docs/zh/usb/img/10.png new file mode 100644 index 00000000..bb57645e Binary files /dev/null and b/docs/zh/usb/img/10.png differ diff --git a/docs/zh/usb/img/11.png b/docs/zh/usb/img/11.png new file mode 100644 index 00000000..11056e33 Binary files /dev/null and b/docs/zh/usb/img/11.png differ diff --git a/docs/zh/usb/img/12.png b/docs/zh/usb/img/12.png new file mode 100644 index 00000000..4149d81e Binary files /dev/null and b/docs/zh/usb/img/12.png differ diff --git a/docs/zh/usb/img/13.png b/docs/zh/usb/img/13.png new file mode 100644 index 00000000..29a544b2 Binary files /dev/null and b/docs/zh/usb/img/13.png differ diff --git a/docs/zh/usb/img/14.png b/docs/zh/usb/img/14.png new file mode 100644 index 00000000..8ca094a4 Binary files /dev/null and b/docs/zh/usb/img/14.png differ diff --git a/docs/zh/usb/img/15.png b/docs/zh/usb/img/15.png new file mode 100644 index 00000000..eba7b89b Binary files /dev/null and b/docs/zh/usb/img/15.png differ diff --git a/docs/zh/usb/img/16.png b/docs/zh/usb/img/16.png new file mode 100644 index 00000000..259336ca Binary files /dev/null and b/docs/zh/usb/img/16.png differ diff --git a/docs/zh/usb/img/17.png b/docs/zh/usb/img/17.png new file mode 100644 index 00000000..c42de390 Binary files /dev/null and b/docs/zh/usb/img/17.png differ diff --git a/docs/zh/usb/img/18.png b/docs/zh/usb/img/18.png new file mode 100644 index 00000000..f08b6354 Binary files /dev/null and b/docs/zh/usb/img/18.png differ diff --git a/docs/zh/usb/img/19.png b/docs/zh/usb/img/19.png new file mode 100644 index 00000000..2e6eb9ce Binary files /dev/null and b/docs/zh/usb/img/19.png differ diff --git a/docs/zh/usb/img/2.png b/docs/zh/usb/img/2.png new file mode 100644 index 00000000..5b4f5f20 Binary files /dev/null and b/docs/zh/usb/img/2.png differ diff --git a/docs/zh/usb/img/20.png b/docs/zh/usb/img/20.png new file mode 100644 index 00000000..a44898a8 Binary files /dev/null and b/docs/zh/usb/img/20.png differ diff --git a/docs/zh/usb/img/21.png b/docs/zh/usb/img/21.png new file mode 100644 index 00000000..7aa81e95 Binary files /dev/null and b/docs/zh/usb/img/21.png differ diff --git a/docs/zh/usb/img/22.png b/docs/zh/usb/img/22.png new file mode 100644 index 00000000..370d39f9 Binary files /dev/null and b/docs/zh/usb/img/22.png differ diff --git a/docs/zh/usb/img/23.png b/docs/zh/usb/img/23.png new file mode 100644 index 00000000..e08db16e Binary files /dev/null and b/docs/zh/usb/img/23.png differ diff --git a/docs/zh/usb/img/24.png b/docs/zh/usb/img/24.png new file mode 100644 index 00000000..fec98d49 Binary files /dev/null and b/docs/zh/usb/img/24.png differ diff --git a/docs/zh/usb/img/25.png b/docs/zh/usb/img/25.png new file mode 100644 index 00000000..9bcaf151 Binary files /dev/null and b/docs/zh/usb/img/25.png differ diff --git a/docs/zh/usb/img/26.png b/docs/zh/usb/img/26.png new file mode 100644 index 00000000..d439b7c4 Binary files /dev/null and b/docs/zh/usb/img/26.png differ diff --git a/docs/zh/usb/img/27.png b/docs/zh/usb/img/27.png new file mode 100644 index 00000000..1047da1b Binary files /dev/null and b/docs/zh/usb/img/27.png differ diff --git a/docs/zh/usb/img/28.png b/docs/zh/usb/img/28.png new file mode 100644 index 00000000..95b760c5 Binary files /dev/null and b/docs/zh/usb/img/28.png differ diff --git a/docs/zh/usb/img/29.png b/docs/zh/usb/img/29.png new file mode 100644 index 00000000..09538d16 Binary files /dev/null and b/docs/zh/usb/img/29.png differ diff --git a/docs/zh/usb/img/3.png b/docs/zh/usb/img/3.png new file mode 100644 index 00000000..b8ef0823 Binary files /dev/null and b/docs/zh/usb/img/3.png differ diff --git a/docs/zh/usb/img/30.png b/docs/zh/usb/img/30.png new file mode 100644 index 00000000..d3014f95 Binary files /dev/null and b/docs/zh/usb/img/30.png differ diff --git a/docs/zh/usb/img/4.png b/docs/zh/usb/img/4.png new file mode 100644 index 00000000..f80c5366 Binary files /dev/null and b/docs/zh/usb/img/4.png differ diff --git a/docs/zh/usb/img/5.png b/docs/zh/usb/img/5.png new file mode 100644 index 00000000..ec6a4ba2 Binary files /dev/null and b/docs/zh/usb/img/5.png differ diff --git a/docs/zh/usb/img/6.png b/docs/zh/usb/img/6.png new file mode 100644 index 00000000..2d280398 Binary files /dev/null and b/docs/zh/usb/img/6.png differ diff --git a/docs/zh/usb/img/7.png b/docs/zh/usb/img/7.png new file mode 100644 index 00000000..e7562f11 Binary files /dev/null and b/docs/zh/usb/img/7.png differ diff --git a/docs/zh/usb/img/8.png b/docs/zh/usb/img/8.png new file mode 100644 index 00000000..a4ac6ad4 Binary files /dev/null and b/docs/zh/usb/img/8.png differ diff --git a/docs/zh/usb/img/9.png b/docs/zh/usb/img/9.png new file mode 100644 index 00000000..a8b5b2a3 Binary files /dev/null and b/docs/zh/usb/img/9.png differ diff --git a/docs/zh/usb/img/overview1.png b/docs/zh/usb/img/overview1.png new file mode 100644 index 00000000..fbaf5a19 Binary files /dev/null and b/docs/zh/usb/img/overview1.png differ diff --git a/docs/zh/usb/img/overview2.png b/docs/zh/usb/img/overview2.png new file mode 100644 index 00000000..c8b3b779 Binary files /dev/null and b/docs/zh/usb/img/overview2.png differ diff --git a/docs/zh/usb/img/usb_enum.png b/docs/zh/usb/img/usb_enum.png new file mode 100644 index 00000000..01c67c15 Binary files /dev/null and b/docs/zh/usb/img/usb_enum.png differ diff --git a/docs/zh/usb/img/usb_request.png b/docs/zh/usb/img/usb_request.png new file mode 100644 index 00000000..bb9f2637 Binary files /dev/null and b/docs/zh/usb/img/usb_request.png differ diff --git a/docs/zh/usb/img/usbstruct.png b/docs/zh/usb/img/usbstruct.png new file mode 100644 index 00000000..bd062ca3 Binary files /dev/null and b/docs/zh/usb/img/usbstruct.png differ diff --git a/docs/source/usb/usb2.0_basic.rst b/docs/zh/usb/usb2.0_basic.rst similarity index 100% rename from docs/source/usb/usb2.0_basic.rst rename to docs/zh/usb/usb2.0_basic.rst diff --git a/docs/source/usb/usb3.0_basic.rst b/docs/zh/usb/usb3.0_basic.rst similarity index 100% rename from docs/source/usb/usb3.0_basic.rst rename to docs/zh/usb/usb3.0_basic.rst diff --git a/docs/source/usb/usb_desc.rst b/docs/zh/usb/usb_desc.rst similarity index 100% rename from docs/source/usb/usb_desc.rst rename to docs/zh/usb/usb_desc.rst diff --git a/docs/source/usb/usb_enum.rst b/docs/zh/usb/usb_enum.rst similarity index 100% rename from docs/source/usb/usb_enum.rst rename to docs/zh/usb/usb_enum.rst diff --git a/docs/source/usb/usb_ext.rst b/docs/zh/usb/usb_ext.rst similarity index 100% rename from docs/source/usb/usb_ext.rst rename to docs/zh/usb/usb_ext.rst diff --git a/docs/source/usb/usb_request.rst b/docs/zh/usb/usb_request.rst similarity index 100% rename from docs/source/usb/usb_request.rst rename to docs/zh/usb/usb_request.rst diff --git a/docs/zh/usbdev.svg b/docs/zh/usbdev.svg new file mode 100644 index 00000000..8f787289 --- /dev/null +++ b/docs/zh/usbdev.svg @@ -0,0 +1,4 @@ + + + +
usbd_desc_register
usbd_add_interface
usbd_add_endpoint
    struct usbd_tx_rx_msg tx_msg[16];
    struct usbd_tx_rx_msg rx_msg[16];
struct usbd_interface *intf[16];
usbd_initialize
USBD_IRQHandler
usbd_event_reset_handler
usbd_event_ep0_setup_complete_handler
usbd_event_ep_in_complete_handler
usbd_event_ep_out_complete_handler
usbd_setup_request_handler
tx_msg[ep & 0x7f].cb
rx_msg[ep & 0x7f].cb
usbd_event_ep0_in_complete_handler
tx_msg[ep & 0x7f].cb (ep != 0)
usbd_event_ep0_out_complete_handler
rx_msg[ep & 0x7f].cb (ep != 0)
usbd_standard_request_handler
usbd_class_request_handler
usbd_vendor_request_handler
 \ No newline at end of file diff --git a/docs/zh/usbhost.svg b/docs/zh/usbhost.svg new file mode 100644 index 00000000..b7d537b5 --- /dev/null +++ b/docs/zh/usbhost.svg @@ -0,0 +1,9 @@ +
usbh_initialize
usbh_initialize
usbh_hub_initialize
usbh_hub_initialize
usbh_roothub_register
usbh_roothub_register
create usbh_hub_thread
create usbh_hub_thread
usb_hc_init
usb_hc_init
usbh_roothub_thread_wakeup
usbh_roothub_thread_wakeup +
hub_int_complete_callback
hub_int_complete_callback +
wakeup
wakeup
wakeup
wakeup
usbh_enumerate
usbh_enumerate +
search all ports
search all ports
usbh_hub_events
usbh_hub_events +
CLASS_CONNECT
CLASS_CONNECT +
search all interface drivers
search all interface drivers
usbh_find_class_driver
usbh_find_class_driver +
if hub class？
if hub class？
usbh_int_urb_fill


usbh_submit_urb
usbh_int_urb_fill...
Class Register
Class Register +
USBH_IRQHandler
USBH_IRQHandler +Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/source/demo/usbh_wifi.rst b/docs/zh/usbip/cdns2.rst similarity index 61% rename from docs/source/demo/usbh_wifi.rst rename to docs/zh/usbip/cdns2.rst index be148c7d..88afc8d2 100644 --- a/docs/source/demo/usbh_wifi.rst +++ b/docs/zh/usbip/cdns2.rst @@ -1,2 +1,2 @@ -usbh_wifi +CDNS2 =============== diff --git a/docs/source/demo/usbd_rndis.rst b/docs/zh/usbip/cdns3.rst similarity index 59% rename from docs/source/demo/usbd_rndis.rst rename to docs/zh/usbip/cdns3.rst index 40fba402..c2132d1a 100644 --- a/docs/source/demo/usbd_rndis.rst +++ b/docs/zh/usbip/cdns3.rst @@ -1,2 +1,2 @@ -usbd_rndis +CDNS3 =============== diff --git a/docs/zh/usbip/chipidea.rst b/docs/zh/usbip/chipidea.rst new file mode 100644 index 00000000..57c46ec0 --- /dev/null +++ b/docs/zh/usbip/chipidea.rst @@ -0,0 +1,2 @@ +CHIPIDEA +================= \ No newline at end of file diff --git a/docs/zh/usbip/dwc2.rst b/docs/zh/usbip/dwc2.rst new file mode 100644 index 00000000..6c5a8c08 --- /dev/null +++ b/docs/zh/usbip/dwc2.rst @@ -0,0 +1,2 @@ +DWC2 +================= \ No newline at end of file diff --git a/docs/source/demo/usbd_ecm.rst b/docs/zh/usbip/dwc3.rst similarity index 55% rename from docs/source/demo/usbd_ecm.rst rename to docs/zh/usbip/dwc3.rst index c4c64ab5..746bbee6 100644 --- a/docs/source/demo/usbd_ecm.rst +++ b/docs/zh/usbip/dwc3.rst @@ -1,2 +1,2 @@ -usbd_cdc_ecm +DWC3 =============== diff --git a/docs/zh/usbip/ehci.rst b/docs/zh/usbip/ehci.rst new file mode 100644 index 00000000..637bbe69 --- /dev/null +++ b/docs/zh/usbip/ehci.rst @@ -0,0 +1,2 @@ +EHCI +================= \ No newline at end of file diff --git a/docs/source/demo/usbh_bluetooth.rst b/docs/zh/usbip/fotg210.rst similarity index 51% rename from docs/source/demo/usbh_bluetooth.rst rename to docs/zh/usbip/fotg210.rst index a93844ea..f6e566a8 100644 --- a/docs/source/demo/usbh_bluetooth.rst +++ b/docs/zh/usbip/fotg210.rst @@ -1,2 +1,2 @@ -usbh_bluetooth +FOTG210 =============== diff --git a/docs/zh/usbip/musb.rst b/docs/zh/usbip/musb.rst new file mode 100644 index 00000000..597876c0 --- /dev/null +++ b/docs/zh/usbip/musb.rst @@ -0,0 +1,2 @@ +MUSB +================= \ No newline at end of file diff --git a/docs/zh/usbip/ohci.rst b/docs/zh/usbip/ohci.rst new file mode 100644 index 00000000..8467233b --- /dev/null +++ b/docs/zh/usbip/ohci.rst @@ -0,0 +1,2 @@ +OHCI +================= \ No newline at end of file diff --git a/docs/zh/usbip/xhci.rst b/docs/zh/usbip/xhci.rst new file mode 100644 index 00000000..0c16c2e2 --- /dev/null +++ b/docs/zh/usbip/xhci.rst @@ -0,0 +1,2 @@ +XHCI +================= \ No newline at end of file diff --git a/docs/source/version.rst b/docs/zh/version.rst similarity index 100% rename from docs/source/version.rst rename to docs/zh/version.rst diff --git a/idf_component.yml b/idf_component.yml index 9642e0e2..bcae2d65 100644 --- a/idf_component.yml +++ b/idf_component.yml @@ -1,4 +1,4 @@ -version: "1.5.3" +version: "1.6.0" description: CherryUSB is a tiny and portable USB Stack (device & host) for embedded system with USB IP tags: - usb