forked from espressif/esp-idf
Merge branch 'docs/usb_docs_p4' into 'master'
Update USB host & device documentation for P4 Closes IDF-7724 See merge request espressif/esp-idf!32855
This commit is contained in:
Tomas Rezucha
@@ -8,8 +8,6 @@ api-guides/dfu.rst
|
||||
api-guides/wifi-security.rst
|
||||
api-reference/peripherals/adc_continuous.rst
|
||||
api-reference/peripherals/adc_oneshot.rst
|
||||
api-reference/peripherals/usb_host.rst
|
||||
api-reference/peripherals/usb_device.rst
|
||||
api-reference/peripherals/touch_element.rst
|
||||
api-reference/peripherals/touch_pad.rst
|
||||
api-reference/peripherals/adc_calibration.rst
|
||||
|
||||
@@ -5,9 +5,9 @@ USB Device Stack
|
||||
|
||||
{IDF_TARGET_USB_DP_GPIO_NUM:default="20"}
|
||||
{IDF_TARGET_USB_DM_GPIO_NUM:default="19"}
|
||||
{IDF_TARGET_USB_EP_NUM:default="6"}
|
||||
{IDF_TARGET_USB_EP_NUM_INOUT:default="5"}
|
||||
{IDF_TARGET_USB_EP_NUM_IN:default="1"}
|
||||
{IDF_TARGET_USB_EP_NUM: default="6", esp32p4="15"}
|
||||
{IDF_TARGET_USB_EP_NUM_INOUT:default="5", esp32p4="8"}
|
||||
{IDF_TARGET_USB_EP_NUM_IN:default="1", esp32p4="7"}
|
||||
|
||||
Overview
|
||||
--------
|
||||
@@ -34,16 +34,24 @@ Features
|
||||
Hardware Connection
|
||||
-------------------
|
||||
|
||||
The {IDF_TARGET_NAME} routes the USB D+ and D- signals to GPIOs {IDF_TARGET_USB_DP_GPIO_NUM} and {IDF_TARGET_USB_DM_GPIO_NUM} respectively. For USB device functionality, these GPIOs should be connected to the bus in some way (e.g., via a Micro-B port, USB-C port, or directly to standard-A plug).
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
The {IDF_TARGET_NAME} routes the USB D+ and D- signals to GPIOs {IDF_TARGET_USB_DP_GPIO_NUM} and {IDF_TARGET_USB_DM_GPIO_NUM} respectively. For USB device functionality, these GPIOs should be connected to the bus in some way (e.g., via a Micro-B port, USB-C port, or directly to standard-A plug).
|
||||
|
||||
.. only:: esp32p4
|
||||
|
||||
The {IDF_TARGET_NAME} routes the USB D+ and D- signals to their dedicated pins. For USB device functionality, these pins should be connected to the bus in some way (e.g., via a Micro-B port, USB-C port, or directly to standard-A plug).
|
||||
|
||||
.. figure:: ../../../_static/usb-board-connection.png
|
||||
:align: center
|
||||
:alt: Connection of an USB GPIOs directly to a USB standard-A plug
|
||||
:figclass: align-center
|
||||
|
||||
.. note::
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
If you are using an {IDF_TARGET_NAME} development board with two USB ports, the port labeled "USB" will already be connected to the D+ and D- GPIOs.
|
||||
.. note::
|
||||
|
||||
If you are using an {IDF_TARGET_NAME} development board with two USB ports, the port labeled "USB" will already be connected to the D+ and D- GPIOs.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -95,15 +103,17 @@ Full-speed devices should initialize the following field to provide their config
|
||||
|
||||
- :cpp:member:`configuration_descriptor`
|
||||
|
||||
High-speed devices should initialize the following fields to provide configuration descriptors at each speed:
|
||||
.. only:: esp32p4
|
||||
|
||||
- :cpp:member:`fs_configuration_descriptor`
|
||||
- :cpp:member:`hs_configuration_descriptor`
|
||||
- :cpp:member:`qualifier_descriptor`
|
||||
High-speed devices should initialize the following fields to provide configuration descriptors at each speed:
|
||||
|
||||
.. note::
|
||||
- :cpp:member:`fs_configuration_descriptor`
|
||||
- :cpp:member:`hs_configuration_descriptor`
|
||||
- :cpp:member:`qualifier_descriptor`
|
||||
|
||||
When Device Stack supports high-speed, both :cpp:member:`fs_configuration_descriptor` and :cpp:member:`hs_configuration_descriptor` should be present to comply with USB 2.0 specification.
|
||||
.. note::
|
||||
|
||||
Both :cpp:member:`fs_configuration_descriptor` and :cpp:member:`hs_configuration_descriptor` must be present to comply with USB 2.0 specification.
|
||||
|
||||
The Device Stack will instantiate a USB device based on the descriptors provided in the fields described above when :cpp:func:`tinyusb_driver_install` is called.
|
||||
|
||||
|
||||
@@ -25,18 +25,26 @@ Features & Limitations
|
||||
|
||||
The Host Library has the following features:
|
||||
|
||||
- Supports Full Speed (FS) and Low Speed (LS) Devices.
|
||||
- Supports all four transfer types, i.e., Control, Bulk, Interrupt, and Isochronous.
|
||||
- Allows multiple class drivers to run simultaneously, i.e., multiple clients of the Host Library.
|
||||
- A single device can be used by multiple clients simultaneously, e.g., composite devices.
|
||||
- The Host Library itself and the underlying Host Stack does not internally instantiate any OS tasks. The number of tasks is entirely controlled by how the Host Library interface is used. However, a general rule of thumb regarding the number of tasks is ``(the number of host class drivers running + 1)``.
|
||||
.. list::
|
||||
|
||||
:esp32s2 or esp32s3: - Supports Full Speed (FS) and Low Speed (LS) Devices.
|
||||
:esp32p4: - Supports High Speed (HS), Full Speed (FS) and Low Speed (LS) Devices.
|
||||
- Supports all four transfer types: Control, Bulk, Interrupt, and Isochronous.
|
||||
:esp32p4: - Supports High-Bandwidth Isochronous endpoints.
|
||||
- Allows multiple class drivers to run simultaneously, i.e., multiple clients of the Host Library.
|
||||
- A single device can be used by multiple clients simultaneously, e.g., composite devices.
|
||||
- The Host Library itself and the underlying Host Stack does not internally instantiate any OS tasks. The number of tasks is entirely controlled by how the Host Library interface is used. However, a general rule of thumb regarding the number of tasks is ``(the number of host class drivers running + 1)``.
|
||||
|
||||
Currently, the Host Library and the underlying Host Stack has the following limitations:
|
||||
|
||||
- Only supports a single device, but the Host Library's API is designed for multiple device support.
|
||||
- Only supports Asynchronous transfers.
|
||||
- Only supports using the first configuration found. Changing to other configurations is not supported yet.
|
||||
- Transfer timeouts are not supported yet.
|
||||
.. list::
|
||||
|
||||
- Only supports a single device, but the Host Library's API is designed for multiple device support.
|
||||
- Only supports Asynchronous transfers.
|
||||
- Only supports using one configuration. Changing to other configurations after enumeration is not supported yet.
|
||||
- Transfer timeouts are not supported yet.
|
||||
:esp32p4: - {IDF_TARGET_NAME} contains two USB-OTG peripherals USB 2.0 OTG High-Speed and USB 2.0 OTG Full-Speed. Only the High-Speed instance is supported now.
|
||||
:esp32p4: - {IDF_TARGET_NAME} cannot enumerate Low-Speed devices yet.
|
||||
|
||||
|
||||
.. -------------------------------------------------- Architecture -----------------------------------------------------
|
||||
@@ -89,7 +97,7 @@ Therefore, in addition to the client tasks, the Host Library also requires a tas
|
||||
Devices
|
||||
^^^^^^^
|
||||
|
||||
The Host Library shields clients from the details of device handling, encompassing details such as connection, memory allocation, and enumeration. The clients are provided only with a list of already connected and enumerated devices to choose from. During enumeration, each device is automatically configured to use the first configuration found, namely, the first configuration descriptor returned on a Get Configuration Descriptor request. For most standard devices, the first configuration will have a ``bConfigurationValue`` of ``1``.
|
||||
The Host Library shields clients from the details of device handling, encompassing details such as connection, memory allocation, and enumeration. The clients are provided only with a list of already connected and enumerated devices to choose from. By default during enumeration, each device is automatically configured to use the first configuration found, namely, the first configuration descriptor returned on a Get Configuration Descriptor request. For most standard devices, the first configuration will have a ``bConfigurationValue`` of ``1``. If option :ref:`CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` is enabled, a different ``bConfigurationValue`` can be selected, see `Multiple configuration Support`_ for more details.
|
||||
|
||||
It is possible for two or more clients to simultaneously communicate with the same device as long as they are not communicating to the same interface. However, multiple clients can simultaneously communicate with the same device's default endpoint (i.e., EP0), which will result in their control transfers being serialized.
|
||||
|
||||
|
||||
@@ -5,9 +5,9 @@ USB 设备栈
|
||||
|
||||
{IDF_TARGET_USB_DP_GPIO_NUM:default="20"}
|
||||
{IDF_TARGET_USB_DM_GPIO_NUM:default="19"}
|
||||
{IDF_TARGET_USB_EP_NUM:default="6"}
|
||||
{IDF_TARGET_USB_EP_NUM_INOUT:default="5"}
|
||||
{IDF_TARGET_USB_EP_NUM_IN:default="1"}
|
||||
{IDF_TARGET_USB_EP_NUM: default="6", esp32p4="15"}
|
||||
{IDF_TARGET_USB_EP_NUM_INOUT:default="5", esp32p4="8"}
|
||||
{IDF_TARGET_USB_EP_NUM_IN:default="1", esp32p4="7"}
|
||||
|
||||
概述
|
||||
--------
|
||||
@@ -34,16 +34,24 @@ USB 设备栈（以下简称设备栈）支持在 {IDF_TARGET_NAME} 上启用 US
|
||||
硬件连接
|
||||
--------
|
||||
|
||||
{IDF_TARGET_NAME} 将 USB D+ 和 D- 信号分别路由到 GPIO {IDF_TARGET_USB_DP_GPIO_NUM} 和 {IDF_TARGET_USB_DM_GPIO_NUM}。为了实现 USB 设备功能，这些 GPIO 应通过某种方式连接到总线上（例如，通过 Micro-B 端口、USB-C 端口或直接连接到标准-A 插头）。
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
{IDF_TARGET_NAME} 将 USB D+ 和 D- 信号分别路由到 GPIO {IDF_TARGET_USB_DP_GPIO_NUM} 和 {IDF_TARGET_USB_DM_GPIO_NUM}。为了实现 USB 设备功能，这些 GPIO 应通过某种方式连接到总线（例如，通过 Micro-B 端口、USB-C 端口或直接连接到标准-A 插头）。
|
||||
|
||||
.. only:: esp32p4
|
||||
|
||||
{IDF_TARGET_NAME} 将 USB D+ 和 D- 信号路由到其专用引脚。为了实现 USB 设备功能，这些引脚应通过某种方式连接到总线（例如，通过 Micro-B 端口、USB-C 端口或直接连接到标准-A 插头）。
|
||||
|
||||
.. figure:: ../../../_static/usb-board-connection.png
|
||||
:align: center
|
||||
:alt: 将 USB GPIO 直接接连至 USB 标准-A 插头
|
||||
:figclass: align-center
|
||||
|
||||
.. note::
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
如果你使用带有两个 USB 端口的 {IDF_TARGET_NAME} 开发板，标有 "USB" 的端口已经连接到 D+ 和 D- GPIO。
|
||||
.. note::
|
||||
|
||||
如果你使用带有两个 USB 端口的 {IDF_TARGET_NAME} 开发板，标有 "USB" 的端口已经连接到 D+ 和 D- GPIO。
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -95,15 +103,17 @@ USB 设备栈（以下简称设备栈）支持在 {IDF_TARGET_NAME} 上启用 US
|
||||
|
||||
- :cpp:member:`configuration_descriptor`
|
||||
|
||||
高速 USB 设备应初始化以下字段，以提供不同速度下的配置描述符：
|
||||
.. only:: esp32p4
|
||||
|
||||
- :cpp:member:`fs_configuration_descriptor`
|
||||
- :cpp:member:`hs_configuration_descriptor`
|
||||
- :cpp:member:`qualifier_descriptor`
|
||||
高速 USB 设备应初始化以下字段，以提供不同速度下的配置描述符：
|
||||
|
||||
.. note::
|
||||
- :cpp:member:`fs_configuration_descriptor`
|
||||
- :cpp:member:`hs_configuration_descriptor`
|
||||
- :cpp:member:`qualifier_descriptor`
|
||||
|
||||
若设备栈支持高速，为符合 USB 2.0 协议规范，应同时初始化 :cpp:member:`fs_configuration_descriptor` 和 :cpp:member:`hs_configuration_descriptor`。
|
||||
.. note::
|
||||
|
||||
为符合 USB 2.0 协议规范，需同时初始化 :cpp:member:`fs_configuration_descriptor` 和 :cpp:member:`hs_configuration_descriptor`。
|
||||
|
||||
调用 :cpp:func:`tinyusb_driver_install` 时，设备栈将基于上述字段中提供的描述符实现 USB 设备。
|
||||
|
||||
|
||||
@@ -25,18 +25,26 @@ USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供
|
||||
|
||||
主机库具有以下特性：
|
||||
|
||||
- 支持全速 (FS) 和低速 (LS) 设备。
|
||||
- 支持四种传输类型，即控制传输、块传输、中断传输和同步传输。
|
||||
- 支持多个 Class 驱动程序同时运行，即主机的多个客户端同时运行。
|
||||
- 单个设备可以由多个客户端同时使用，如复合设备。
|
||||
- 主机库及其底层主机栈不会在内部自动创建操作系统任务，任务数量完全由主机库接口的使用方式决定。一般来说，任务数量为 ``（运行中的主机 Class 驱动程序数量 + 1）``。
|
||||
.. list::
|
||||
|
||||
:esp32s2 or esp32s3: - 支持全速 (FS) 和低速 (LS) 设备。
|
||||
:esp32p4: - 支持高速 (HS)、全速 (FS) 和低速 (LS) 设备。
|
||||
- 支持四种传输类型，即控制传输、块传输、中断传输和同步传输。
|
||||
:esp32p4: - 支持高带宽等时性端点。
|
||||
- 支持多个 Class 驱动程序同时运行，即主机的多个客户端同时运行。
|
||||
- 单个设备可以由多个客户端同时使用，如复合设备。
|
||||
- 主机库及其底层主机栈不会在内部自动创建操作系统任务，任务数量完全由主机库接口的使用方式决定。一般来说，任务数量为 ``（运行中的主机 Class 驱动程序数量 + 1）``。
|
||||
|
||||
目前，主机库及其底层主机栈存在以下限制：
|
||||
|
||||
- 仅支持单个设备，而主机库的 API 支持多设备。
|
||||
- 仅支持异步传输。
|
||||
- 仅支持使用发现的首个配置，尚不支持变更为其他配置。
|
||||
- 尚不支持传输超时。
|
||||
.. list::
|
||||
|
||||
- 仅支持单个设备，而主机库的 API 支持多设备。
|
||||
- 仅支持异步传输。
|
||||
- 仅支持使用发现的首个配置，尚不支持变更为其他配置。
|
||||
- 尚不支持传输超时。
|
||||
:esp32p4: - {IDF_TARGET_NAME} 包含两个 USB-OTG 外设：USB 2.0 OTG 高速和 USB 2.0 OTG 全速。目前仅支持高速实例。
|
||||
:esp32p4: - {IDF_TARGET_NAME} 目前无法枚举低速设备。
|
||||
|
||||
|
||||
.. -------------------------------------------------- Architecture -----------------------------------------------------
|
||||
@@ -89,7 +97,7 @@ USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供
|
||||
设备
|
||||
^^^^^^^
|
||||
|
||||
主机库隔离了客户端与设备处理的细节，包括连接、内存分配和枚举等，客户端只需提供已连接且已枚举的设备列表供选择。在枚举过程中，每个设备都会自动配置为使用找到的第一个配置，即通过获取配置描述符请求返回的第一个配置描述符。对于大多数标准设备，通常将第一个配置的 ``bConfigurationValue`` 设置为 ``1``。
|
||||
主机库隔离了客户端与设备处理的细节，包括连接、内存分配和枚举等，客户端只需提供已连接且已枚举的设备列表供选择。默认情况下，在枚举过程中，每个设备都会自动配置为使用找到的第一个配置，即通过获取配置描述符请求返回的第一个配置描述符。对于大多数标准设备，通常将第一个配置的 ``bConfigurationValue`` 设置为 ``1``。启用选项 :ref:`CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` 后，可以选择不同的 ``bConfigurationValue``。获取更多详细信息，请参阅 `Multiple configuration Support_`。
|
||||
|
||||
只要不与相同接口通信，两个及以上的客户端可以同时与同一设备通信。然而，多个客户端同时与相同设备的默认端点（即 EP0）通信，将导致它们的控制传输序列化。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user