feat(usb_host_uvc): add support for user-provided frame buffers

Author: leeebo

host/class/uvc/usb_host_uvc/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.4.0
+
+- Added support for user-provided frame buffers via `user_frame_buffers` field in `uvc_host_stream_config_t.advanced`
+- Fixed assertion failure when receiving packets with unexpected `frame_id`
+
 ## 2.3.1
 
 - Added support for ESP32-H4

host/class/uvc/usb_host_uvc/host_test/main/streaming/test_streaming.cpp

@@ -69,7 +69,7 @@ void run_streaming_frame_reconstruction_scenario(void)
                 return true;
             };
 
-            REQUIRE(uvc_frame_allocate(&stream, 1, 100 * 1024, 0) == ESP_OK);
+            REQUIRE(uvc_frame_allocate(&stream, 1, 100 * 1024, 0, NULL) == ESP_OK);
             uvc_frame_format_update(&stream, &logo_jpg_format);
 
             // Test
@@ -147,7 +147,7 @@ void run_streaming_frame_reconstruction_scenario(void)
                 enum uvc_host_dev_event *event_type = static_cast<enum uvc_host_dev_event *>(user_ctx);
                 *event_type = event->type;
             };
-            REQUIRE(uvc_frame_allocate(&stream, 1, logo_jpg.size() - 100, 0) == ESP_OK);
+            REQUIRE(uvc_frame_allocate(&stream, 1, logo_jpg.size() - 100, 0, NULL) == ESP_OK);
 
             WHEN("The frame is too big") {
                 send_function_wrapper(1024, &stream, std::span(logo_jpg));
@@ -170,7 +170,7 @@ void run_streaming_frame_reconstruction_scenario(void)
             };
 
             uvc_host_frame_t *temp_frame = nullptr;
-            REQUIRE(uvc_frame_allocate(&stream, 1, 100 * 1024, 0) == ESP_OK);
+            REQUIRE(uvc_frame_allocate(&stream, 1, 100 * 1024, 0, NULL) == ESP_OK);
             temp_frame = uvc_frame_get_empty(&stream);
             REQUIRE(temp_frame != nullptr);
 
