Merge pull request #402 from espressif/feat/usb_dual_host

feat(usb/host): Add support for USB dual host on ESP32-P4

Author: tore-espressif

docs/en/usb_host.rst

@@ -33,7 +33,7 @@ The Host Library has the following features:
     :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.
-    :esp32p4: - {IDF_TARGET_NAME} includes two USB 2.0 OTG peripherals: one High-Speed and one Full-Speed. Both support USB Host functionality. However, due to a current software limitation, only one can operate as a USB Host at a time. Support for dual USB Host operation is planned for a future update.
+    :esp32p4: - {IDF_TARGET_NAME} has two USB 2.0 OTG controllers: one High-Speed and one Full-Speed. Each controller can operate as a USB host independently, so either one alone or both together can function as USB hosts simultaneously.
     - 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)``.
@@ -54,7 +54,6 @@ Currently, the Host Library and the underlying Host Stack has the following limi
     - 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).
     :esp32p4: - The External Hub Driver: No Transaction Translator layer (No FS/LS Devices support when a Hub is attached to HS Host).
 
 
@@ -536,8 +535,7 @@ CDC-ACM
 """""""
 
 * A host class driver for the Communication Device Class (Abstract Control Model) is distributed as a managed component via the `ESP Component Registry <https://components.espressif.com/component/espressif/usb_host_cdc_acm>`__.
-* `cdc_acm_host <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb/host/cdc/cdc_acm_host>`__ demonstrates how to use the CDC-ACM Host Driver to enable communication between {IDF_TARGET_NAME} and a USB CDC-ACM device.
-* `cdc_acm_vcp <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb/host/cdc/cdc_acm_vcp>`__ demonstrates how to extend the CDC-ACM driver for Virtual Communication Port (VCP) devices like CP210x, FTDI FT23x or CH34x devices, and how to control the device and send data using the CDC-ACM API.
+* `cdc_acm_host <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb/host/cdc>`__ demonstrates how to use the CDC-ACM Host Driver to enable communication between {IDF_TARGET_NAME} and a USB CDC-ACM device, including vendor-specific devices such as CP210x, FTDI FT23x or CH34x.
 * The CDC-ACM driver is also used in `esp_modem examples <https://github.com/espressif/esp-protocols/tree/master/components/esp_modem/examples>`__, where it is used for communication with cellular modems.
 
 MSC

docs/en/usb_host/usb_host_notes_arch.rst

@@ -26,13 +26,13 @@ The layers of the Host Stack are described in the following table. The layers ar
       - The HAL (Hardware Abstraction Layer) abstracts the operating steps of the USB controller into functions according to ESP-IDF's `Hardware Abstraction API Guidelines <https://docs.espressif.com/projects/esp-idf/en/stable/{IDF_TARGET_PATH_NAME}/api-guides/hardware-abstraction.html>`__. This layer also abstracts the controller's host port and host channels, and provides APIs to operate the them.
     * - HCD
       - ``hcd.h``, ``hcd.c``
-      - The HCD (Host Controller Driver) acts as hardware agnostic API for all USB controllers (i.e., an API that can theoretically be used with any USB controller implementation). This layer also abstracts the root port (i.e., root hub) and USB pipes.
+      - The HCD (Host Controller Driver) acts as hardware agnostic API for all USB controllers (i.e., an API that can theoretically be used with any USB controller implementation). This layer also abstracts the root port and USB pipes.
     * - USBH and Hub Driver
       - ``usbh.h``, ``usbh.c``
       - The USBH (USB Host Driver) layer is equivalent to the USBD layer described in chapter 10 of the USB2.0 specification. The USBH presents an abstraction of USB devices, internally manages a list of connected devices (i.e., device pool), and also arbitrates device sharing between clients (i.e., tracks which endpoints are in use and also presents a shared endpoint 0).
     * - Hub Driver
