Merge branch 'docs/usb_host_ext_port_driver' into 'master'
docs(ext_port): Maintainers Notes for the External Port Driver Closes IDF-11106 See merge request espressif/esp-idf!33350
This commit is contained in:
Roman Leonov
@@ -18,7 +18,7 @@ USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供
|
||||
然而，由于以下的某些原因（但不仅限于此），有时你可能需要直接使用主机库：
|
||||
|
||||
- 需要实现自定义主机 Class 驱动程序
|
||||
- 需要更低级别的抽象
|
||||
- 需要更低级别的 USB 主机 API
|
||||
|
||||
特性和限制
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -34,17 +34,23 @@ USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供
|
||||
- 支持多个 Class 驱动程序同时运行，即主机的多个客户端同时运行。
|
||||
- 单个设备可以由多个客户端同时使用，如复合设备。
|
||||
- 主机库及其底层主机栈不会在内部自动创建操作系统任务，任务数量完全由主机库接口的使用方式决定。一般来说，任务数量为 ``（运行中的主机 Class 驱动程序数量 + 1）``。
|
||||
- 支持单个 Hub（启用选项 :ref:`CONFIG_USB_HOST_HUBS_SUPPORTED`）。
|
||||
- 支持多个 Hub（启用选项 :ref:`CONFIG_USB_HOST_HUB_MULTI_LEVEL`）。
|
||||
|
||||
目前，主机库及其底层主机栈存在以下限制：
|
||||
|
||||
.. list::
|
||||
|
||||
- 仅支持单个设备，而主机库的 API 支持多设备。
|
||||
- 仅支持异步传输。
|
||||
- 仅支持使用发现的首个配置，尚不支持变更为其他配置。
|
||||
- 尚不支持传输超时。
|
||||
:esp32p4: - {IDF_TARGET_NAME} 包含两个 USB-OTG 外设：USB 2.0 OTG 高速和 USB 2.0 OTG 全速。目前仅支持高速实例。
|
||||
:esp32p4: - {IDF_TARGET_NAME} 目前无法枚举低速设备。
|
||||
- 外部 Hub 驱动：仅支持与上游端口速率相同的设备。（例如，低速设备无法通过全速外部 Hub 工作。）
|
||||
- 外部 Hub 驱动：不支持远程唤醒功能（即使没有设备插入，外部 Hub 也处于工作状态）。
|
||||
- 外部 Hub 驱动：不处理错误用例（尚未实现过流处理、初始化错误等功能）。
|
||||
- 外部 Hub 驱动：不支持接口选择。驱动程序使用具有 Hub 类代码 (09h) 的第一个可用接口。
|
||||
- 外部端口驱动：无下游端口去抖动机制（尚未实现）。
|
||||
:esp32p4: - 外部 Hub 驱动：无事务转换层（当 Hub 连接到高速主机时，不支持全速/低速设备）。
|
||||
|
||||
|
||||
.. -------------------------------------------------- Architecture -----------------------------------------------------
|
||||
@@ -97,7 +103,7 @@ USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供
|
||||
设备
|
||||
^^^^^^^
|
||||
|
||||
主机库隔离了客户端与设备处理的细节，包括连接、内存分配和枚举等，客户端只需提供已连接且已枚举的设备列表供选择。默认情况下，在枚举过程中，每个设备都会自动配置为使用找到的第一个配置，即通过获取配置描述符请求返回的第一个配置描述符。对于大多数标准设备，通常将第一个配置的 ``bConfigurationValue`` 设置为 ``1``。启用选项 :ref:`CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` 后，可以选择不同的 ``bConfigurationValue``。获取更多详细信息，请参阅 `Multiple configuration Support_`。
|
||||
主机库隔离了客户端与设备处理的细节，包括连接、内存分配和枚举等，客户端只需提供已连接且已枚举的设备列表供选择。默认情况下，在枚举过程中，每个设备都会自动配置为使用找到的第一个配置，即通过获取配置描述符请求返回的第一个配置描述符。对于大多数标准设备，通常将第一个配置的 ``bConfigurationValue`` 设置为 ``1``。启用选项 :ref:`CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` 后，可以选择不同的 ``bConfigurationValue``。获取更多详细信息，请参阅 `多项配置支持`_。
|
||||
|
||||
只要不与相同接口通信，两个及以上的客户端可以同时与同一设备通信。然而，多个客户端同时与相同设备的默认端点（即 EP0）通信，将导致它们的控制传输序列化。
|
||||
|
||||
@@ -438,6 +444,44 @@ USB 设备可能是热插拔的，因此必须配置电源开关和设备连接
|
||||
* :ref:`CONFIG_USB_HOST_RESET_RECOVERY_MS` 用于配置重置恢复时间。
|
||||
* :ref:`CONFIG_USB_HOST_SET_ADDR_RECOVERY_MS` 用于配置 ``SetAddress()`` 恢复时间。
|
||||
|
||||
下游端口配置
|
||||
^^^^^^^^^^^^
|
||||
|
||||
当支持外部 Hub 功能时，可以为外部 Hub 端口配置多个参数。
|
||||
|
||||
每个外部 Hub 都有一个 Hub 描述符，用于描述设备特性。
|
||||
|
||||
.. note::
|
||||
|
||||
有关 Hub 描述符的详细信息，请参考 `USB 2.0 规范 <https://www.usb.org/document-library/usb-20-specification>`_ > 章节 11.23.2.1 *Hub Descriptor*。
|
||||
|
||||
可以通过 Menuconfig 配置下游端口的可配置参数。
|
||||
|
||||
* 对于在端口上电后稳定电源的自定义值（PwrOn2PwrGood 值），请参阅 :ref:`CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_MS`。
|
||||
* 对于复位恢复间隔，请参阅 :ref:`CONFIG_USB_HOST_EXT_PORT_RESET_RECOVERY_DELAY_MS`。
|
||||
|
||||
.. note::
|
||||
|
||||
规范规定，对于没有电源开关的 Hub，PwrOn2PwrGood 必须设置为零。同时，对于某些设备，可以增加此值以提供额外的上电时间。如需启用此功能，请参考 :ref:`CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_ENABLE`。
|
||||
|
||||
主机通道
|
||||
"""""""""""""
|
||||
|
||||
当启用外部 Hub 支持功能（:ref:`CONFIG_USB_HOST_HUBS_SUPPORTED`）时，主机通道的数量非常重要，因为每个下游设备都需要空闲通道。
|
||||
|
||||
每个连接的设备需要不同数量的通道，而所需通道数则取决于设备类别（EP 数量）。
|
||||
|
||||
对于 {IDF_TARGET_NAME}，支持的通道数量为 {OTG_NUM_HOST_CHAN}。
|
||||
|
||||
.. note::
|
||||
|
||||
- 需要一个空闲通道来枚举设备。
|
||||
|
||||
- 需要 1 到 N（N 为 EP 数量）个空闲通道来占用接口。
|
||||
|
||||
- 如果所有的主机通道都已经被占用，则设备无法进行枚举，也无法获取接口。
|
||||
|
||||
|
||||
多项配置支持
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst
|
||||
Reference in New Issue
Block a user