feat(usb_host): UVC Host add suspend/resume events

[peter-marcisovsky]

Description

This MR adds Suspend/Resume events for UVC class driver as a follow-up for the Global/Suspend resume

Changes

Added Suspend and Resume UVC Host interface events

// For backward compatibility with IDF versions which do not have suspend/resume api
#ifdef USB_HOST_LIB_EVENT_FLAGS_AUTO_SUSPEND
#define UVC_HOST_SUSPEND_RESUME_API_SUPPORTED
#endif

Related

• Closes Suspend/Resume support for UVC Class driver
• Related feat(usb_host): Global suspend/resume #275

Testing

• Added target tests to test UVC Host reaction to suspend/resume events

---

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 suspend/resume handling to UVC Host, exposing new events and updating examples and tests accordingly.

• API/Driver:
  • Add UVC_HOST_DEVICE_SUSPENDED and UVC_HOST_DEVICE_RESUMED events in include/usb/uvc_host.h (gated by UVC_HOST_SUSPEND_RESUME_API_SUPPORTED).
  • Implement suspend/resume flow in uvc_host.c:
    • New helper uvc_host_device_suspended() to pause stream and ensure frames are returned.
    • Handle USB_HOST_CLIENT_EVENT_DEV_SUSPENDED/DEV_RESUMED to notify clients and manage stream state.
• Examples:
  • Update examples/basic_uvc_stream and examples/camera_display to log and handle new suspend/resume events (conditional on macro); refresh SPDX year in camera_display.c.
• Tests:
  • Add test_app/main/test_uvc_host_pm.c with suspend/resume scenarios (basic, while streaming, resume-on-transfer, close while suspended, open while suspended, concurrent suspend/disconnect, auto-suspend timer).
  • Update test_app/sdkconfig.defaults to enable indexed task notifications.
• Docs:
  • Update CHANGELOG.md with “Added global suspend/resume support”.

^{Written by Cursor Bugbot for commit 76274d5. 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.

[peter-marcisovsky]

Updated the MR with the recent #333 PR (Refactor(usb_host): Rename auto suspend timer public API), fixed cursor review into a separate commit. And rebased.

[roma-jam]

Two questions from my side.

[roma-jam]

Just to understand it better for me.

If we are streaming, logically the SUSPEND event should never occur, right?
Because there is a constant ongoing urb transfers, which restart the auto suspend timer every time.

So, the SUSPEND event might occur, when we have several devices attached to the host and num_urb_pending == 0 ?

[peter-marcisovsky]

The suspend even can occur any time.

Yes, the suspend timer gets reset whenever there is an activity either from a class driver, or from the usb_host_lib itself. But the suspend timer is only used for automatic suspend.

The suspend event can occur anytime, as it is usb_host_lib call. Thus even during streaming. The usb_host_lib automatically clears and halts all the pipes (does not matter if a client is actively using some pipe or not). Once the suspend procedure is over, the client only gets a notification. Aka, there is nothing that client can do, to prevent the suspend from happening.

[roma-jam]

We don't need to change the state for the uvc_stream to protect the stream or to handle the stream resuming somehow later, because if device was suspended, we can just enable the streaming and this will automatically resume the root port?

[peter-marcisovsky]

Essentially yes. The driver just pauses the stream to return frames (there is already not any activity on the bus, as the usb_host_lib halts all the EPs) after receiving suspend event.

Upon receiving resume event, the stream must be unpaused explicitly by the user.
Or, there is the automatic resume by transfer submit feature, so the user can continue streaming just by calling uvc_host_stream_unpause(), as this function submits a transfer, which automatically resumes the root port.

After going into suspended state, the user still owns the stream_hdl so he can simply unpause the stream and the device will resume automatically. I added a test case, which tests this here