Skip to content

refactor(uac_host): Suspend/Resume public API terminology #363

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
peter-marcisovsky wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

refactor(uac_host): Suspend/Resume public API terminology #363

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions host/class/uac/usb_host_uac/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions host/class/uac/usb_host_uac/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
10 changes: 5 additions & 5 deletions host/class/uac/usb_host_uac/examples/audio_player/main/main.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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");
}
}
}
Expand Down Expand Up @@ -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;
}
Expand Down
16 changes: 8 additions & 8 deletions host/class/uac/usb_host_uac/include/usb/uac_host.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 */

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
24 changes: 12 additions & 12 deletions host/class/uac/usb_host_uac/test_app/main/test_host_uac.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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));

Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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);
}
Expand Down Expand Up @@ -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));
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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);
}
Expand Down
36 changes: 18 additions & 18 deletions host/class/uac/usb_host_uac/uac_host.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

/**
Expand Down Expand Up @@ -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;
Expand All @@ -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;
Expand All @@ -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);
Expand All @@ -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);
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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;
Expand All @@ -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);
Expand All @@ -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;
Expand All @@ -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);
Expand All @@ -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;
Expand All @@ -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) {
Expand Down
Loading