feat(usb_host): Global suspend/resume by peter-marcisovsky · Pull Request #275 · espressif/esp-usb

peter-marcisovsky · 2025-10-01T10:56:13Z

Description

This MR adds Global Suspend/Resume functionality for USB Host.

Limitations

No remote wakeup (for now, as it would be too big for one MR)
No selective suspend/resume, same reason as above
Not working with external hubs (we need to add ext_hub api to stop and start ext. hub)
Tested by MSC, HID, CDC, UAC, UVC class drivers as each class driver must be modified to work with suspend/resume events

How it works

Suspending
Global Suspend/Resume implemented through root port - Stop/Start sending SOFs
- A device must be connected
  - As we are not suspending the USB-OTG peripheral on the USB Host side (to save power), it does not make sense to suspend root port without any device connected
- Check if any transfers are submitted
- Flush and Halt all EPs of all devices
- Both Hub and HCD Port must be in correct state (active state, with a device connected) to enter suspend mode
- Suspend is issued via HCD Port command -> Set HPRT.PrtSusp bit
Resuming
- A device must be connected
- Both Hub and HCD Port must be in correct state (Suspended state) to exit suspended mode
- Resume is issued via HCD Port command -> Clear HPRT.PrtSusp bit
- Clear all previously halted EPs of all devices

Changes

Client events

USB_HOST_CLIENT_EVENT_DEV_SUSPENDED delivered to a client which opened a device which is now suspended
USB_HOST_CLIENT_EVENT_DEV_RESUMED delivered to a client which opened a device which is now resumed
both event messages deliver device handle of the device being suspended/resumed

USB Host lib event - unblock `usb_host_lib` task

USB_HOST_LIB_EVENT_FLAGS_AUTO_SUSPEND automatic suspend timer has expired.

Auto Suspend timer

usb_host_lib_set_auto_pm()
Can be configured as:
- USB_HOST_LIB_PM_SUSPEND_ONE_SHOT one shot suspend timer
- USB_HOST_LIB_PM_SUSPEND_PERIODIC periodic suspend timer

USB host public API

Global suspend:
- usb_host_lib_root_port_suspend(void)
Resume:
- usb_host_lib_root_port_resume(void)

USBH public API

Issuing actions for all devices regarding Suspend/Resume
- usbh_devs_set_pm_actions_all()

Hub public API

Mark root port as ready for suspend -> processed in hub_process() -> HCD command
- hub_root_mark_suspend()
Mark root port as ready for resume -> processed in hub_process() -> HCD command
- hub_root_mark_resume()
Check if the root hub can be suspended (Correct hub state, no transfer in flight)
- hub_root_can_suspend()

HCD Tests

HCD Port Suspend/Resume with sudden disconnect
HCD Port Suspend/Resume already present

USB Host Tests

MSC client to test Suspending/Resuming at various conditions (No client opened device, No or A transfer submitted, sudden disconnect.. )
Automatic timer test

Closes Provide public API for ESP32-S3 USB host suspend functionality (IDFGH-13974) esp-idf#14805
MSC Host suspend/resume feat(usb_host): MSC Host add suspend/resume events #181
HID Host suspend/resume feat(host/hid): HID Host add suspend/resume events #182
CDC-ACM Host suspend/resume feat(usb_host): CDC-ACM Host add suspend/resume events #206
UAC Host suspend/resume feat(uac_host): Add global suspend/resume #211
UVC Host suspend/resume feat(usb_host): UVC Host add suspend/resume events #328

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.

peter-marcisovsky · 2025-10-07T11:17:30Z

@tore-espressif @roma-jam @igi540
This MR is a cherry-pick from esp-idf suspend resume MR (already reviewed and approved).

There is one change in the separate commit 6594a35.

The change is regarding USB Hal. The suspend/resume feature calls one function from HAL, which was merged to esp-idf separately in 57d48ef and will be bacported to ID 5.4 and IDF 5.5.

We decided to access ll instead of hal in this feature, to allow users of any IDF 5.4.x and IDF 5.5.x to use the suspend/resume feature in the managed USB component. Otherwise (with hal call) the feature will be limited to the current IDF 5.5.2 and newer (IDF 5.4.2 and newer)

This change will be removed (hal function will be called instead of ll after the end of support for IDF 5.5).

PTAL, Thank you.

roma-jam

Still LGTM.

I tried to review it from the scratch again and maybe there are more notes, that I might gave sooner.

I checked the test cases, and I didn't see the one, which handles the sudden disconnection after putting the port to suspend state (tests in the test_usb_host_plugging.c).

Basically, it is interesting to verify the following cases:

detaching the device, while the suspend command was triggered (device has a flag USBH_DEV_SUSPEND_EVT or any other flags, that we can set during the usbh_devs_set_pm_actions_all)
detaching the device, which already is in suspended mode (so the hcd_port is in suspended state).

peter-marcisovsky · 2025-10-13T11:59:26Z

@roma-jam Thank you very much for the review. To address your point about testing

I checked the test cases, and I didn't see the one, which handles the sudden disconnection after putting the port to suspend state (tests in the test_usb_host_plugging.c).

Sudden diconnect on HCD level here
Sudden diconnect on USB Host level here
Also, each of the Class drivers tests feature it's own sudden disconnect tests, for example here

I see you are mentioning test_usb_host_plugging.c file, I will check if I can move some tests there, just to be consistent with the testing hierarchy.

tore-espressif

@peter-marcisovsky great work. I leave only 2 nitpicky questions.
Can you also add an entry to changelog?

I want to run few experiments on HW and then we can finally merge it.

tore-espressif

