mirror of
https://github.com/espressif/esp-idf.git
synced 2026-01-20 09:27:26 +00:00
docs: Update CN translation for usb_host.rst
This commit is contained in:
renpeiying
committed by
peter.marcisovsky
peter.marcisovsky
parent
83b6594307
commit
5fbac0ecf0
@@ -50,11 +50,11 @@ Currently, the Host Library and the underlying Host Stack has the following limi
|
||||
- Only supports using one configuration. Changing to other configurations after enumeration is not supported yet.
|
||||
- Transfer timeouts are not supported yet.
|
||||
- Selective (per-device/per-port) suspend/resume is not supported yet.
|
||||
- Remote Wakeup initiated by a USB Device is not supported yet.
|
||||
- Remote Wakeup initiated by a USB device is not supported yet.
|
||||
- The External Hub Driver: Remote Wakeup feature is not supported (External Hubs are active, even if there are no devices inserted).
|
||||
- The External Hub Driver: Doesn't handle error cases (overcurrent handling, errors during initialization etc. are not implemented yet).
|
||||
- The External Hub Driver: No Interface selection. The Driver uses the first available Interface with Hub Class code (09h).
|
||||
- The External Port Driver: No downstream port debounce mechanism (not implemented yet)
|
||||
- The External Port Driver: No downstream port debounce mechanism (not implemented yet).
|
||||
:esp32p4: - The External Hub Driver: No Transaction Translator layer (No FS/LS Devices support when a Hub is attached to HS Host).
|
||||
|
||||
|
||||
@@ -377,6 +377,7 @@ Global Suspend/Resume
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
USB Host library supports global Suspend/Resume, which suspends and resumes the entire USB bus. The global Suspend/Resume is implemented through the root port(s). When suspended, the USB Host stops sending SOFs, which effectively puts all the devices connected to the USB bus to a suspended state.
|
||||
|
||||
Note that the global Suspend/Resume does **not** suspend/resume the USB-OTG peripheral on the USB Host side, and therefore does **not** reduce power consumption on the host controller itself.
|
||||
|
||||
Events
|
||||
@@ -402,6 +403,7 @@ Auto Suspend Timer
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Users can configure an automatic suspend timer using :cpp:func:`usb_host_lib_set_auto_suspend`. The auto suspend timer is reset every time the USB Host library client processing function handles an event from any client, or when USB Host library itself is processing any event.
|
||||
|
||||
The auto suspend timer actively monitors USB bus activity and USB Host library activity. Specifically:
|
||||
|
||||
- If USB traffic is detected (i.e., any transfer or client-handled event occurs), the timer is automatically reset.
|
||||
@@ -419,7 +421,7 @@ Important considerations for the auto suspend timer:
|
||||
- When the timer expires, the USB Host library event is delivered only if:
|
||||
|
||||
- A device is currently connected to the root port, and
|
||||
- The root port is not already in a suspended state.
|
||||
- The root port is not already in a suspended state
|
||||
|
||||
The auto suspend timer can be configured in the following modes:
|
||||
|
||||
@@ -443,7 +445,7 @@ This mechanism simplifies client implementation and ensures that resume behavior
|
||||
|
||||
Auto-resume via transfer submission is only applicable when the root port is in a suspended state. If the port is already active, transfer submission proceeds as usual.
|
||||
|
||||
The following code snippet demonstrates how to cycle between suspended and resumed states using the auto suspend timer and the Auto resume by transfer submit functionality.
|
||||
The following code snippet demonstrates how to cycle between suspended and resumed states using the auto suspend timer and the auto resume by transfer submit functionality.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@@ -456,7 +458,7 @@ The following code snippet demonstrates how to cycle between suspended and resum
|
||||
// Device will then automatically enter suspended mode after 1 second of inactivity thanks to the auto suspend timer
|
||||
usb_host_transfer_submit(xfer_out);
|
||||
|
||||
// Switch context for 10s. The device will be automatically suspended after ~1s of inactivity.
|
||||
// Switch context for 10s. The device will be automatically suspended after ~1s of inactivity
|
||||
vTaskDelay(pdMS_TO_TICKS(10000));
|
||||
}
|
||||
}
|
||||
@@ -484,7 +486,7 @@ The following code snippet demonstrates how to cycle between suspended and resum
|
||||
|
||||
.. note::
|
||||
|
||||
For more details regarding Suspend and Resume, please refer to `USB 2.0 Specification <https://www.usb.org/document-library/usb-20-specification>`_ > Chapter 11.9 *Suspend and Resume*.
|
||||
For more details regarding suspend and resume, please refer to `USB 2.0 Specification <https://www.usb.org/document-library/usb-20-specification>`_ > Chapter 11.9 *Suspend and Resume*.
|
||||
|
||||
.. ---------------------------------------------------- Examples -------------------------------------------------------
|
||||
|
||||
@@ -494,7 +496,7 @@ Examples
|
||||
Host Library Examples
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- :example:`peripherals/usb/host/usb_host_lib` demonstrates how to use the USB Host Library API to install and register a client, wait for a device connection, print the device's information, handle disconnection, and repeat these steps until a user quits the application.
|
||||
:example:`peripherals/usb/host/usb_host_lib` demonstrates how to use the USB Host Library API to install and register a client, wait for a device connection, print the device's information, handle disconnection, and repeat these steps until a user quits the application.
|
||||
|
||||
Class Driver Examples
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -554,12 +556,15 @@ UVC
|
||||
Example connection using STUSB03E and analog switch (Host mode)
|
||||
|
||||
.. note::
|
||||
|
||||
This schematic is a minimal example intended only to demonstrate the external PHY connection. It omits other essential components and signals (e.g., VCC, GND, RESET) required for a complete, functional {IDF_TARGET_NAME} design.
|
||||
|
||||
The schematic includes both a +5 V rail (used to power USB devices) and a VCC rail (typically 3.3 V). VCC should match the chip supply voltage. Ensure that +5 V for the USB bus is appropriately sourced and protected (e.g., with a power switch and current limiting). Always comply with USB host power requirements, particularly when supporting USB bus-powered devices.
|
||||
|
||||
Hardware configuration is handled via GPIO mapping to the PHY's pins. Any unused pins (e.g., :cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num`) **must be set to -1**.
|
||||
|
||||
.. note::
|
||||
|
||||
The :cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num` pin is **currently not supported** and does not need to be connected.
|
||||
|
||||
**Example Code:**
|
||||
@@ -669,9 +674,7 @@ Supported amount of channels for {IDF_TARGET_NAME} is {IDF_TARGET_OTG_NUM_HOST_C
|
||||
.. note::
|
||||
|
||||
- One free channel is required to enumerate the device.
|
||||
|
||||
- From 1 to N (when N - number of EPs) free channels are required to claim the interface.
|
||||
|
||||
- When there are no more free Host channels available, the device could not be enumerated and its interface cannot be claimed.
|
||||
|
||||
|
||||
|
||||
@@ -39,6 +39,8 @@ USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供
|
||||
- 主机库及其底层主机栈不会在内部自动创建操作系统任务，任务数量完全由主机库接口的使用方式决定。一般来说，任务数量为 ``（运行中的主机 Class 驱动程序数量 + 1）``。
|
||||
- 支持单个 Hub（启用选项 `CONFIG_USB_HOST_HUBS_SUPPORTED`）。
|
||||
- 支持多个 Hub（启用选项 `CONFIG_USB_HOST_HUB_MULTI_LEVEL`）。
|
||||
- 支持全局挂起与恢复，通过挂起或恢复整个总线来实现。
|
||||
- 支持通过提交传输自动触发全局恢复。
|
||||
|
||||
目前，主机库及其底层主机栈存在以下限制：
|
||||
|
||||
@@ -47,6 +49,8 @@ USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供
|
||||
- 仅支持异步传输。
|
||||
- 仅支持使用发现的首个配置，尚不支持变更为其他配置。
|
||||
- 尚不支持传输超时。
|
||||
- 尚未支持选择性（按设备/按端口）挂起/恢复。
|
||||
- 尚不支持由 USB 设备发起的远程唤醒。
|
||||
- 外部 Hub 驱动：不支持远程唤醒功能（即使没有设备插入，外部 Hub 也处于工作状态）。
|
||||
- 外部 Hub 驱动：不处理错误用例（尚未实现过流处理、初始化错误等功能）。
|
||||
- 外部 Hub 驱动：不支持接口选择。驱动程序使用具有 Hub 类代码 (09h) 的第一个可用接口。
|
||||
@@ -364,6 +368,126 @@ USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供
|
||||
#. 删除客户端任务。如有需要，向守护进程任务发送信号。
|
||||
|
||||
|
||||
.. ---------------------------------------------------- 电源管理 -----------------------------------------------
|
||||
|
||||
电源管理
|
||||
----------------
|
||||
|
||||
全局挂起/恢复
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
USB 主机库支持全局挂起/恢复，也就是挂起或恢复整个 USB 总线。全局挂起恢复通过根端口实现。挂起时，USB 主机会停止发送 SOF 包，从而使连接到 USB 总线的所有设备进入挂起状态。
|
||||
|
||||
请注意，全局挂起/恢复并 **不会** 在 USB 主机端挂起/恢复 USB-OTG 外设，因此并 **不会** 降低主机控制器本身的功耗。
|
||||
|
||||
事件
|
||||
^^^^^^
|
||||
|
||||
客户端事件
|
||||
"""""""""""""
|
||||
|
||||
当设备被挂起或恢复时，所有已打开该受影响设备的客户端都会通过以下事件收到通知。每个事件都包含该被挂起或已恢复设备的句柄：
|
||||
|
||||
- :cpp:enumerator:`USB_HOST_CLIENT_EVENT_DEV_SUSPENDED` — 设备已进入挂起状态。
|
||||
|
||||
- :cpp:enumerator:`USB_HOST_CLIENT_EVENT_DEV_RESUMED` — 设备已恢复运行。
|
||||
|
||||
USB 主机库事件
|
||||
""""""""""""""""""""
|
||||
|
||||
下列事件与自动挂起定时器相关联。定时器超时后，其回调函数会解除 USB 主机库处理程序的阻塞并传递该事件：
|
||||
|
||||
- :cpp:enumerator:`USB_HOST_LIB_EVENT_FLAGS_AUTO_SUSPEND` — 表示自动挂起定时器已超时。
|
||||
|
||||
自动挂起定时器
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
可使用 :cpp:func:`usb_host_lib_set_auto_suspend` 配置自动挂起定时器。每当 USB 主机库的客户端处理函数处理来自任意客户端的事件时，或当 USB 主机库本身在处理任何事件时，自动挂起定时器都会被重置。
|
||||
|
||||
自动挂起定时器会主动监测 USB 总线活动以及 USB 主机库的活动情况。具体如下：
|
||||
|
||||
- 如果检测到 USB 流量（即发生任何传输或由客户端处理的事件），定时器会自动重置。
|
||||
- 如果检测到 USB 主机库的活动（即有新设备连接），定时器会自动重置。
|
||||
- 如果 USB 总线和 USB 主机库保持空闲（无流量、客户端事件或库事件），定时器继续倒计时。
|
||||
- 一旦定时器达到指定的超时时间（以毫秒为单位），将触发挂起。
|
||||
|
||||
这种机制确保 USB 主机仅在总线真正空闲时才进入挂起模式，避免在活跃通信期间出现意外挂起。
|
||||
|
||||
自动挂起定时器的重要注意事项：
|
||||
|
||||
- 定时器可配置，即使未连接任何设备也会开始倒计时。
|
||||
- 所有设备断开连接后，定时器停止。
|
||||
- 设备连接或断开时，定时器自动重置。
|
||||
- 定时器超时后，只有在以下情况下才会派发 USB 主机库事件：
|
||||
|
||||
- 当前有设备连接到根端口，并且
|
||||
- 根端口尚未处于挂起状态
|
||||
|
||||
自动挂起定时器可以配置为以下几种模式：
|
||||
|
||||
- **单次** (:cpp:enumerator:`USB_HOST_LIB_PM_SUSPEND_ONE_SHOT`)：定时器超时一次后停止。
|
||||
- **周期性** (:cpp:enumerator:`USB_HOST_LIB_PM_SUSPEND_PERIODIC`)：定时器在每次超时后自动重启，无限重复。
|
||||
|
||||
由传输提交触发自动恢复
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
除了自动挂起定时器之外，USB 主机库还支持在传输提交（控制或非控制）时对已挂起的根端口进行自动恢复。通过此功能，开发人员只需调用传输 API（例如 :cpp:func:`usb_host_transfer_submit` 或 :cpp:func:`usb_host_transfer_submit_control`）即可发起恢复，无需显式调用 :cpp:func:`usb_host_lib_root_port_resume`。
|
||||
|
||||
当根端口处于挂起状态，且有客户端向已挂起的设备提交传输请求时，USB 主机库将执行以下流程：
|
||||
|
||||
1. 自动向根端口发起恢复信号。
|
||||
2. 暂停处理该传输请求，直到恢复信号完成。
|
||||
3. 待总线进入活动（已恢复）状态后提交传输。
|
||||
|
||||
这一机制简化了客户端实现，避免了因手动触发恢复与提交传输并行进行而可能产生的竞态条件，确保恢复行为一致且安全。
|
||||
|
||||
.. note::
|
||||
|
||||
仅在根端口处于挂起状态时，才能通过传输提交进行自动恢复。若根端口已处于活动状态，传输提交将照常进行。
|
||||
|
||||
下面的代码片段演示了如何使用自动挂起定时器和传输提交自动恢复功能，在挂起与恢复状态之间循环切换。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "usb/usb_host.h"
|
||||
|
||||
static void client_task(void *arg)
|
||||
{
|
||||
while(true) {
|
||||
// 向挂起的设备提交传输，以自动恢复设备
|
||||
// 借助自动挂起定时器，设备在无操作 1 秒后自动进入挂起模式
|
||||
usb_host_transfer_submit(xfer_out);
|
||||
|
||||
// 切换上下文 10 秒。设备将在空闲约 1 秒后自动挂起
|
||||
vTaskDelay(pdMS_TO_TICKS(10000));
|
||||
}
|
||||
}
|
||||
|
||||
void usb_host_lib_task(void *arg)
|
||||
{
|
||||
...
|
||||
|
||||
// 将自动挂起定时器设置为周期模式，周期为 1 秒，
|
||||
// 用于在无操作 1 秒后自动挂起设备，并在超时后自动重启
|
||||
usb_host_lib_set_auto_suspend(USB_HOST_LIB_PM_SUSPEND_PERIODIC, 1000);
|
||||
|
||||
while (1) {
|
||||
uint32_t event_flags;
|
||||
usb_host_lib_handle_events(portMAX_DELAY, &event_flags);
|
||||
|
||||
if (event_flags & USB_HOST_LIB_EVENT_FLAGS_AUTO_SUSPEND) {
|
||||
// 自动挂起定时器超时，挂起根端口
|
||||
usb_host_lib_root_port_suspend();
|
||||
}
|
||||
...
|
||||
}
|
||||
...
|
||||
}
|
||||
|
||||
.. note::
|
||||
|
||||
关于挂起与恢复的更多细节，请参阅 `USB 2.0 规范 <https://www.usb.org/document-library/usb-20-specification>`_ > 第 11.9 章 *Suspend and Resume*。
|
||||
|
||||
.. ---------------------------------------------------- Examples -------------------------------------------------------
|
||||
|
||||
示例
|
||||
@@ -432,12 +556,15 @@ UVC
|
||||
使用 STUSB03E 与模拟开关的连接示例（主机模式）
|
||||
|
||||
.. note::
|
||||
|
||||
此原理图为简化示例，用于演示外部 PHY 连接方式，未包含完整 {IDF_TARGET_NAME} 设计所需的所有元器件和信号（如 VCC、GND、RESET 等）。
|
||||
|
||||
图中包含 +5 V 电源轨（用于为 USB 设备供电）和 VCC 电源轨（通常为 3.3 V）。VCC 电压应与芯片供电电压保持一致。确保为 USB 总线提供的 +5 V 电源可靠，并具备必要的保护措施（如电源开关和限流设计）在支持 USB 总线供电设备时，务必遵守 USB 主机的供电规范。
|
||||
|
||||
硬件配置通过将 GPIO 映射到 PHY 引脚实现。任何未使用的引脚（如 :cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num`） **必须设置为 -1**。
|
||||
|
||||
.. note::
|
||||
|
||||
:cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num` 引脚 **当前不支持**，无需连接。
|
||||
|
||||
**示例代码：**
|
||||
@@ -547,9 +674,7 @@ USB 设备可能是热插拔的，因此必须配置电源开关和设备连接
|
||||
.. note::
|
||||
|
||||
- 需要一个空闲通道来枚举设备。
|
||||
|
||||
- 需要 1 到 N（N 为 EP 数量）个空闲通道来占用接口。
|
||||
|
||||
- 如果所有的主机通道都已经被占用，则设备无法进行枚举，也无法获取接口。
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user