From f10000f366123a5c23192d414271c177ba55241d Mon Sep 17 00:00:00 2001 From: Peter Marcisovsky Date: Wed, 3 Jan 2024 12:52:51 +0100 Subject: [PATCH] feat(docs): added usb host enumeration filter description - CN and EN docs --- docs/en/api-reference/peripherals/usb_host.rst | 17 ++++++++++++++++- .../api-reference/peripherals/usb_host.rst | 15 +++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/en/api-reference/peripherals/usb_host.rst b/docs/en/api-reference/peripherals/usb_host.rst index db2d325452..ea30d2f507 100644 --- a/docs/en/api-reference/peripherals/usb_host.rst +++ b/docs/en/api-reference/peripherals/usb_host.rst @@ -428,7 +428,22 @@ Configurable parameters of the USB host stack can be configured with multiple op * 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`. -* Fer ``SetAddress()`` recovery interval, refer to :ref:`CONFIG_USB_HOST_SET_ADDR_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 ---------------------------------------------------- diff --git a/docs/zh_CN/api-reference/peripherals/usb_host.rst b/docs/zh_CN/api-reference/peripherals/usb_host.rst index 3371b4c7aa..967f107630 100644 --- a/docs/zh_CN/api-reference/peripherals/usb_host.rst +++ b/docs/zh_CN/api-reference/peripherals/usb_host.rst @@ -430,6 +430,21 @@ USB 设备可能是热插拔的，因此必须配置电源开关和设备连接 * :ref:`CONFIG_USB_HOST_RESET_RECOVERY_MS` 用于配置重置恢复时间。 * :ref:`CONFIG_USB_HOST_SET_ADDR_RECOVERY_MS` 用于配置 ``SetAddress()`` 恢复时间。 +多项配置支持 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +对于具有多项配置的 USB 设备，可以在设备枚举过程中指定所需的配置编号。 + +枚举过滤器 +"""""""""""""""""" + +枚举过滤器是类型为 :cpp:type:`usb_host_enum_filter_cb_t` 的回调函数。从新连接的 USB 设备上读取设备描述符后，USB 主机栈会在枚举过程开始时调用枚举过滤器，从而为用户提供读取的设备描述符。借助此回调，用户得以： + +* 选择 USB 设备的配置。 +* 过滤应该进行枚举的 USB 设备。 + +在 menuconfig 中启用 :ref:`CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` 选项即可启用枚举过滤器。可以通过设置 :cpp:member:`usb_host_config_t::enum_filter_cb` 来指定回调函数，该函数会在调用 :cpp:func:`usb_host_install` 时传递至主机库。 + .. -------------------------------------------------- API Reference ---------------------------------------------------- API 参考