@peter-marcisovsky I tested with P4-ECO5, no additional remarks, LGTM!

tore-espressif · 2025-10-17T09:59:39Z

@peter-marcisovsky I tested with P4-ECO5, no additional remarks, LGTM!

oh, the changelog entry is still missing!

- Suspend/Resume of the root port (global) - Auto resume by transfer submit feature - No remote wake-up feature - Closes espressif/esp-idf#14805

peter-marcisovsky · 2025-10-17T10:08:34Z

@tore-espressif thanks for checking. Changelog added, ready to be merged.

alex-k8 · 2025-10-22T13:26:09Z

Hello this seems great, thank you very much for this! I have a question. Let's say I have a keyboard connected to the ESP32-S3, and I put it to sleep using this new method. Can I wake it up by pressing a key on the keyboard, or is that the No remote wakeup that was mentioned? Thanks!

peter-marcisovsky · 2025-10-22T13:46:51Z

Hi @alex-k8 the feature you are requesting is remote wakeup, which is not implemented in this PR.
I already started working on the remote wakeup in #298. We might release the both features (This one and the remote wake) together.

alex-k8 · 2025-10-22T13:50:18Z

Thank you for the amazing work @peter-marcisovsky ! That feature will be a game changer for me.

peter-marcisovsky added this to the usb_host v1.0.1 milestone Oct 1, 2025

peter-marcisovsky self-assigned this Oct 1, 2025

peter-marcisovsky added Status: In Progress Issue is being worked on Component: usb_host Issue affects usb_host component labels Oct 1, 2025

github-advanced-security AI found potential problems Oct 1, 2025

View reviewed changes

Comment thread host/usb/src/hcd_dwc.c Fixed

Comment thread host/usb/src/hub.c Fixed

peter-marcisovsky force-pushed the feat/usb_host_suspend branch 2 times, most recently from 6b88280 to 5ead420 Compare October 7, 2025 11:05

peter-marcisovsky force-pushed the feat/usb_host_suspend branch 2 times, most recently from 6594a35 to 025f3a1 Compare October 9, 2025 09:29

peter-marcisovsky marked this pull request as ready for review October 9, 2025 12:28

peter-marcisovsky requested review from igi540, roma-jam and tore-espressif October 9, 2025 13:19

peter-marcisovsky added Status: Reviewing Issue is being reviewed and removed Status: In Progress Issue is being worked on labels Oct 9, 2025

tore-espressif modified the milestones: usb_host v1.0.1, usb_host 1.1.0 Oct 9, 2025

roma-jam reviewed Oct 10, 2025

View reviewed changes

igi540 approved these changes Oct 12, 2025

View reviewed changes

Comment thread host/usb/test/target_test/usb_host/main/msc_client_transfer_resume.c Outdated

Comment thread host/usb/src/hcd_dwc.c

roma-jam approved these changes Oct 13, 2025

View reviewed changes

tore-espressif reviewed Oct 15, 2025

View reviewed changes

Comment thread host/usb/include/usb/usb_host.h Outdated

Comment thread host/usb/src/hcd_dwc.c

peter-marcisovsky force-pushed the feat/usb_host_suspend branch from 623f8c4 to 3cd4cc8 Compare October 15, 2025 15:17

tore-espressif approved these changes Oct 17, 2025

View reviewed changes

feat(usb_host): Global suspend/resume

d6209d7

- Suspend/Resume of the root port (global) - Auto resume by transfer submit feature - No remote wake-up feature - Closes espressif/esp-idf#14805

peter-marcisovsky force-pushed the feat/usb_host_suspend branch from 3cd4cc8 to d6209d7 Compare October 17, 2025 10:07

peter-marcisovsky merged commit af7de6d into master Oct 22, 2025
96 of 100 checks passed

peter-marcisovsky deleted the feat/usb_host_suspend branch October 22, 2025 13:04

peter-marcisovsky added Status: Done Issue is done internally and removed Status: Reviewing Issue is being reviewed labels Nov 20, 2025

This was referenced Nov 20, 2025

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

Merged

Refactor(usb_host): Rename auto suspend timer public API #333

Merged

feat(usb_host): Exit suspend state by port reset #335

Merged

This was referenced Dec 3, 2025

USB Host remote wakeup #298

Merged

release(usb_host_lib): v1.1.0 #348

Merged

feat(uac_host): Add global suspend/resume #211

Draft

tore-espressif mentioned this pull request Feb 16, 2026

USB HID example howto enter suspend mode (IDFGH-9806) espressif/esp-idf#11141

Closed

Conversation

peter-marcisovsky commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Limitations

How it works

Changes

Client events

USB Host lib event - unblock usb_host_lib task

Auto Suspend timer

USB host public API

USBH public API

Hub public API

HCD Tests

USB Host Tests

Related

Checklist

Uh oh!

Uh oh!

Uh oh!

peter-marcisovsky commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

roma-jam left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

peter-marcisovsky commented Oct 13, 2025

Uh oh!

tore-espressif left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tore-espressif left a comment

Choose a reason for hiding this comment

Uh oh!

tore-espressif commented Oct 17, 2025

Uh oh!

peter-marcisovsky commented Oct 17, 2025

Uh oh!

Uh oh!

alex-k8 commented Oct 22, 2025

Uh oh!

peter-marcisovsky commented Oct 22, 2025

Uh oh!

alex-k8 commented Oct 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

peter-marcisovsky commented Oct 1, 2025 •

edited

Loading

USB Host lib event - unblock `usb_host_lib` task

peter-marcisovsky commented Oct 7, 2025 •

edited

Loading