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

[leeebo]

Description

1. Support user-provided frame buffers for zero-copy operation. Right now, You can now pass your own buffers to the driver through the user_frame_buffers field. The driver will write frames directly to your buffers, skipping the copy entirely.
2. Fixed assertion failure when receiving packets with unexpected frame_id. In some cameras, we encountered this situation. Perhaps it was because the USB transfer speed was insufficient that some data packets were lost inside the camera.

Backward Compatibility

The new user_frame_buffers field is optional and defaults to NULL. If you don't set it, everything works exactly as before - no code changes needed.

However, out of caution, I've bumped the minor version to 2.4.0. While this shouldn't technically break anything (it's an additive change), the buffer management behavior does change when the new field is used. Better safe than sorry - this gives users a clear signal that something noteworthy was added.

Related

Testing

• Test ESP32-P4 with USB Camera with 720P resolution

---

Checklist

Before submitting a Pull Request, please ensure the following:

• 🚨 This PR does not introduce breaking changes.
• All CI checks (GH Actions) pass.
• Documentation is updated as needed.
• Tests are updated or added as necessary.
• Code is well-commented, especially in complex areas.
• Git history is clean — commits are squashed to the minimum necessary.

---

Note

Adds zero-copy support via user-supplied frame buffers and skips frames with unexpected frame_id at EoF; updates API, tests, docs, and bumps version to 2.4.0.

• API/Driver:
  • Add advanced.user_frame_buffers to uvc_host_stream_config_t; validate buffers in uvc_host_stream_open().
  • Extend uvc_frame_allocate() to accept user buffers and track user_provided_fb; free buffers conditionally in uvc_frame_free().
• Streaming (Bulk):
  • On EoF, skip frame if bmHeaderInfo.error or frame_id mismatch instead of asserting.
• Tests:
  • Update calls to uvc_frame_allocate(..., NULL) and set .user_frame_buffers = NULL in opening tests.
  • Add runtime test using user-provided buffers in test_app.
• Docs:
  • Document user-provided buffers in docs/FAQ.md and docs/arch_notes.md.
• Versioning/Changelog:
  • Bump component to 2.4.0 and update CHANGELOG.md.

^{Written by Cursor Bugbot for commit 70f9013. This will update automatically on new commits. Configure here.}

[cursor]

This PR is being reviewed by Cursor Bugbot

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[tore-espressif]

@leeebo thank for this feature!

I left two of nit-picky comments.
You can also consider writing something to arch_notes.md or FAQ.md about this new feature. Although this is not a blocker, I plan to improve the docs of UVC driver soon

[tore-espressif]

@leeebo I added this PR to 2.4.0 milestone. Please wait for #319 before merging, thanks!

[peter-marcisovsky]

LGTM, tested on HW.