refactor(uac_host): Suspend/Resume public API terminology

[peter-marcisovsky]

Changes

• update (no functional changes) suspend/resume terminology to pause/unpause

Why do we need this change

• As a prerequisite for root port suspend/resume support for this driver
• The current driver contains a set of following public API functions and defines/enums

esp_err_t uac_host_device_suspend(uac_host_device_handle_t uac_dev_handle);
esp_err_t uac_host_device_resume(uac_host_device_handle_t uac_dev_handle);
#define FLAG_STREAM_SUSPEND_AFTER_START

And private API functions

static esp_err_t uac_host_interface_suspend(uac_iface_t *iface);
static esp_err_t uac_host_interface_resume(uac_iface_t *iface);

• Those functions do not actually suspend or resume the device (or interface) to lower power consumption, but rather suspend and resume audio data stream

The API shall be changed in a following way, not to confuse the users with the public API terminology

• Updated public API

esp_err_t uac_host_device_pause(uac_host_device_handle_t uac_dev_handle);
esp_err_t uac_host_device_unpause(uac_host_device_handle_t uac_dev_handle);
#define FLAG_STREAM_PAUSE_AFTER_START

• Updated private API

static esp_err_t uac_host_interface_pause(uac_iface_t *iface);
static esp_err_t uac_host_interface_unpause(uac_iface_t *iface);

---

Related

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

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

Standardizes UAC stream control terminology from suspend/resume to pause/unpause.

• Public API renamed: uac_host_device_suspend/resume -> uac_host_device_pause/unpause; FLAG_STREAM_SUSPEND_AFTER_START -> FLAG_STREAM_PAUSE_AFTER_START
• Internal functions and states renamed (e.g., uac_host_interface_suspend/resume -> ..._pause/unpause, SUSPENDING -> PAUSING); comments/logs updated
• Usage updated across examples and tests (e.g., audio_player, loopback tests) to new APIs and flag
• README and CHANGELOG updated; header docs note FLAG_STREAM_PAUSE_AFTER_START behavior

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

[peter-marcisovsky]

@tore-espressif Here is a regression from conditional CI run.

In this PR, there are only UAC changes. Its test app does not have any pytest file with target runner marker, so there is no target test to be run in this PR. Yet still the CI fails.

I tried to replicate it locally and it is behaving the same way.

• If at least one of the pytest files with target marker (msc, cdc, hid) is built and run the CI passes (otherwise fails)

[tore-espressif]

@tore-espressif Here is a regression from conditional CI run.

In this PR, there are only UAC changes. Its test app does not have any pytest file with target runner marker, so there is no target test to be run in this PR. Yet still the CI fails.

I tried to replicate it locally and it is behaving the same way.

* If at least one of the pytest files with target marker (msc, cdc, hid) is built and run the CI passes (otherwise fails)

@peter-marcisovsky I'm sorry about that, it was working before I merged it... I'll have a look ASAP

[igi540]

Reserving “suspend/resume” for the upcoming real root-port/device suspend/resume support makes sense.

One question about API compatibility and future semantics:

Since this is a public API rename (uac_host_device_suspend()/resume() + FLAG_STREAM_SUSPEND_AFTER_START), existing user code will stop compiling after this change. Would it make sense to keep the old names as deprecated aliases (wrappers/macros mapping to pause/unpause) for at least one release, and document the migration in the changelog/README?

This might also help avoid a more subtle issue later: once “real suspend/resume” is merged and these names get reused with different behavior, users relying on the current stream-control semantics could get surprised. A deprecation window now would make that transition clearer and safer.

(If you prefer a hard break immediately, could we at least call it out explicitly as a breaking change in the changelog with a short old→new mapping?)

[peter-marcisovsky]

@igi540 Yes, I had the same doubt, but just following what was agreed upon this changes in this response

[peter-marcisovsky]

After a discussion, it was agreed on, that this change would be considered as a breaking change (with very little actual beneficial change to the users) we have decided to postpone merging this and #211 PR.

Considering, there is a planned support of UAC 2.0, we will align this change (delivering suspend/resume feature for the driver) with the UAC 2.0 release plan and will deliver the suspend/resume feature together with the actual UAC 2.0 driver.