Merge branch 'feature/usb_host_ext_hub_error_handle' into 'master'

roma-jam · roma-jam · commit d7222cc89ea1 · 2025-02-25T17:18:46.000+08:00
feat(ext_hub): Added device error handling Closes IDF-10057 Closes #15437 See merge request espressif/esp-idf!33956
diff --git a/Kconfig b/Kconfig
@@ -702,6 +702,5 @@ mainmenu "Espressif IoT Development Framework Configuration"
             - CONFIG_BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH
             - CONFIG_ESP_WIFI_EAP_TLS1_3
             - CONFIG_ESP_WIFI_ENABLE_ROAMING_APP
-            - CONFIG_USB_HOST_EXT_PORT_SUPPORT_LS
             - CONFIG_USB_HOST_EXT_PORT_RESET_ATTEMPTS
             - CONFIG_LIBC_PICOLIBC
diff --git a/components/usb/Kconfig b/components/usb/Kconfig
@@ -115,13 +115,6 @@ menu "USB-OTG"
         menu "Downstream Port configuration"
             depends on USB_HOST_HUBS_SUPPORTED
 
-            config USB_HOST_EXT_PORT_SUPPORT_LS
-                depends on IDF_EXPERIMENTAL_FEATURES
-                bool "Support LS"
-                default n
-                help
-                    Enables support of Low-speed devices, connected through the external Hub.
-
             config USB_HOST_EXT_PORT_RESET_ATTEMPTS
                 depends on IDF_EXPERIMENTAL_FEATURES
                 # Invisible config option
diff --git a/components/usb/ext_hub.c b/components/usb/ext_hub.c
diff --git a/components/usb/hub.c b/components/usb/hub.c
@@ -351,16 +351,6 @@ static void ext_port_event_callback(ext_port_event_data_t *event_data, void *arg
             }
         }
 