@@ -236,7 +236,7 @@ SCENARIO("Bulk stream frame reconstruction", "[streaming][bulk]")
 
     GIVEN("Streaming enabled and frame allocated") {
         REQUIRE(uvc_host_stream_unpause(&stream) == ESP_OK);
-        REQUIRE(uvc_frame_allocate(&stream, 1, 100 * 1024, 0) == ESP_OK);
+        REQUIRE(uvc_frame_allocate(&stream, 1, 100 * 1024, 0, NULL) == ESP_OK);
         uvc_frame_format_update(&stream, &logo_jpg_format);
 
         WHEN("Expected SoF but got EoF") {

host/class/uvc/usb_host_uvc/idf_component.yml

@@ -1,5 +1,5 @@
 ## IDF Component Manager Manifest File
-version: "2.3.1"
+version: "2.4.0"
 description: USB Host UVC driver
 url: https://github.com/espressif/esp-usb/tree/master/host/class/uvc/usb_host_uvc
 dependencies:

host/class/uvc/usb_host_uvc/include/usb/uvc_host.h

@@ -182,6 +182,8 @@ typedef struct {
         int number_of_urbs;          /**< Number of URBs for this stream. Triple buffering scheme is recommended */
         size_t urb_size;             /**< Size in bytes of 1 URB, 10kB should be enough for start.
                                           Larger value results in less frequent interrupts at the cost of memory consumption */
+        uint8_t **user_frame_buffers; /**< Optional: User-provided frame buffers. NULL (default) = driver allocates buffers.
+                                           Non-NULL = provide 'number_of_frame_buffers' buffers, each 'frame_size' bytes. */
     } advanced;
 } uvc_host_stream_config_t;
 

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

@@ -20,12 +20,13 @@ extern "C" {
  * @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] user_frame_buffers Optional user-provided frame buffers. If not NULL, use these instead of allocating
  * @return
  *     - ESP_OK: Success
  *     - ESP_ERR_NO_MEM: Not enough memory for frame buffers
  *     - ESP_ERR_INVALID_ARG: Invalid count or size of frame buffers
  */
-esp_err_t uvc_frame_allocate(uvc_stream_t *uvc_stream, int nb_of_fb, size_t fb_size, uint32_t fb_caps);
+esp_err_t uvc_frame_allocate(uvc_stream_t *uvc_stream, int nb_of_fb, size_t fb_size, uint32_t fb_caps, uint8_t **user_frame_buffers);
 
 /**
  * @brief Free allocated frame buffers

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

@@ -36,6 +36,7 @@ struct uvc_host_stream_s {
         uvc_host_frame_callback_t frame_cb;   // User's frame callback
         void *cb_arg;                         // Common argument for user's callbacks
         QueueHandle_t empty_fb_queue;         // Queue of empty framebuffers
+        bool user_provided_fb;                // Flag indicating if frame buffers are user-provided
 
         // Constant USB descriptor values
         uint16_t bcdUVC;                      // Version of UVC specs this device implements

host/class/uvc/usb_host_uvc/test_app/main/test_uvc_host.c

@@ -310,4 +310,120 @@ TEST_CASE("Open and change format", "[uvc]")
     vTaskDelay(20); // Short delay to allow task to be cleaned up
 }
 
+/**
+ * @brief UVC user-provided frame buffers streaming test
+ *
+ * This test verifies zero-copy streaming with user-provided buffers.
+ *
+ * -# Allocate user frame buffers
+ * -# Open UVC stream with user-provided buffers
+ * -# Start streaming
+ * -# Receive frames and verify they use user buffers (pointer check)
+ * -# Stop streaming
+ * -# Close stream and free buffers
+ */
+static volatile int frames_received = 0;
+static uint8_t **test_user_buffers_ptr = NULL;
+static int test_num_buffers = 0;
+
+static bool test_frame_callback(const uvc_host_frame_t *frame, void *user_ctx)
+{
+    frames_received++;
+
+    // Verify that frame data pointer is one of our user buffers
+    bool is_user_buffer = false;
+    for (int i = 0; i < test_num_buffers; i++) {
+        if (frame->data == test_user_buffers_ptr[i]) {
+            is_user_buffer = true;
+            printf("Frame %d received in user buffer[%d] (%p), size: %zu bytes\n",
+                   frames_received, i, frame->data, frame->data_len);
+            break;
+        }
+    }
+
+    TEST_ASSERT_TRUE_MESSAGE(is_user_buffer, "Frame data is not in user-provided buffer!");
+    return true; // Return frame immediately
+}
+
+TEST_CASE("Streaming with user-provided frame buffers", "[uvc]")
+{
+    test_install_uvc_driver();
+
+    // Allocate user frame buffers
+    const int num_buffers = 3;
+    const size_t buffer_size = 60 * 1024;
+    uint8_t *user_buffers[num_buffers];
+
+    printf("Allocating %d * %d KB buffers for streaming test\n", num_buffers, buffer_size / 1024);
+    for (int i = 0; i < num_buffers; i++) {
+#if CONFIG_SPIRAM
+        user_buffers[i] = heap_caps_malloc(buffer_size, MALLOC_CAP_SPIRAM);
+#else
+        user_buffers[i] = heap_caps_malloc(buffer_size, MALLOC_CAP_DEFAULT);
+#endif
+        TEST_ASSERT_NOT_NULL(user_buffers[i]);
+        printf("  Buffer[%d] at %p\n", i, user_buffers[i]);
+    }
+
+    // Set global pointers for callback verification
+    test_user_buffers_ptr = user_buffers;
+    test_num_buffers = num_buffers;
+    frames_received = 0;
+
+    printf("Opening UVC stream\n");
+    uvc_host_stream_hdl_t stream = NULL;
+    uvc_host_stream_config_t stream_config = {
+        .event_cb = NULL,
+        .frame_cb = test_frame_callback,
+        .user_ctx = NULL,
+        .usb = {
+            .dev_addr = UVC_HOST_ANY_DEV_ADDR,
+            .vid = UVC_HOST_ANY_VID,
+            .pid = UVC_HOST_ANY_PID,
+            .uvc_stream_index = 0,
+        },
+        .vs_format = {
+            .h_res = 1280,
+            .v_res = 720,
+            .fps = 15,
+            .format = UVC_VS_FORMAT_MJPEG,
+        },
+        .advanced = {
+            .number_of_frame_buffers = num_buffers,
+            .frame_size = buffer_size,
+            .frame_heap_caps = 0,
+            .number_of_urbs = 4,
+            .urb_size = 10 * 1024,
+            .user_frame_buffers = user_buffers,
+        },
+    };
+
+    TEST_ASSERT_EQUAL(ESP_OK, uvc_host_stream_open(&stream_config, 1000, &stream));
+    TEST_ASSERT_NOT_NULL(stream);
+
+    printf("Starting stream\n");
+    TEST_ASSERT_EQUAL(ESP_OK, uvc_host_stream_start(stream));
+
+    // Receive frames for 3 seconds
+    printf("Streaming for 3 seconds...\n");
+    vTaskDelay(pdMS_TO_TICKS(3000));
+
+    printf("Stopping stream\n");
+    TEST_ASSERT_EQUAL(ESP_OK, uvc_host_stream_stop(stream));
+
+    printf("Total frames received: %d\n", frames_received);
+    TEST_ASSERT_GREATER_THAN(0, frames_received);
+
+    // Clean-up
+    TEST_ASSERT_EQUAL(ESP_OK, uvc_host_stream_close(stream));
+
+    printf("Freeing user frame buffers\n");
+    for (int i = 0; i < num_buffers; i++) {
+        free(user_buffers[i]);
+    }
+
+    TEST_ASSERT_EQUAL(ESP_OK, uvc_host_uninstall());
+    vTaskDelay(20);
+}
+
 #endif // SOC_USB_OTG_SUPPORTED

host/class/uvc/usb_host_uvc/uvc_bulk.c

@@ -86,8 +86,7 @@ void bulk_transfer_callback(usb_transfer_t *transfer)
         uvc_stream->single_thread.next_bulk_packet = UVC_STREAM_BULK_PACKET_SOF;
 
         if (payload_header->bmHeaderInfo.end_of_frame) {
-            assert(payload_header->bmHeaderInfo.frame_id == uvc_stream->single_thread.current_frame_id);
-            if (payload_header->bmHeaderInfo.error) {
+            if (payload_header->bmHeaderInfo.error || payload_header->bmHeaderInfo.frame_id != uvc_stream->single_thread.current_frame_id) {
                 uvc_stream->single_thread.skip_current_frame = true;
             }
 

host/class/uvc/usb_host_uvc/uvc_frame.c

@@ -30,29 +30,46 @@ esp_err_t uvc_host_frame_return(uvc_host_stream_hdl_t stream_hdl, uvc_host_frame
     return ESP_OK;
 }
 
-esp_err_t uvc_frame_allocate(uvc_stream_t *uvc_stream, int nb_of_fb, size_t fb_size, uint32_t fb_caps)
+esp_err_t uvc_frame_allocate(uvc_stream_t *uvc_stream, int nb_of_fb, size_t fb_size, uint32_t fb_caps, uint8_t **user_frame_buffers)
 {
     UVC_CHECK(uvc_stream, ESP_ERR_INVALID_ARG);
     esp_err_t ret;
 
+    // Determine if we're using user-provided buffers
+    const bool using_user_buffers = (user_frame_buffers != NULL);
+    uvc_stream->constant.user_provided_fb = using_user_buffers;
+
     // We will be passing the frame buffers by reference
     uvc_stream->constant.empty_fb_queue = xQueueCreate(nb_of_fb, sizeof(uvc_host_frame_t *));
     UVC_CHECK(uvc_stream->constant.empty_fb_queue, ESP_ERR_NO_MEM);
+
     for (int i = 0; i < nb_of_fb; i++) {
         // Allocate the frame buffer
         uvc_host_frame_t *this_fb = malloc(sizeof(uvc_host_frame_t));
-        if (fb_caps == 0) {
-            fb_caps = MALLOC_CAP_DEFAULT; // In case the user did not fill the config, set it to default
-        }
-        uint8_t *this_data = heap_caps_malloc(fb_size, fb_caps);
-        if (this_data == NULL || this_fb == NULL) {
-            free(this_fb);
-            free(this_data);
+        if (this_fb == NULL) {
             ret = ESP_ERR_NO_MEM;
-            ESP_LOGE(TAG, "Not enough memory for frame buffers %zu", fb_size);
+            ESP_LOGE(TAG, "Not enough memory for frame buffer structure");
             goto err;
         }
 
+        uint8_t *this_data = NULL;
+        if (using_user_buffers) {
+            // Use user-provided buffer (already validated in uvc_host_stream_open)
+            this_data = user_frame_buffers[i];
+        } else {
+            // Allocate driver-managed buffer
+            if (fb_caps == 0) {
+                fb_caps = MALLOC_CAP_DEFAULT; // In case the user did not fill the config, set it to default
+            }
+            this_data = heap_caps_malloc(fb_size, fb_caps);
+            if (this_data == NULL) {
+                free(this_fb);
+                ret = ESP_ERR_NO_MEM;
+                ESP_LOGE(TAG, "Not enough memory for frame buffers %zu", fb_size);
+                goto err;
+            }
+        }
+
         // Set members to default
         this_fb->data = this_data;
         this_fb->data_buffer_len = fb_size;
@@ -78,7 +95,10 @@ void uvc_frame_free(uvc_stream_t *uvc_stream)
     // Free all Frame Buffers and the Queue itself
     uvc_host_frame_t *this_fb;
     while (xQueueReceive(uvc_stream->constant.empty_fb_queue, &this_fb, 0) == pdPASS) {
-        free(this_fb->data);
+        // Only free the data buffer if it was allocated by the driver (not user-provided)
+        if (!uvc_stream->constant.user_provided_fb) {
+            free(this_fb->data);
+        }
         free(this_fb);
     }
     vQueueDelete(uvc_stream->constant.empty_fb_queue);

host/class/uvc/usb_host_uvc/uvc_host.c

@@ -665,6 +665,19 @@ esp_err_t uvc_host_stream_open(const uvc_host_stream_config_t *stream_config, in
     UVC_CHECK(stream_config, ESP_ERR_INVALID_ARG);
     UVC_CHECK(stream_hdl_ret, ESP_ERR_INVALID_ARG);
 
+    // Validate user-provided frame buffers configuration
+    if (stream_config->advanced.user_frame_buffers != NULL) {
+        UVC_CHECK(stream_config->advanced.number_of_frame_buffers > 0, ESP_ERR_INVALID_ARG);
+        UVC_CHECK(stream_config->advanced.frame_size > 0, ESP_ERR_INVALID_ARG);
+        // Verify that all user-provided buffers are not NULL
+        for (int i = 0; i < stream_config->advanced.number_of_frame_buffers; i++) {
+            if (stream_config->advanced.user_frame_buffers[i] == NULL) {
+                ESP_LOGE(TAG, "User-provided frame buffer[%d] is NULL", i);
+                return ESP_ERR_INVALID_ARG;
+            }
+        }
+    }
+
     uvc_stream_t *uvc_stream;
     xSemaphoreTake(p_uvc_host_driver->open_close_mutex, portMAX_DELAY);
 
@@ -717,7 +730,8 @@ esp_err_t uvc_host_stream_open(const uvc_host_stream_config_t *stream_config, in
             uvc_stream,
             stream_config->advanced.number_of_frame_buffers,
             stream_config->advanced.frame_size ? stream_config->advanced.frame_size : vs_result.dwMaxVideoFrameSize,
-            stream_config->advanced.frame_heap_caps),
+            stream_config->advanced.frame_heap_caps,
+            stream_config->advanced.user_frame_buffers),
         err, TAG,);
 
     // Save info