Merge branch 'feature/usb_host_multi_configuration' into 'master'

USB Host multiconfiguration support pt1 (getting the configuration descriptor)

Closes IDFGH-11532 and IDF-8732

See merge request espressif/esp-idf!26760

components/usb/include/usb/usb_host.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -346,6 +346,35 @@ esp_err_t usb_host_get_device_descriptor(usb_device_handle_t dev_hdl, const usb_
  */
 esp_err_t usb_host_get_active_config_descriptor(usb_device_handle_t dev_hdl, const usb_config_desc_t **config_desc);
 
+/**
+ * @brief Get get device's configuration descriptor
+ *
+ * - The USB Host library only caches a device's active configuration descriptor.
+ * - This function reads any configuration descriptor of a particular device (specified by bConfigurationValue).
+ * - This function will read the specified configuration descriptor via control transfers, and allocate memory to store that descriptor.
+ * - Users can call usb_host_get_config_desc_free() to free the descriptor's memory afterwards.
+ *
+ * @note This function can block
+ * @note A client must call usb_host_device_open() on the device first
+ * @param[in] client_hdl Client handle - usb_host_client_handle_events() should be called repeatedly in a separate task to handle client events
+ * @param[in] dev_hdl Device handle
+ * @param[out] config_desc_ret Returned configuration descriptor
+ * @param[in] bConfigurationValue Index of device's configuration descriptor to be read
+ * @note bConfigurationValue starts from index 1
+ * @return esp_err_t
+ */
+esp_err_t usb_host_get_config_desc(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, uint8_t bConfigurationValue, const usb_config_desc_t **config_desc_ret);
+
+/**
+ * @brief Free a configuration descriptor
+ *
+ * This function frees a configuration descriptor that was returned by usb_host_get_config_desc()
+ *
+ * @param[out] config_desc Configuration descriptor
+ * @return esp_err_t
+ */
+esp_err_t usb_host_get_config_desc_free(const usb_config_desc_t *config_desc);
+
 // ----------------------------------------------- Interface Functions -------------------------------------------------
 
 /**

components/usb/test_apps/usb_host/main/multiconf_client.h

@@ -0,0 +1,22 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdint.h>
+
+typedef struct {
+    SemaphoreHandle_t dev_open_smp;
+    uint8_t bConfigurationValue;
+} multiconf_client_test_param_t;
+
+/**
+ * @brief Multiconfiguration client task
+ */
+void multiconf_client_async_task(void *arg);
+
+/**
+ * @brief Get configuration descriptor
+ */
+void multiconf_client_get_conf_desc(void);

components/usb/test_apps/usb_host/main/multiconf_client_async.c

@@ -0,0 +1,179 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdint.h>
+#include <string.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+#include "esp_err.h"
+#include "esp_log.h"
+#include "test_usb_common.h"
+#include "multiconf_client.h"
+#include "mock_msc.h"
+#include "dev_msc.h"
+#include "usb/usb_host.h"
+#include "unity.h"
+
+/*
+Implementation of a multi-configuration client used for USB Host Tests.
+
+- The multi-configuration client will:
+    - Register itself as a client
+    - Receive USB_HOST_CLIENT_EVENT_NEW_DEV event message, and open the device
+    - Get active configuration descriptor
+    - Start handling client events
+    - Wait for a request from main task to read a configuration descriptor
+    - Compare the obtained configuration descriptor with the active configuration descriptor
+    - Free the memory used for storing the configuration descriptor
+    - Close the device
+    - Deregister control client
+*/
+
+const char *MULTICONF_CLIENT_TAG = "Multi config Client";
+
+#define CLIENT_NUM_EVENT_MSG        5
+
+typedef enum {
+    TEST_STAGE_WAIT_CONN,
+    TEST_STAGE_DEV_OPEN,
+    TEST_STAGE_WAIT,
+    TEST_STAGE_CHECK_CONFIG_DESC,
+    TEST_STAGE_DEV_CLOSE,
+} test_stage_t;
+
+typedef struct {
+    // Test parameters
+    multiconf_client_test_param_t test_param;
+    // device info
+    uint8_t dev_addr;
+    usb_speed_t dev_speed;
+    // Client variables
+    usb_host_client_handle_t client_hdl;
+    usb_device_handle_t dev_hdl;
+    // Test state
+    test_stage_t cur_stage;
+    test_stage_t next_stage;
+    const usb_config_desc_t *config_desc_cached;
+} multiconf_client_obj_t;
+
+static multiconf_client_obj_t *s_multiconf_obj;
+
+static void multiconf_client_event_cb(const usb_host_client_event_msg_t *event_msg, void *arg)
+{
+    multiconf_client_obj_t *multiconf_obj = (multiconf_client_obj_t *)arg;
+    switch (event_msg->event) {
+    case USB_HOST_CLIENT_EVENT_NEW_DEV:
+        TEST_ASSERT_EQUAL(TEST_STAGE_WAIT_CONN, multiconf_obj->cur_stage);
+        multiconf_obj->next_stage = TEST_STAGE_DEV_OPEN;
+        multiconf_obj->dev_addr = event_msg->new_dev.address;
+        break;
+    default:
+        abort();    // Should never occur in this test
+        break;
+    }
+}
+
+void multiconf_client_async_task(void *arg)
+{
+    multiconf_client_obj_t multiconf_obj;
+    // Initialize test params
+    memcpy(&multiconf_obj.test_param, arg, sizeof(multiconf_client_test_param_t));
+    // Initialize client variables
+    multiconf_obj.client_hdl = NULL;
+    multiconf_obj.dev_hdl = NULL;
+    // Initialize test stage
+    multiconf_obj.cur_stage = TEST_STAGE_WAIT_CONN;
+    multiconf_obj.next_stage = TEST_STAGE_WAIT_CONN;
+    multiconf_obj.dev_addr = 0;
+
+    // Register client
+    usb_host_client_config_t client_config = {
+        .is_synchronous = false,
+        .max_num_event_msg = CLIENT_NUM_EVENT_MSG,
+        .async = {
+            .client_event_callback = multiconf_client_event_cb,
+            .callback_arg = (void *) &multiconf_obj,
+        },
+    };
+    TEST_ASSERT_EQUAL(ESP_OK, usb_host_client_register(&client_config, &multiconf_obj.client_hdl));
+    s_multiconf_obj = &multiconf_obj;
+
+    // Wait to be started by main thread
+    ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
+    ESP_LOGD(MULTICONF_CLIENT_TAG, "Starting");
+
+    bool exit_loop = false;
+    bool skip_event_handling = false;
+    while (!exit_loop) {
+        if (!skip_event_handling) {
+            TEST_ASSERT_EQUAL(ESP_OK, usb_host_client_handle_events(multiconf_obj.client_hdl, portMAX_DELAY));
+        }
+        skip_event_handling = false;
+        if (multiconf_obj.cur_stage == multiconf_obj.next_stage) {
+            continue;
+        }
+        multiconf_obj.cur_stage = multiconf_obj.next_stage;
+
+        switch (multiconf_obj.next_stage) {
+        case TEST_STAGE_DEV_OPEN: {
+            ESP_LOGD(MULTICONF_CLIENT_TAG, "Open");
+            // Open the device
+            TEST_ASSERT_EQUAL_MESSAGE(ESP_OK, usb_host_device_open(multiconf_obj.client_hdl, multiconf_obj.dev_addr, &multiconf_obj.dev_hdl), "Failed to open the device");
+
+            // Get device info to get it's speed
+            usb_device_info_t dev_info;
+            TEST_ASSERT_EQUAL(ESP_OK, usb_host_device_info(multiconf_obj.dev_hdl, &dev_info));
+            multiconf_obj.dev_speed = dev_info.speed;
+
+            multiconf_obj.next_stage = TEST_STAGE_WAIT;
+            skip_event_handling = true;
+            break;
+        }
+        case TEST_STAGE_WAIT: {
+            // Give semaphore signalizing that the device has been opened
+            xSemaphoreGive(multiconf_obj.test_param.dev_open_smp);
+            break;
+        }
+        case TEST_STAGE_CHECK_CONFIG_DESC: {
+            ESP_LOGD(MULTICONF_CLIENT_TAG, "Check config descriptors");
+            // Get mocked config descriptor
+            const usb_config_desc_t *config_desc_ref = dev_msc_get_config_desc(multiconf_obj.dev_speed);
+            TEST_ASSERT_EQUAL_MESSAGE(multiconf_obj.config_desc_cached->wTotalLength, config_desc_ref->wTotalLength, "Incorrect length of CFG descriptor");
+            TEST_ASSERT_EQUAL_MEMORY_MESSAGE(config_desc_ref, multiconf_obj.config_desc_cached, sizeof(usb_config_desc_t), "Configuration descriptors do not match");
+
+            // Free the memory used to store the config descriptor
+            TEST_ASSERT_EQUAL(ESP_OK, usb_host_get_config_desc_free(multiconf_obj.config_desc_cached));
+            multiconf_obj.next_stage = TEST_STAGE_DEV_CLOSE;
+            skip_event_handling = true;
+            break;
+        }
+        case TEST_STAGE_DEV_CLOSE: {
+            ESP_LOGD(MULTICONF_CLIENT_TAG, "Close");
+            vTaskDelay(10); // Give USB Host Lib some time to process all transfers
+            TEST_ASSERT_EQUAL(ESP_OK, usb_host_device_close(multiconf_obj.client_hdl, multiconf_obj.dev_hdl));
+            exit_loop = true;
+            break;
+        }
+        default:
+            abort();
+            break;
+        }
+    }
+    TEST_ASSERT_EQUAL(ESP_OK, usb_host_client_deregister(multiconf_obj.client_hdl));
+    ESP_LOGD(MULTICONF_CLIENT_TAG, "Done");
+    vTaskDelete(NULL);
+}
+
+void multiconf_client_get_conf_desc(void)
+{
+    // Get configuration descriptor, ctrl transfer is sent to the device to get the config descriptor
+    TEST_ASSERT_EQUAL(ESP_OK, usb_host_get_config_desc(s_multiconf_obj->client_hdl, s_multiconf_obj->dev_hdl, s_multiconf_obj->test_param.bConfigurationValue, &s_multiconf_obj->config_desc_cached));
+
+    // Go to next stage
+    s_multiconf_obj->next_stage = TEST_STAGE_CHECK_CONFIG_DESC;
+    ESP_ERROR_CHECK(usb_host_client_unblock(s_multiconf_obj->client_hdl));
+}

components/usb/test_apps/usb_host/main/test_app_main.c

@@ -33,6 +33,8 @@ void tearDown(void)
     vTaskDelay(10);
     // Clean up USB Host
     ESP_ERROR_CHECK(usb_host_uninstall());
+    // Short delay to allow task to be cleaned up after client uninstall
+    vTaskDelay(10);
     test_usb_deinit_phy();  // Deinitialize the internal USB PHY after testing
     unity_utils_evaluate_leaks();
 }