-      - ``hub.h``, ``hub.c``
-      - The Hub Driver layer acts as a special client of the USBH that is responsible for handling device attachment/detachment, and notifying the USBH of such events. For device attachment, the Hub Driver also handles the enumeration process as well.
+      - ``hub.h``, ``hub.c``, ``enum.h``, ``enum.c``
+      - The Hub Driver layer implements the Root HUB and acts as a special client of the USBH that is responsible for handling device attachment/detachment, and notifying the USBH of such events. For device attachment, the Hub Driver also handles the enumeration process as well.
     * - USB Host Library
       - ``usb_host.h``, ``usb_host.c``
       - The USB Host Library layer is the lowest public API layer of the Host Stack and presents the concept of USB Host Clients. The abstraction of clients allows for multiple class drivers to coexist simultaneously (where each class roughly maps to a single client) and also acts as a mechanism for division of labor (where each client is responsible for its own processing and event handling).

docs/zh_CN/usb_host.rst

@@ -507,8 +507,7 @@ CDC-ACM
 """""""
 
 * 通信设备 Class（抽象控制模型）的主机 Class 驱动程序通过 `乐鑫组件注册表 <https://components.espressif.com/component/espressif/usb_host_cdc_acm>`__ 作为受管理的组件分发。
-* 示例 `cdc_acm_host <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb/host/cdc/cdc_acm_host>`__ 演示了使用 CDC-ACM 主机驱动程序组件，实现 {IDF_TARGET_NAME} 与 USB CDC-ACM 设备的通信。
-* 示例 `cdc_acm_vcp <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb/host/cdc/cdc_acm_vcp>`__ 演示了如何扩展 CDC-ACM 的主机驱动程序，以支持 VCP 设备（即虚拟通信端口设备，如 CP210x、FTDI FT23x 或 CH34x），以及如何使用 CDC-ACM API 控制设备并发送数据。
+* 示例 `cdc_acm_host <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb/host/cdc>`__ 演示了如何使用 CDC-ACM 主机驱动程序，让 {IDF_TARGET_NAME} 与 USB CDC-ACM 设备通信，包括 CP210x、FTDI FT23x 或 CH34x 等厂商设备。
 * 示例 `esp_modem <https://github.com/espressif/esp-protocols/tree/master/components/esp_modem/examples>`__ 中也使用了 CDC-ACM 驱动程序，该程序在这些示例中与蜂窝模块通信。
 
 MSC

host/usb/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this component will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- USB Dual Host support on ESP32-P4
+
 ## [1.2.0] - 2026-02-05
 
 ### Added

