feat(usb_host): esp sleep modes verification

[peter-marcisovsky]

Description

Verification of using light sleep and deep sleep in combination with USB Host application.

Light sleep

• Using CONFIG_ESP_SLEEP_EVENT_CALLBACKS
• Register enter and exit light sleep events
• Calling root port suspend/resume (not public API) upon enter/exit light sleep to effectively suspend the peripheral and the connected device
• Connected device enters suspended state during the light sleep
• Connected device must not undergo a reset during light sleep

Light sleep log, with light sleep callbacks enabeld

Root port enters suspended mode before entering light sleep

Light sleep log, with light sleep callbacks disabled

Missing suspend/resume sequence from host. Host just stops sending SOFs without any "reason". This pattern only appears on HS port. The device does not enter suspended state

Enter light sleep latency

Added light sleep latency when entering and exiting light sleep with automatic suspend/resume of the peripheral

	esp32s2	esp32s3	esp32p4	esp32h4
enter light sleep	~135 uS	~80 uS	~20 uS	~110 uS
exit light sleep	~65 uS	~50 uS	~10 uS	~35 uS

Deep sleep

• Connected device shall be disconnected upon entering deep sleep and connected back after exiting deep sleep
• RAM is unpowered during deep sleep and any information about the connected device (cached descriptors, device state.. ) is lost during deep sleep
• Currently, HNP cap is enabled on all HNP capable targets by default, to prevent current leakage in deep sleep.

Testing

• usb_sleep_modes target tests
  • light sleep functionality verification
  • deep sleep functionality verification
  • enter/exit light sleep latency
  • error handling inside the enter/exit light sleep callbacks

Limitations

• Light sleep: a device must be present in order to call root port suspend in a light sleep callback
  • Known "issue" from the original suspend/resume implementation before HCLK clock gating was introduced
  • Will be fixed in a separate PR, which will remove the device presence obligation when entering light sleep

Related

• Documentation feat(usb_host): system sleep docs #476
• Tested by feat(cdc_acm_host): ESP system sleep modes #478

---

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

Medium Risk
Adds sleep event callbacks that suspend/resume the USB root port from light-sleep critical sections and introduces new synchronization/error-handling paths, which could affect USB stability and wake latency on supported targets.

Overview
Adds optional automatic USB root-port suspend/resume around light sleep (guarded by CONFIG_ESP_SLEEP_EVENT_CALLBACKS) by registering sleep event callbacks in usb_host_install()/usb_host_uninstall() and coordinating async suspend completion via a new semaphore.

Extends the hub driver with a HUB_EVENT_SUSPEND_COMPLETED event and a hub_root_mark_light_sleep_auto_resume() flag to safely handle the case where a device disconnects during light sleep (HCD port in RECOVERY) before attempting resume.

Introduces a new usb_sleep_modes target test app (Unity + pytest) that exercises USB Host behavior across repeated light-sleep cycles and multi-stage deep-sleep resets, including an error-path test for sleep callback failures.

^{Reviewed by Cursor Bugbot for commit 7a8ee7a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7a8ee7a. Configure here.}

[peter-marcisovsky]

Converted to draft, trying to lower the sleep latency even more.