components/usb/test_apps/usb_host/main/test_usb_host_async.c

@@ -14,13 +14,15 @@
 #include "dev_msc.h"
 #include "msc_client.h"
 #include "ctrl_client.h"
+#include "multiconf_client.h"
 #include "usb/usb_host.h"
 #include "unity.h"
 
 #define TEST_MSC_NUM_SECTORS_TOTAL          10
 #define TEST_MSC_NUM_SECTORS_PER_XFER       2
 #define TEST_MSC_SCSI_TAG                   0xDEADBEEF
 #define TEST_CTRL_NUM_TRANSFERS             30
+#define B_CONFIGURATION_VALUE               1
 
 // --------------------------------------------------- Test Cases ------------------------------------------------------
 
@@ -275,3 +277,66 @@ TEST_CASE("Test USB Host async API", "[usb_host][full_speed][low_speed]")
         vTaskDelay(10);
     }
 }
+
+/*
+Test USB Host Asynchronous API single client
+
+Purpose:
+    - Test that client can read configuration descriptor by request
+
+Procedure:
+    - Install USB Host Library
+    - Create a task to run a multiconfig client
+    - Create a task to handle system events
+    - Start the MSC client task. It will open the device and start handling client events
+    - Wait for the main task requests client to read configuration descriptor
+    - Compare the requested configuration descriptor with the active configuration descriptor
+    - Wait for the host library event handler to report a USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS event
+    - Free all devices
+    - Uninstall USB Host Library
+*/
+static void host_lib_task(void *arg)
+{
+    while (1) {
+        // Start handling system events
+        uint32_t event_flags;
+        usb_host_lib_handle_events(portMAX_DELAY, &event_flags);
+        if (event_flags & USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS) {
+            printf("No more clients\n");
+            TEST_ASSERT_EQUAL(ESP_ERR_NOT_FINISHED, usb_host_device_free_all());
+        }
+        if (event_flags & USB_HOST_LIB_EVENT_FLAGS_ALL_FREE) {
+            break;
+        }
+    }
+
+    printf("Deleting host_lib_task\n");
+    vTaskDelete(NULL);
+}
+
+TEST_CASE("Test USB Host multiconfig client (single client)", "[usb_host][full_speed][high_speed]")
+{
+    SemaphoreHandle_t dev_open_smp = xSemaphoreCreateBinary();
+    TaskHandle_t client_task;
+
+    multiconf_client_test_param_t multiconf_params = {
+        .dev_open_smp = dev_open_smp,
+        .bConfigurationValue = B_CONFIGURATION_VALUE,
+    };
+
+    xTaskCreatePinnedToCore(multiconf_client_async_task, "async client", 4096, (void*)&multiconf_params, 2, &client_task, 0);
+    TEST_ASSERT_NOT_NULL_MESSAGE(client_task, "Failed to create async client task");
+    // Start the task
+    xTaskNotifyGive(client_task);
+
+    TaskHandle_t host_lib_task_hdl;
+    xTaskCreatePinnedToCore(host_lib_task, "host lib", 4096, NULL, 2, &host_lib_task_hdl, 0);
+    TEST_ASSERT_NOT_NULL_MESSAGE(host_lib_task_hdl, "Failed to create host lib task");
+
+    // Wait for the device to be open
+    xSemaphoreTake(dev_open_smp, portMAX_DELAY);
+    multiconf_client_get_conf_desc();
+
+    // Cleanup
+    vSemaphoreDelete(dev_open_smp);
+}