diff --git a/host/class/uac/usb_host_uac/CHANGELOG.md b/host/class/uac/usb_host_uac/CHANGELOG.md index 89e3d8515..402b2f02d 100644 --- a/host/class/uac/usb_host_uac/CHANGELOG.md +++ b/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 diff --git a/host/class/uac/usb_host_uac/README.md b/host/class/uac/usb_host_uac/README.md index beb70e295..0470929b3 100644 --- a/host/class/uac/usb_host_uac/README.md +++ b/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: diff --git a/host/class/uac/usb_host_uac/examples/audio_player/main/main.c b/host/class/uac/usb_host_uac/examples/audio_player/main/main.c index d867d1a72..caabbd817 100644 --- a/host/class/uac/usb_host_uac/examples/audio_player/main/main.c +++ b/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,8 +396,8 @@ 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, @@ -405,7 +405,7 @@ static void uac_lib_task(void *arg) .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; } diff --git a/host/class/uac/usb_host_uac/include/usb/uac_host.h b/host/class/uac/usb_host_uac/include/usb/uac_host.h index 3fe8a7880..bef12534e 100644 --- a/host/class/uac/usb_host_uac/include/usb/uac_host.h +++ b/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,7 +318,7 @@ 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 @@ -326,10 +326,10 @@ esp_err_t uac_host_device_start(uac_host_device_handle_t uac_dev_handle, const u * - 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 @@ -337,7 +337,7 @@ esp_err_t uac_host_device_suspend(uac_host_device_handle_t uac_dev_handle); * - 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 diff --git a/host/class/uac/usb_host_uac/test_app/main/test_host_uac.c b/host/class/uac/usb_host_uac/test_app/main/test_host_uac.c index 10ac1de77..8c7fa4f7c 100644 --- a/host/class/uac/usb_host_uac/test_app/main/test_host_uac.c +++ b/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); } diff --git a/host/class/uac/usb_host_uac/uac_host.c b/host/class/uac/usb_host_uac/uac_host.c index a62fee6c4..11b12b64d 100644 --- a/host/class/uac/usb_host_uac/uac_host.c +++ b/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) {