Merge branch 'feat/usb_host_set_device_config_v5.2' into 'release/v5.2'

USB Host: Add enumeration callback filter (backport v5.2)

See merge request espressif/esp-idf!28550

docs/en/api-reference/peripherals/usb_host.rst

@@ -390,6 +390,62 @@ UVC
 * A host class driver for the USB Video Device Class is distributed as a managed component via the `ESP-IDF Component Registry <https://components.espressif.com/component/espressif/usb_host_uvc>`__.
 * The :example:`peripherals/usb/host/uvc` example demonstrates the usage of the UVC host driver to receive a video stream from a USB camera and optionally forward that stream over Wi-Fi.
 
+.. ---------------------------------------------- USB Host Menuconfig --------------------------------------------------
+
+Host Stack Configuration
+------------------------
+
+Non-Compliant Device Support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To support USB devices that are non-compliant in various scenarios or exhibit specific behaviors, it is possible to configure the USB Host stack.
+
+As a USB device may be hot-plugged, it is essential to have the configurable delays between power switching and device attachment, and when the device's internal power has stabilized.
+
+Enumeration Configuration
+"""""""""""""""""""""""""
+
+During the process of enumerating connected USB devices, several timeout values ensure the proper functioning of the device.
+
+.. figure:: ../../../_static/usb_host/poweron-timings.png
+    :align: center
+    :alt: USB Root Hub Power-on and Connection Events Timing
+    :figclass: align-center
+
+    USB Root Hub Power-on and Connection Events Timing
+
+The figure above shows all the timeouts associated with both turning on port power with a device connected and hot-plugging a device.
+
+* After a port is reset or resumed, the USB system software is expected to provide a "recovery" interval of 10 ms before the device attached to the port is expected to respond to data transfers.
+* After the reset/resume recovery interval, if a device receives a ``SetAddress()`` request, the device must be able to complete processing of the request and be able to successfully complete the Status stage of the request within 50 ms.
+* After successful completion of the Status stage, the device is allowed a ``SetAddress()`` recovery interval of 2 ms.
+
+.. note::
+
+    For more details regarding connection event timings, please refer to *Universal Serial Bus 2.0 Specification* > Chapter 7.1.7.3 *Connect and Disconnect Signaling*.
+
+Configurable parameters of the USB host stack can be configured with multiple options via Menuconfig.
+
+* For debounce delay, refer to :ref:`CONFIG_USB_HOST_DEBOUNCE_DELAY_MS`.
+* For reset hold interval, refer to :ref:`CONFIG_USB_HOST_RESET_HOLD_MS`.
+* For reset recovery interval, refer to :ref:`CONFIG_USB_HOST_RESET_RECOVERY_MS`.
+* For ``SetAddress()`` recovery interval, refer to :ref:`CONFIG_USB_HOST_SET_ADDR_RECOVERY_MS`.
+
+Multiple Configuration Support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To support USB devices that have more than one configuration, it is possible to specify the desired configuration number during a device's enumeration process.
+
+Enumeration Filter
+""""""""""""""""""
+
+The enumeration filter is a callback function of type :cpp:type:`usb_host_enum_filter_cb_t` called at the beginning of the enumeration process once a device descriptor is read from a newly attached USB device. Consequently, the user is provided with the obtained device descriptor. Through this callback, the user can:
+
+* Select the configuration of the USB device.
+* Filter which USB devices should be enumerated.
+
+To use the enumeration filter, users should enable the :ref:`CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` option using menuconfig. Users can specify the callback by setting :cpp:member:`usb_host_config_t::enum_filter_cb` which is then passed to the Host Library when calling :cpp:func:`usb_host_install`.
+
 .. -------------------------------------------------- API Reference ----------------------------------------------------
 
 API Reference

docs/zh_CN/api-reference/peripherals/usb_host.rst

@@ -390,6 +390,47 @@ UVC
 * USB 视频设备 Class 的主机 Class 驱动程序作为托管组件通过 `ESP-IDF 组件注册器 <https://components.espressif.com/component/espressif/usb_host_uvc>`__ 分发。
 * 示例 :example:`peripherals/usb/host/uvc` 展示了如何使用 UVC 主机驱动程序接收来自 USB 摄像头的视频流，并可选择将该流通过 Wi-Fi 转发。
 
+.. ---------------------------------------------- USB Host Menuconfig --------------------------------------------------
+
+主机栈配置
+----------
+
+非兼容设备支持
+^^^^^^^^^^^^^^
+
+为了支持在某些情况下非兼容或会表现出特定行为的 USB 设备，可以对 USB 主机栈进行配置。
+
+USB 设备可能是热插拔的，因此必须配置电源开关和设备连接之间的延迟，以及设备内部电源稳定后的延迟。
+
+枚举配置
+""""""""
+
+在枚举已连接 USB 设备的过程中，一些超时值可确保设备正常运行。
+
+.. figure:: ../../../_static/usb_host/poweron-timings.png
+    :align: center
+    :alt: USB 根集线器上电和连接事件时序
+    :figclass: align-center
+
+    USB 根集线器上电和连接事件时序
+
+上图展示了与连接设备时开启端口电源和热插拔设备相关的所有超时值。
+
+* 端口复位或恢复运行后，USB 系统软件应提供 10 毫秒的恢复时间，此后连接到端口的设备才会响应数据传输。
+* 恢复时间结束后，如果设备收到 ``SetAddress()`` 请求，设备必须能够完成对该请求的处理，并能在 50 毫秒内成功完成请求的状态 (Status) 阶段。
+* 状态阶段结束后，设备允许有 2 毫秒的 ``SetAddress()`` 恢复时间。
+
+.. note::
+
+    有关连接事件时序的更多信息，请参阅 *通用串行总线 2.0 规范* > 第 7.1.7.3 章 *连接和断开信令*。
+
+可通过 Menuconfig 选项设置 USB 主机栈的可配置参数。
+
+* :ref:`CONFIG_USB_HOST_DEBOUNCE_DELAY_MS` 用于配置防抖延迟。
+* :ref:`CONFIG_USB_HOST_RESET_HOLD_MS` 用于配置重置保持时间。
+* :ref:`CONFIG_USB_HOST_RESET_RECOVERY_MS` 用于配置重置恢复时间。
+* :ref:`CONFIG_USB_HOST_SET_ADDR_RECOVERY_MS` 用于配置 ``SetAddress()`` 恢复时间。
+
 .. -------------------------------------------------- API Reference ----------------------------------------------------
 
 API 参考