refactor(uac_host): Suspend/Resume public API terminology

    - Replaced suspend/resume with pause/unpuase terminology
    - Preparation for suspend/resume support

Author: peter-marcisovsky

host/class/uac/usb_host_uac/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this component will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [unreleased]
+
+### Changed
+
+- Changed API terminology from suspend/resume to pause/unpause as pre-requisite for root port suspend/resume feature
+
 ## [1.3.3] - 2025-11-27
 
 ### Changed

host/class/uac/usb_host_uac/README.md

@@ -24,9 +24,9 @@ The following steps outline the typical API call pattern of the UAC Class Driver
 06. To enable/disable data streaming with specific audio format use:
     - `uac_host_device_start()`
     - `uac_host_device_stop()`
-07. To suspend/resume data streaming use:
-    - `uac_host_device_suspend()`
-    - `uac_host_device_resume()`
+07. To pause/unpause data streaming use:
+    - `uac_host_device_pause()`
+    - `uac_host_device_unpause()`
 08. To control the volume/mute use:
     - `uac_host_device_set_mute()`
 09. To control the volume use:

host/class/uac/usb_host_uac/examples/audio_player/main/main.c

@@ -199,11 +199,11 @@ static void mic_palyback_done_cb(void)
 {
     vTaskDelay(pdMS_TO_TICKS(1000)); // wait for a while before resuming recording
     if (s_mic_dev_handle != NULL) {
-        if (uac_host_device_resume(s_mic_dev_handle) == ESP_OK) {
+        if (uac_host_device_unpause(s_mic_dev_handle) == ESP_OK) {
             s_mic_recording = true;
             s_mic_record_wr = 0;
         } else {
-            ESP_LOGE(TAG, "Failed to resume MIC device");
+            ESP_LOGE(TAG, "Failed to unpause MIC device");
         }
     }
 }
@@ -396,16 +396,16 @@ static void uac_lib_task(void *arg)
                         if (s_mic_record_wr >= s_mic_record_buf_size) {
                             if (s_spk_dev_handle != NULL) {
                                 s_mic_recording = false;
-                                // Suspend microphone streaming before playback
-                                uac_host_device_suspend(s_mic_dev_handle);
+                                // Pause microphone streaming before playback
+                                uac_host_device_pause(s_mic_dev_handle);
                                 // Prepare playback of the recorded PCM
                                 player_config_t player_config = {
                                     .pcm_ptr = s_mic_record_buf,
                                     .pcm_size = s_mic_record_buf_size,
                                     .complete_cb = mic_palyback_done_cb,
                                 };
                                 if (start_pcm_playback(&player_config) != ESP_OK) {
-                                    uac_host_device_resume(s_mic_dev_handle);
+                                    uac_host_device_unpause(s_mic_dev_handle);
                                     s_mic_recording = true;
                                     s_mic_record_wr = 0;
                                 }

host/class/uac/usb_host_uac/include/usb/uac_host.h

@@ -31,10 +31,10 @@ extern "C" {
 /**
  * @brief Flags to control stream work flow
  *
- * FLAG_STREAM_SUSPEND_AFTER_START: do not start stream transfer during start, only claim interface and prepare memory
- * @note User should call uac_host_device_resume to start stream transfer when needed
+ * FLAG_STREAM_PAUSE_AFTER_START: do not start stream transfer during start, only claim interface and prepare memory
+ * @note User should call uac_host_device_unpause to start stream transfer when needed
 */
-#define FLAG_STREAM_SUSPEND_AFTER_START      (1 << 0)
+#define FLAG_STREAM_PAUSE_AFTER_START      (1 << 0)
 
 typedef struct uac_interface *uac_host_device_handle_t;    /*!< Logic Device Handle. Handle to a particular UAC interface */
 
@@ -303,7 +303,7 @@ esp_err_t uac_host_handle_events(TickType_t timeout);
 /**
  * @brief Start a UAC stream with specific stream configuration (channels, bit resolution, sample frequency)
  *
- * @note set flags FLAG_STREAM_SUSPEND_AFTER_START to suspend stream after start
+ * @note set flags FLAG_STREAM_PAUSE_AFTER_START to pause stream after start
  *
  * @param[in] uac_dev_handle  UAC device handle
  * @param[in] stream_config   Pointer to UAC stream configuration structure
@@ -318,26 +318,26 @@ esp_err_t uac_host_handle_events(TickType_t timeout);
 esp_err_t uac_host_device_start(uac_host_device_handle_t uac_dev_handle, const uac_host_stream_config_t *stream_config);
 
 /**
- * @brief Suspend a UAC stream
+ * @brief Pause a UAC stream
  *
  * @param[in] uac_dev_handle  UAC device handle
  * @return esp_err_t
  * - ESP_OK on success
  * - ESP_ERR_INVALID_ARG if the device handle is invalid
  * - ESP_ERR_INVALID_STATE if the device is not in the right state
  */
-esp_err_t uac_host_device_suspend(uac_host_device_handle_t uac_dev_handle);
+esp_err_t uac_host_device_pause(uac_host_device_handle_t uac_dev_handle);
 
 /**
- * @brief Resume a UAC stream with same stream configuration
+ * @brief Unpause a UAC stream with same stream configuration
  *
  * @param[in] uac_dev_handle  UAC device handle
  * @return esp_err_t
  * - ESP_OK on success
  * - ESP_ERR_INVALID_ARG if the device handle is invalid
  * - ESP_ERR_INVALID_STATE if the device is not in the right state
  */
-esp_err_t uac_host_device_resume(uac_host_device_handle_t uac_dev_handle);
+esp_err_t uac_host_device_unpause(uac_host_device_handle_t uac_dev_handle);
 
 /**
  * @brief Stop a UAC stream, stream resources will be released

host/class/uac/usb_host_uac/test_app/main/test_host_uac.c

@@ -602,7 +602,7 @@ TEST_CASE("test uac tx writing", "[uac_host][tx]")
         .channels = spk_alt_params.channels,
         .bit_resolution = spk_alt_params.bit_resolution,
         .sample_freq = spk_alt_params.sample_freq[0],
-        .flags = FLAG_STREAM_SUSPEND_AFTER_START,
+        .flags = FLAG_STREAM_PAUSE_AFTER_START,
     };
     TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_start(uac_device_handle, &stream_config));
 
@@ -669,7 +669,7 @@ TEST_CASE("test uac tx writing", "[uac_host][tx]")
     TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_get_volume(uac_device_handle, &actual_volume));
     volume = actual_volume;
     printf("Volume: %d \n", volume);
-    TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_resume(uac_device_handle));
+    TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_unpause(uac_device_handle));
     TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_write(uac_device_handle, (uint8_t *)tx_buffer, tx_size, 0));
 
     uint8_t test_counter = 0;
@@ -779,7 +779,7 @@ TEST_CASE("test uac tx rx loopback", "[uac_host][tx][rx]")
         .channels = mic_alt_params.channels,
         .bit_resolution = mic_alt_params.bit_resolution,
         .sample_freq = mic_alt_params.sample_freq[0],
-        .flags = FLAG_STREAM_SUSPEND_AFTER_START,
+        .flags = FLAG_STREAM_PAUSE_AFTER_START,
     };
 
     uint8_t actual_volume = 0;
@@ -831,8 +831,8 @@ TEST_CASE("test uac tx rx loopback", "[uac_host][tx][rx]")
     uint32_t test_counter = 0;
     event_queue_t evt_queue = {0};
     while (1) {
-        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_resume(mic_device_handle));
-        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_resume(spk_device_handle));
+        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_unpause(mic_device_handle));
+        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_unpause(spk_device_handle));
         while (1) {
             if (xQueueReceive(s_event_queue, &evt_queue, portMAX_DELAY)) {
                 TEST_ASSERT_EQUAL(UAC_DEVICE_EVENT, evt_queue.event_group);
@@ -885,8 +885,8 @@ TEST_CASE("test uac tx rx loopback", "[uac_host][tx][rx]")
         if (++test_counter >= test_times) {
             goto exit_rx;
         }
-        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_suspend(mic_device_handle));
-        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_suspend(spk_device_handle));
+        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_pause(mic_device_handle));
+        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_pause(spk_device_handle));
         time_counter = 0;
         vTaskDelay(100);
     }
@@ -938,7 +938,7 @@ TEST_CASE("test uac tx rx loopback with disconnect", "[uac_host][tx][rx][hot-plu
         .channels = mic_alt_params.channels,
         .bit_resolution = mic_alt_params.bit_resolution,
         .sample_freq = mic_alt_params.sample_freq[0],
-        .flags = FLAG_STREAM_SUSPEND_AFTER_START,
+        .flags = FLAG_STREAM_PAUSE_AFTER_START,
     };
     TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_start(mic_device_handle, &stream_config));
     TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_set_mute(mic_device_handle, 0));
@@ -979,8 +979,8 @@ TEST_CASE("test uac tx rx loopback with disconnect", "[uac_host][tx][rx][hot-plu
     uint32_t test_counter = 0;
     event_queue_t evt_queue = {0};
     while (1) {
-        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_resume(mic_device_handle));
-        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_resume(spk_device_handle));
+        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_unpause(mic_device_handle));
+        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_unpause(spk_device_handle));
         while (1) {
             if (xQueueReceive(s_event_queue, &evt_queue, portMAX_DELAY)) {
                 TEST_ASSERT_EQUAL(UAC_DEVICE_EVENT, evt_queue.event_group);
@@ -1033,8 +1033,8 @@ TEST_CASE("test uac tx rx loopback with disconnect", "[uac_host][tx][rx][hot-plu
         if (++test_counter >= test_times) {
             goto exit_rx;
         }
-        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_suspend(mic_device_handle));
-        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_suspend(spk_device_handle));
+        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_pause(mic_device_handle));
+        TEST_ASSERT_EQUAL(ESP_OK, uac_host_device_pause(spk_device_handle));
         time_counter = 0;
         vTaskDelay(100);
     }

host/class/uac/usb_host_uac/uac_host.c

@@ -124,9 +124,9 @@ typedef struct uac_host_device {
 typedef enum {
     UAC_INTERFACE_STATE_NOT_INITIALIZED = 0x00,     /*!< UAC Interface not initialized */
     UAC_INTERFACE_STATE_IDLE,                       /*!< UAC Interface has been opened but not started */
-    UAC_INTERFACE_STATE_READY,                      /*!< UAC Interface has started but stream is suspended */
+    UAC_INTERFACE_STATE_READY,                      /*!< UAC Interface has started but stream is paused */
     UAC_INTERFACE_STATE_ACTIVE,                     /*!< UAC Interface is streaming */
-    UAC_INTERFACE_STATE_SUSPENDING,                 /*!< UAC Interface is suspending */
+    UAC_INTERFACE_STATE_PAUSING,                    /*!< UAC Interface is pausing */
 } uac_iface_state_t;
 
 /**
@@ -1332,19 +1332,19 @@ static void stream_tx_xfer_done(usb_transfer_t *out_xfer)
 }
 
 /**
- * @brief Suspend active interface, the interface will be in READY state
+ * @brief Pause active interface, the interface will be in READY state
  *
  * @param[in] iface       Pointer to Interface structure
  * @return esp_err_t
  */
-static esp_err_t uac_host_interface_suspend(uac_iface_t *iface)
+static esp_err_t uac_host_interface_pause(uac_iface_t *iface)
 {
     UAC_RETURN_ON_INVALID_ARG(iface);
     UAC_RETURN_ON_INVALID_ARG(iface->parent);
     UAC_RETURN_ON_INVALID_ARG(iface->free_xfer_list);
     UAC_RETURN_ON_FALSE(is_interface_in_list(iface), ESP_ERR_NOT_FOUND, "Interface handle not found");
     UAC_RETURN_ON_FALSE((UAC_INTERFACE_STATE_ACTIVE == iface->state), ESP_ERR_INVALID_STATE, "Interface wrong state");
-    iface->state = UAC_INTERFACE_STATE_SUSPENDING;
+    iface->state = UAC_INTERFACE_STATE_PAUSING;
 
     // Set Interface alternate setting to 0
     usb_setup_packet_t usb_request;
@@ -1355,9 +1355,9 @@ static esp_err_t uac_host_interface_suspend(uac_iface_t *iface)
     memcpy(&uac_request, &usb_request, sizeof(usb_setup_packet_t));
     esp_err_t ret = uac_cs_request_set(iface->parent, &uac_request);
     if (ret != ESP_OK) {
-        ESP_LOGW(TAG, "Suspend Interface %d-%d Failed", iface->dev_info.iface_num, 0);
+        ESP_LOGW(TAG, "Pause Interface %d-%d Failed", iface->dev_info.iface_num, 0);
     } else {
-        ESP_LOGI(TAG, "Suspend Interface %d-%d", iface->dev_info.iface_num, 0);
+        ESP_LOGI(TAG, "Pause Interface %d-%d", iface->dev_info.iface_num, 0);
     }
 
     uint8_t ep_addr = iface->iface_alt[iface->cur_alt].ep_addr;
@@ -1382,12 +1382,12 @@ static esp_err_t uac_host_interface_suspend(uac_iface_t *iface)
 }
 
 /**
- * @brief Resume suspended interface, the interface will be in ACTIVE state
+ * @brief Unpause paused interface, the interface will be in ACTIVE state
  *
  * @param[in] iface       Pointer to Interface structure
  * @return esp_err_t
  */
-static esp_err_t uac_host_interface_resume(uac_iface_t *iface)
+static esp_err_t uac_host_interface_unpause(uac_iface_t *iface)
 {
     UAC_RETURN_ON_INVALID_ARG(iface);
     UAC_RETURN_ON_INVALID_ARG(iface->parent);
@@ -1403,7 +1403,7 @@ static esp_err_t uac_host_interface_resume(uac_iface_t *iface)
     uac_cs_request_t uac_request = {0};
     memcpy(&uac_request, &usb_request, sizeof(usb_setup_packet_t));
     UAC_RETURN_ON_ERROR(uac_cs_request_set(iface->parent, &uac_request), "Unable to set Interface alternate");
-    ESP_LOGI(TAG, "Resume Interface %d-%d", iface->dev_info.iface_num, iface->cur_alt + 1);
+    ESP_LOGI(TAG, "Unpause Interface %d-%d", iface->dev_info.iface_num, iface->cur_alt + 1);
     // Set endpoint frequency control
     if (iface->iface_alt[iface->cur_alt].freq_ctrl_supported) {
         ESP_LOGI(TAG, "Set EP %d frequency %"PRIu32, iface->iface_alt[iface->cur_alt].ep_addr & USB_B_ENDPOINT_ADDRESS_EP_NUM_MASK, iface->iface_alt[iface->cur_alt].cur_sampling_freq);
@@ -2201,7 +2201,7 @@ esp_err_t uac_host_device_close(uac_host_device_handle_t uac_dev_handle)
 
     UAC_RETURN_ON_ERROR(uac_host_interface_try_lock(uac_iface, DEFAULT_CTRL_XFER_TIMEOUT_MS), "UAC Interface is busy by other task");
     if (UAC_INTERFACE_STATE_ACTIVE == uac_iface->state) {
-        UAC_GOTO_ON_ERROR(uac_host_interface_suspend(uac_iface), "Unable to disable UAC Interface");
+        UAC_GOTO_ON_ERROR(uac_host_interface_pause(uac_iface), "Unable to disable UAC Interface");
     }
 
     if (UAC_INTERFACE_STATE_READY == uac_iface->state) {
@@ -2372,8 +2372,8 @@ esp_err_t uac_host_device_start(uac_host_device_handle_t uac_dev_handle, const u
     UAC_GOTO_ON_ERROR(uac_host_interface_claim_and_prepare_transfer(iface), "Unable to claim Interface");
     iface_claimed = true;
 
-    if (!(iface->flags & FLAG_STREAM_SUSPEND_AFTER_START)) {
-        UAC_GOTO_ON_ERROR(uac_host_interface_resume(iface), "Unable to enable UAC Interface");
+    if (!(iface->flags & FLAG_STREAM_PAUSE_AFTER_START)) {
+        UAC_GOTO_ON_ERROR(uac_host_interface_unpause(iface), "Unable to enable UAC Interface");
     }
     uac_host_interface_unlock(iface);
     return ESP_OK;
@@ -2386,7 +2386,7 @@ esp_err_t uac_host_device_start(uac_host_device_handle_t uac_dev_handle, const u
     return ret;
 }
 
-esp_err_t uac_host_device_suspend(uac_host_device_handle_t uac_dev_handle)
+esp_err_t uac_host_device_pause(uac_host_device_handle_t uac_dev_handle)
 {
     uac_iface_t *iface = get_iface_by_handle(uac_dev_handle);
     UAC_RETURN_ON_INVALID_ARG(iface);
@@ -2398,7 +2398,7 @@ esp_err_t uac_host_device_suspend(uac_host_device_handle_t uac_dev_handle)
     }
     esp_err_t ret = ESP_OK;
     UAC_GOTO_ON_FALSE((UAC_INTERFACE_STATE_ACTIVE == iface->state), ESP_ERR_INVALID_STATE, "device not active");
-    UAC_GOTO_ON_ERROR(uac_host_interface_suspend(iface), "Unable to disable UAC Interface");
+    UAC_GOTO_ON_ERROR(uac_host_interface_pause(iface), "Unable to disable UAC Interface");
 
     uac_host_interface_unlock(iface);
     return ESP_OK;
@@ -2408,7 +2408,7 @@ esp_err_t uac_host_device_suspend(uac_host_device_handle_t uac_dev_handle)
     return ret;
 }
 
-esp_err_t uac_host_device_resume(uac_host_device_handle_t uac_dev_handle)
+esp_err_t uac_host_device_unpause(uac_host_device_handle_t uac_dev_handle)
 {
     uac_iface_t *iface = get_iface_by_handle(uac_dev_handle);
     UAC_RETURN_ON_INVALID_ARG(iface);
@@ -2421,7 +2421,7 @@ esp_err_t uac_host_device_resume(uac_host_device_handle_t uac_dev_handle)
 
     esp_err_t ret = ESP_OK;
     UAC_GOTO_ON_FALSE((UAC_INTERFACE_STATE_READY == iface->state), ESP_ERR_INVALID_STATE, "device not ready");
-    UAC_GOTO_ON_ERROR(uac_host_interface_resume(iface), "Unable to enable UAC Interface");
+    UAC_GOTO_ON_ERROR(uac_host_interface_unpause(iface), "Unable to enable UAC Interface");
 
     uac_host_interface_unlock(iface);
     return ESP_OK;
@@ -2439,7 +2439,7 @@ esp_err_t uac_host_device_stop(uac_host_device_handle_t uac_dev_handle)
     esp_err_t ret = ESP_OK;
     UAC_RETURN_ON_ERROR(uac_host_interface_try_lock(iface, DEFAULT_CTRL_XFER_TIMEOUT_MS), "Unable to lock UAC Interface");
     if (UAC_INTERFACE_STATE_ACTIVE == iface->state) {
-        UAC_GOTO_ON_ERROR(uac_host_interface_suspend(iface), "Unable to disable UAC Interface");
+        UAC_GOTO_ON_ERROR(uac_host_interface_pause(iface), "Unable to disable UAC Interface");
     }
 
     if (UAC_INTERFACE_STATE_READY == iface->state) {