-#if (!CONFIG_USB_HOST_EXT_PORT_SUPPORT_LS)
-        if (port_speed == USB_SPEED_LOW) {
-            ESP_LOGE(HUB_DRIVER_TAG, "Connected %s-speed device, not supported",
-            (char *[]) {
-                "Low", "Full", "High"
-            }[port_speed]);
-            goto new_ds_dev_err;
-        }
-#endif // CONFIG_USB_HOST_EXT_PORT_SUPPORT_LS
-
         if (dev_tree_node_new(event_data->connected.parent_dev_hdl, event_data->connected.parent_port_num, port_speed) != ESP_OK) {
             ESP_LOGE(HUB_DRIVER_TAG, "Failed to add new downstream device");
             goto new_ds_dev_err;
diff --git a/components/usb/private_include/ext_hub.h b/components/usb/private_include/ext_hub.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -127,7 +127,7 @@ esp_err_t ext_hub_get_handle(usb_device_handle_t dev_hdl, ext_hub_handle_t *ext_
  *
  * @return
  *    - ESP_OK: New device added successfully
- *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed, or not in correct state to add a new device
+ *    - ESP_ERR_NOT_ALLOWED: External Hub driver is not installed
  */
 esp_err_t ext_hub_new_dev(uint8_t dev_addr);
 
@@ -141,7 +141,7 @@ esp_err_t ext_hub_new_dev(uint8_t dev_addr);
  *
  * @return
  *    - ESP_OK: Device freed successfully
- *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_NOT_ALLOWED: External Hub driver is not installed
  *    - ESP_ERR_INVALID_ARG: Invalid argument
  *    - ESP_ERR_NOT_FOUND: Device address not found
  */
@@ -182,7 +182,7 @@ esp_err_t ext_hub_status_handle_complete(ext_hub_handle_t ext_hub_hdl);
  *
  * @return
  *    - ESP_OK: All events handled
- *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_NOT_ALLOWED: External Hub driver is not installed
  */
 esp_err_t ext_hub_process(void);
 
@@ -199,10 +199,11 @@ esp_err_t ext_hub_process(void);
  *
  * @return
  *    - ESP_OK: The port can be recycled
- *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_NOT_ALLOWED: External Hub driver is not installed
  *    - ESP_ERR_INVALID_ARG: Invalid argument
  *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
  *    - ESP_ERR_NOT_SUPPORTED: External Port Driver has not been installed
+ *    - ESP_ERR_INVALID_STATE: External Hub wasn't configured or suspended
  */
 esp_err_t ext_hub_port_recycle(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
 
@@ -214,7 +215,7 @@ esp_err_t ext_hub_port_recycle(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
  *
  * @return
  *    - ESP_OK: The port can be reset
- *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_NOT_ALLOWED: External Hub driver is not installed
  *    - ESP_ERR_INVALID_ARG: Invalid argument
  *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
  *    - ESP_ERR_NOT_SUPPORTED: External Port Driver has not been installed
@@ -229,7 +230,7 @@ esp_err_t ext_hub_port_reset(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
  *
  * @return
  *    - ESP_OK: Device on the External hub's port has been enumerated
- *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_NOT_ALLOWED: External Hub driver is not installed
  *    - ESP_ERR_INVALID_ARG: Invalid argument
  *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
  *    - ESP_ERR_NOT_SUPPORTED: External Port Driver has not been installed
@@ -244,10 +245,11 @@ esp_err_t ext_hub_port_active(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
  *
  * @return
  *    - ESP_OK: Device on the External hub's port can be disabled
- *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_NOT_ALLOWED: External Hub driver is not installed
  *    - ESP_ERR_INVALID_ARG: Invalid argument
  *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
  *    - ESP_ERR_NOT_SUPPORTED: External Port Driver has not been installed
+ *    - ESP_ERR_INVALID_STATE: External Hub wasn't configured or suspended
  */
 esp_err_t ext_hub_port_disable(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
 
@@ -260,10 +262,11 @@ esp_err_t ext_hub_port_disable(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
  *
  * @return
  *    - ESP_OK: The device's speed obtained successfully
- *    - ESP_ERR_INVALID_STATE: External Hub driver is not installed
+ *    - ESP_ERR_NOT_ALLOWED: External Hub driver is not installed
  *    - ESP_ERR_INVALID_ARG: Invalid argument
  *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
  *    - ESP_ERR_NOT_SUPPORTED: External Port Driver has not been installed
+ *    - ESP_ERR_INVALID_STATE: External Hub wasn't configured or suspended
  */
 esp_err_t ext_hub_port_get_speed(ext_hub_handle_t ext_hub_hdl, uint8_t port_num, usb_speed_t *speed);
 
@@ -281,6 +284,7 @@ esp_err_t ext_hub_port_get_speed(ext_hub_handle_t ext_hub_hdl, uint8_t port_num,
  *    - ESP_ERR_NOT_ALLOWED: External Hub driver is not installed
  *    - ESP_ERR_INVALID_ARG: Invalid argument
  *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
+ *    - ESP_ERR_INVALID_STATE: External Hub is not configured or suspended
  */
 esp_err_t ext_hub_set_port_feature(ext_hub_handle_t ext_hub_hdl, uint8_t port_num, uint8_t feature);
 
@@ -296,6 +300,7 @@ esp_err_t ext_hub_set_port_feature(ext_hub_handle_t ext_hub_hdl, uint8_t port_nu
  *    - ESP_ERR_NOT_ALLOWED: External Hub driver is not installed
  *    - ESP_ERR_INVALID_ARG: Invalid argument
  *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
+ *    - ESP_ERR_INVALID_STATE: External Hub is not configured or suspended
  */
 esp_err_t ext_hub_clear_port_feature(ext_hub_handle_t ext_hub_hdl, uint8_t port_num, uint8_t feature);
 
@@ -313,6 +318,7 @@ esp_err_t ext_hub_clear_port_feature(ext_hub_handle_t ext_hub_hdl, uint8_t port_
  *    - ESP_ERR_NOT_ALLOWED: External Hub driver is not installed
  *    - ESP_ERR_INVALID_ARG: Invalid argument
  *    - ESP_ERR_INVALID_SIZE: External Hub port number out of the hub's range
+ *    - ESP_ERR_INVALID_STATE: External Hub is not configured or suspended
  */
 esp_err_t ext_hub_get_port_status(ext_hub_handle_t ext_hub_hdl, uint8_t port_num);
 
diff --git a/docs/en/api-reference/peripherals/usb_host.rst b/docs/en/api-reference/peripherals/usb_host.rst
@@ -45,7 +45,6 @@ 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.
     :esp32p4: - {IDF_TARGET_NAME} contains two USB-OTG peripherals USB 2.0 OTG High-Speed and USB 2.0 OTG Full-Speed. Only the High-Speed instance is supported now.
-    - The External Hub Driver: Supports only devices with the same speed as upstream port speed (e.g., Low-speed device won't work through Full-speed external Hub).
     - 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).
diff --git a/docs/zh_CN/api-reference/peripherals/usb_host.rst b/docs/zh_CN/api-reference/peripherals/usb_host.rst
@@ -45,7 +45,6 @@ USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供
     - 仅支持使用发现的首个配置，尚不支持变更为其他配置。
     - 尚不支持传输超时。
     :esp32p4: - {IDF_TARGET_NAME} 包含两个 USB-OTG 外设：USB 2.0 OTG 高速和 USB 2.0 OTG 全速。目前仅支持高速实例。
-    - 外部 Hub 驱动：仅支持与上游端口速率相同的设备。（例如，低速设备无法通过全速外部 Hub 工作。）
     - 外部 Hub 驱动：不支持远程唤醒功能（即使没有设备插入，外部 Hub 也处于工作状态）。
     - 外部 Hub 驱动：不处理错误用例（尚未实现过流处理、初始化错误等功能）。
     - 外部 Hub 驱动：不支持接口选择。驱动程序使用具有 Hub 类代码 (09h) 的第一个可用接口。