host/usb/include/usb/usb_host.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -123,7 +123,7 @@ typedef struct {
     bool root_port_unpowered;                   /**< If set, the USB Host Library will not power on the root port on installation.
                                                      This allows users to power on the root port manually by calling
                                                      usb_host_lib_set_root_port_power(). */
-    int intr_flags;                             /**< Interrupt flags for the underlying ISR used by the USB Host stack */
+    int intr_flags;                             /**< Interrupt flags for the underlying ISR used by the USB Host stack. In dual host applications, this applies to all ports.*/
     usb_host_enum_filter_cb_t enum_filter_cb;   /**< Enumeration filter callback. Enable CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK
                                                      to use this feature. Set to NULL otherwise. */
     struct {
@@ -133,7 +133,7 @@ typedef struct {
                                        Can be 0 if periodic TX endpoints are not used. */
         uint32_t rx_fifo_lines;   /**< Required: Number of RX FIFO lines.
                                        Must be > 0 to enable custom configuration. */
-    } fifo_settings_custom;       /**< Optional custom FIFO configuration (advanced use).
+    } fifo_settings_custom;       /**< Optional custom FIFO configuration (advanced use), ignored for dual port applications.
                                        RX and NPTX must be > 0. If all fields are zero,
                                        a default configuration will be selected based on Kconfig bias. */
     unsigned peripheral_map;      /**< Selects the USB peripheral(s) to use.
@@ -172,8 +172,10 @@ typedef struct {
  * @note If skip_phy_setup is set in the install configuration, the user is responsible for ensuring that the underlying
  *       Host Controller is enabled and the USB PHY (internal or external) is already setup before this function is
  *       called.
- * @param[in] config USB Host Library configuration
  *
+ * @note In dual host configuration, fifo_settings_custom field is ignored and intr_flags field is used for all ports.
+ *
+ * @param[in] config USB Host Library configuration
  * @return
  *    - ESP_OK: USB Host installed successfully
  *    - ESP_ERR_INVALID_ARG: Invalid argument

host/usb/src/usb_host.c

@@ -161,10 +161,10 @@ typedef struct {
     struct {
         SemaphoreHandle_t event_sem;
         SemaphoreHandle_t mux_lock;
-        TimerHandle_t auto_suspend_timer;   // Freertos timer used for automatic suspend of the root port
-        usb_phy_handle_t phy_handle;        // Will be NULL if host library is installed with skip_phy_setup
-        void *enum_client;                  // Pointer to Enum driver (acting as a client). Used to reroute completed USBH control transfers
-        void *hub_client;                   // Pointer to External Hub driver (acting as a client). Used to reroute completed USBH control transfers. NULL, when External Hub Driver not available.
+        TimerHandle_t auto_suspend_timer;             // Freertos timer used for automatic suspend of the root port
+        usb_phy_handle_t phy_handles[HCD_NUM_PORTS];  // One per port; NULL if skip_phy_setup or port not enabled
+        void *enum_client;                            // Pointer to Enum driver (acting as a client). Used to reroute completed USBH control transfers
+        void *hub_client;                             // Pointer to External Hub driver (acting as a client). Used to reroute completed USBH control transfers. NULL, when External Hub Driver not available.
     } constant;
 } host_lib_t;
 
@@ -536,6 +536,23 @@ esp_err_t usb_host_install(const usb_host_config_t *config)
     HOST_CHECK_FROM_CRIT(p_host_lib_obj == NULL, ESP_ERR_INVALID_STATE);
     HOST_EXIT_CRITICAL();
 
+    // Validate configuration before any allocation (enables early return on invalid config)
+    const unsigned peripheral_map = config->peripheral_map == 0 ? (unsigned)BIT0 : config->peripheral_map;
+    const unsigned peripheral_map_max = (1U << SOC_USB_OTG_PERIPH_NUM) - 1;
+    if (peripheral_map > peripheral_map_max) {
+        ESP_LOGE(USB_HOST_TAG, "peripheral_map 0x%x exceeds maximum 0x%x", peripheral_map, peripheral_map_max);
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    const bool multi_port = (peripheral_map & (peripheral_map - 1)) != 0;
+    if (multi_port) {
+        if (config->fifo_settings_custom.rx_fifo_lines != 0 ||
+                config->fifo_settings_custom.nptx_fifo_lines != 0 ||
+                config->fifo_settings_custom.ptx_fifo_lines != 0) {
+            ESP_LOGW(USB_HOST_TAG, "Custom FIFO configuration is not supported for dual port applications; default FIFO will be used");
+        }
+    }
+
     esp_err_t ret;
     host_lib_t *host_lib_obj = heap_caps_calloc(1, sizeof(host_lib_t), MALLOC_CAP_DEFAULT);
     SemaphoreHandle_t event_sem = xSemaphoreCreateBinary();
@@ -560,35 +577,34 @@ esp_err_t usb_host_install(const usb_host_config_t *config)
     - Hub
     */
 
-    // For backward compatibility accept 0 too
-    const unsigned peripheral_map = config->peripheral_map == 0 ? BIT0 : config->peripheral_map;
+    // Initialize PHY handles to NULL
+    memset(host_lib_obj->constant.phy_handles, 0, sizeof(host_lib_obj->constant.phy_handles));
 
-    // Install USB PHY (if necessary). USB PHY driver will also enable the underlying Host Controller
+    // Install USB PHY for each enabled port (if not skip_phy_setup)
     if (!config->skip_phy_setup) {
-        bool init_utmi_phy = false; // Default value for Linux simulation
+        for (int i = 0; i < SOC_USB_OTG_PERIPH_NUM; i++) {
+            if (!(peripheral_map & BIT(i))) {
+                continue;
+            }
+            bool init_utmi_phy = false; // Default for Linux simulation / non-SOC builds
 
-#if SOC_USB_OTG_SUPPORTED // In case we run on a real target, select the PHY from usb_dwc_info description structure
-        // Right now we support only one peripheral, can be extended in future
-        int peripheral_index = 0;
-        if (peripheral_map & BIT1) {
-            peripheral_index = 1;
-        }
-        init_utmi_phy = (usb_dwc_info.controllers[peripheral_index].supported_phys == USB_PHY_INST_UTMI_0);
+#if SOC_USB_OTG_SUPPORTED
+            init_utmi_phy = (usb_dwc_info.controllers[i].supported_phys == USB_PHY_INST_UTMI_0);
 #endif // SOC_USB_OTG_SUPPORTED
 
-        // Host Library defaults to internal PHY
-        usb_phy_config_t phy_config = {
-            .controller = USB_PHY_CTRL_OTG,
-            .target = init_utmi_phy ? USB_PHY_TARGET_UTMI : USB_PHY_TARGET_INT,
-            .otg_mode = USB_OTG_MODE_HOST,
-            .otg_speed = USB_PHY_SPEED_UNDEFINED,   // In Host mode, the speed is determined by the connected device
-            .ext_io_conf = NULL,
-            .otg_io_conf = NULL,
-        };
-        ret = usb_new_phy(&phy_config, &host_lib_obj->constant.phy_handle);
-        if (ret != ESP_OK) {
-            ESP_LOGE(USB_HOST_TAG, "PHY install error: %s", esp_err_to_name(ret));
-            goto phy_err;
+            usb_phy_config_t phy_config = {
+                .controller = USB_PHY_CTRL_OTG,
+                .target = init_utmi_phy ? USB_PHY_TARGET_UTMI : USB_PHY_TARGET_INT,
+                .otg_mode = USB_OTG_MODE_HOST,
+                .otg_speed = USB_PHY_SPEED_UNDEFINED,
+                .ext_io_conf = NULL,
+                .otg_io_conf = NULL,
+            };
+            ret = usb_new_phy(&phy_config, &host_lib_obj->constant.phy_handles[i]);
+            if (ret != ESP_OK) {
+                ESP_LOGE(USB_HOST_TAG, "PHY install error for port %d: %s", i, esp_err_to_name(ret));
+                goto phy_err;
+            }
         }
     }
 
@@ -633,11 +649,12 @@ esp_err_t usb_host_install(const usb_host_config_t *config)
         .fifo_config = NULL,
     };
 
-    // Check if user has provided a custom FIFO configuration
+    // Check if user has provided a custom FIFO configuration (not used for multi-port)
     hcd_fifo_settings_t user_fifo_config;
-    if (config->fifo_settings_custom.rx_fifo_lines != 0 ||
-            config->fifo_settings_custom.nptx_fifo_lines != 0 ||
-            config->fifo_settings_custom.ptx_fifo_lines != 0) {
+    if (!multi_port &&
+            (config->fifo_settings_custom.rx_fifo_lines != 0 ||
+             config->fifo_settings_custom.nptx_fifo_lines != 0 ||
+             config->fifo_settings_custom.ptx_fifo_lines != 0)) {
 
         // Populate user FIFO configuration with provided values
         user_fifo_config.rx_fifo_lines = config->fifo_settings_custom.rx_fifo_lines;
@@ -678,11 +695,13 @@ esp_err_t usb_host_install(const usb_host_config_t *config)
     ESP_ERROR_CHECK(enum_uninstall());
 enum_err:
     ESP_ERROR_CHECK(usbh_uninstall());
+phy_err:
 usbh_err:
-    if (host_lib_obj->constant.phy_handle) {
-        ESP_ERROR_CHECK(usb_del_phy(host_lib_obj->constant.phy_handle));
+    for (int i = 0; i < HCD_NUM_PORTS; i++) {
+        if (host_lib_obj->constant.phy_handles[i] != NULL) {
+            ESP_ERROR_CHECK(usb_del_phy(host_lib_obj->constant.phy_handles[i]));
+        }
     }
-phy_err:
 alloc_err:
     if (mux_lock) {
         vSemaphoreDelete(mux_lock);
@@ -728,9 +747,11 @@ esp_err_t usb_host_uninstall(void)
     ESP_ERROR_CHECK(hub_uninstall());
     ESP_ERROR_CHECK(enum_uninstall());
     ESP_ERROR_CHECK(usbh_uninstall());
-    // If the USB PHY was setup, then delete it
-    if (host_lib_obj->constant.phy_handle) {
-        ESP_ERROR_CHECK(usb_del_phy(host_lib_obj->constant.phy_handle));
+    // Delete all PHYs that were created
+    for (int i = 0; i < HCD_NUM_PORTS; i++) {
+        if (host_lib_obj->constant.phy_handles[i] != NULL) {
+            ESP_ERROR_CHECK(usb_del_phy(host_lib_obj->constant.phy_handles[i]));
+        }
     }
 
     // Free memory objects