refactor(uvc): Refactor UVC stream opening operations

Refactor UVC stream opening operations to following order:
1. Find and open underlaying USB device (and cache CFG descriptor)
2. Find interface number for requested format: bInterfaceNumber is needed for Control transfers during format negotiation
3. Negotiate the format: negotiated result is needed for correct size of frame buffers and for selecting of bandwidth in ISOC cameras
4. Allocate the frame buffers
5. Find the interface endpoint that fits our requirements and claim it: the endpoint descriptor is needed for proper USB transfer allocation
6. Allocate the USB transfer

Author: tore-espressif

host/class/uvc/usb_host_uvc/private_include/uvc_descriptors_priv.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -38,9 +38,8 @@ esp_err_t uvc_desc_get_streaming_interface_num(
 /**
  * @brief Get Streaming Interface and Endpoint descriptors
  *
- * We go through all alternate interfaces and pick the one that offers endpoint with MPS that:
- * * Is lower than or equal to dwMaxPayloadTransferSize
- * * Has as few as possible extra transactions per microframe (HS only)
+ * We go through all alternate interfaces and pick the one that offers endpoint with MPS
+ * that is lower than or equal to dwMaxPayloadTransferSize
  *
  * @note The caller is responsible for dwMaxPayloadTransferSize fitting in the IN FIFO
  *

host/class/uvc/usb_host_uvc/private_include/uvc_frame_priv.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -19,10 +19,13 @@ extern "C" {
 /**
  * @brief Allocate frame buffers for UVC stream
  *
+ * In case fb_size is 0, format negotiation (probe) must be done before calling this function,
+ * because the frame size is taken from the negotiated format.
+ *
  * @param[in] uvc_stream UVC stream handle
  * @param[in] nb_of_fb   Number of frame buffers to allocate
- * @param[in] fb_size    Size of 1 frame buffer in bytes
- * @param[in] fb_caps    Memory capabilities of memory for frame buffers
+ * @param[in] fb_size    Size of 1 frame buffer in bytes, can be 0 for default
+ * @param[in] fb_caps    Memory capabilities of memory for frame buffers, can be 0 for MALLOC_CAP_DEFAULT
  * @param[in] user_frame_buffers Optional user-provided frame buffers. If not NULL, use these instead of allocating
  * @return
  *     - ESP_OK: Success

host/class/uvc/usb_host_uvc/private_include/uvc_idf_version_priv.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -11,7 +11,7 @@
 
 // @todo fix the hard-coded number here: Should be taken from HAL FIFO config in future versions of esp-idf
 #if (CONFIG_IDF_TARGET_ESP32P4 || CONFIG_IDF_TARGET_LINUX)
-#define MAX_MPS_IN 4096
+#define MAX_MPS_IN 4096 // Theoretically maximum 3 isochronous transaction per microframe, 3072 bytes
 #else
 // If FIFO is configured for bias IN, we have 608 bytes available.
 // However, configuring MPS > 596 causes USB transfer failures,

host/class/uvc/usb_host_uvc/private_include/uvc_types_priv.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -44,6 +44,7 @@ struct uvc_host_stream_s {
         uint8_t  bInterfaceNumber;            // USB Video Streaming interface claimed by this stream. Needed for ISOC Stream start and CTRL transfers
         uint8_t  bAlternateSetting;           // Alternate setting for selected interface. Needed for ISOC Stream start
         uint8_t  bEndpointAddress;            // Streaming endpoint address. Needed for BULK Stream stop
+        const usb_config_desc_t *cfg_desc;    // Configuration descriptor of the device. Cached for faster access
 
         // USB host related members
         usb_device_handle_t dev_hdl;          // USB device handle

host/class/uvc/usb_host_uvc/uvc_control.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -37,8 +37,6 @@ static esp_err_t uvc_host_stream_control(uvc_host_stream_hdl_t stream_hdl, uvc_v
     uvc_stream_t *uvc_stream = (uvc_stream_t *)stream_hdl;
     uint8_t bmRequestType, bRequest;
     uint16_t wValue, wIndex, wLength;
-    const usb_config_desc_t *cfg_desc;
-    ESP_ERROR_CHECK(usb_host_get_active_config_descriptor(uvc_stream->constant.dev_hdl, &cfg_desc));
     esp_err_t ret = ESP_OK;
     const bool set = (req_code == UVC_SET_CUR) ? true : false;
 
@@ -56,7 +54,7 @@ static esp_err_t uvc_host_stream_control(uvc_host_stream_hdl_t stream_hdl, uvc_v
         const uvc_frame_desc_t *frame_desc;
 
         ESP_RETURN_ON_ERROR(
-            uvc_desc_get_frame_format_by_format(cfg_desc, uvc_stream->constant.bInterfaceNumber, vs_format, &format_desc, &frame_desc),
+            uvc_desc_get_frame_format_by_format(uvc_stream->constant.cfg_desc, uvc_stream->constant.bInterfaceNumber, vs_format, &format_desc, &frame_desc),
             TAG, "Could not find format that matches required format");
         UVC_CHECK(format_desc && frame_desc, ESP_ERR_NOT_FOUND);
 
@@ -92,7 +90,7 @@ static esp_err_t uvc_host_stream_control(uvc_host_stream_hdl_t stream_hdl, uvc_v
         const uvc_format_desc_t *format_desc = NULL;
         const uvc_frame_desc_t *frame_desc = NULL;
         ESP_RETURN_ON_ERROR(
-            uvc_desc_get_frame_format_by_index(cfg_desc, uvc_stream->constant.bInterfaceNumber, vs_control->bFormatIndex, vs_control->bFrameIndex, &format_desc, &frame_desc),
+            uvc_desc_get_frame_format_by_index(uvc_stream->constant.cfg_desc, uvc_stream->constant.bInterfaceNumber, vs_control->bFormatIndex, vs_control->bFrameIndex, &format_desc, &frame_desc),
             TAG, "Could not find requested frame format");
 
         vs_format->format = uvc_desc_parse_format(format_desc);

host/class/uvc/usb_host_uvc/uvc_descriptor_parsing.c

@@ -73,6 +73,10 @@ esp_err_t uvc_desc_get_streaming_intf_and_ep(
     const uint8_t num_of_alternate = usb_parse_interface_number_of_alternate(cfg_desc, bInterfaceNumber);
     uint16_t last_mps = 0; // Looking for maximum MPS: init to zero
     uint8_t last_mult = UINT8_MAX; // Looking for minimum: init to max
+
+    /* Number of alternate interfaces will be 0 for BULK cameras
+     * that is why in the for loop below we go from 0 to num_of_alternate **inclusive**
+     */
     for (int i = 0; i <= num_of_alternate; i++) {
         // Check Interface desc
         intf_desc = usb_parse_interface_descriptor(cfg_desc, bInterfaceNumber, i, &offset);

host/class/uvc/usb_host_uvc/uvc_descriptor_printing.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -368,11 +368,9 @@ void uvc_host_desc_print(uvc_host_stream_hdl_t stream_hdl)
 {
     assert(stream_hdl);
     uvc_stream_t *uvc_stream = (uvc_stream_t *)stream_hdl;
-
     const usb_device_desc_t *device_desc;
-    const usb_config_desc_t *config_desc;
+
     ESP_ERROR_CHECK_WITHOUT_ABORT(usb_host_get_device_descriptor(uvc_stream->constant.dev_hdl, &device_desc));
-    ESP_ERROR_CHECK_WITHOUT_ABORT(usb_host_get_active_config_descriptor(uvc_stream->constant.dev_hdl, &config_desc));
     usb_print_device_descriptor(device_desc);
-    usb_print_config_descriptor(config_desc, &uvc_print_desc);
+    usb_print_config_descriptor(uvc_stream->constant.cfg_desc, &uvc_print_desc);
 }

host/class/uvc/usb_host_uvc/uvc_frame.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -15,6 +15,7 @@
 #include "uvc_frame_priv.h"
 #include "uvc_types_priv.h"
 #include "uvc_check_priv.h"
+#include "uvc_critical_priv.h"
 
 #include "freertos/FreeRTOS.h"
 #include "freertos/queue.h"
@@ -58,10 +59,14 @@ esp_err_t uvc_frame_allocate(uvc_stream_t *uvc_stream, int nb_of_fb, size_t fb_s
             // Use user-provided buffer (already validated in uvc_host_stream_open)
             this_data = user_frame_buffers[i];
         } else {
-            // Allocate driver-managed buffer
+            // In case the user did not fill the config, set it to default
+            if (fb_size == 0) {
+                fb_size = UVC_ATOMIC_LOAD(uvc_stream->dynamic.dwMaxVideoFrameSize);
+            }
             if (fb_caps == 0) {
                 fb_caps = MALLOC_CAP_DEFAULT; // In case the user did not fill the config, set it to default
             }
+            // Allocate driver-managed buffer
             this_data = heap_caps_malloc(fb_size, fb_caps);
             if (this_data == NULL) {
                 free(this_fb);