Skip to content
95 changes: 75 additions & 20 deletions ports/espressif/common-hal/audiobusio/__init__.c
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@

#include "common-hal/audiobusio/__init__.h"
#include "bindings/espidf/__init__.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_task.h"
#include "freertos/semphr.h"
#include "soc/soc_caps.h"
#if defined(SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE) && SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
#include "esp_cache.h"
Expand All @@ -27,6 +27,28 @@
#define CIRCUITPY_BUFFER_SIZE (I2S_DMA_BUFFER_MAX_SIZE / 4)
// The number of output channels is fixed at 2
#define CIRCUITPY_OUTPUT_SLOTS (2)
// Refill runs on its own task, above the LVGL render task, so a long display render can't starve
// it.
#define I2S_FILL_TASK_PRIORITY (ESP_TASK_MAIN_PRIO + 2)
#define I2S_FILL_TASK_STACK_SIZE (8192)

// Held by a fill task while it refills, and by any code that changes a sample being played (see
// audiocore_lock()). Recursive because a sample may take it again itself while it fills. Created
// with the first I2SOut, from the FreeRTOS heap rather than static RAM, which is tight on the
// ESP32-S2. Until then there is no fill task to keep out.
static SemaphoreHandle_t audiocore_mutex;

void audiocore_lock(void) {
if (audiocore_mutex != NULL) {
xSemaphoreTakeRecursive(audiocore_mutex, portMAX_DELAY);
}
}

void audiocore_unlock(void) {
if (audiocore_mutex != NULL) {
xSemaphoreGiveRecursive(audiocore_mutex);
}
}

static void i2s_fill_buffer(i2s_t *self) {
if (self->next_buffer_size == 0) {
Expand Down Expand Up @@ -116,29 +138,35 @@ static void i2s_fill_buffer(i2s_t *self) {
self->next_buffer_size = 0;
}

static void i2s_callback_fun(void *self_in) {
static void i2s_fill_task(void *self_in) {
i2s_t *self = self_in;
#if defined(SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE) && SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
void *buffer = self->next_buffer;
size_t buffer_size = self->next_buffer_size;
#endif
i2s_fill_buffer(self);
#if defined(SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE) && SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
// Internal RAM is cached. IDF writes the buffer back right after on_sent, before
// we fill it here, so write it back again or the DMA plays stale data.
if (buffer != NULL) {
esp_cache_msync(buffer, buffer_size, ESP_CACHE_MSYNC_FLAG_DIR_C2M);
for (;;) {
ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
audiocore_lock();
#if defined(SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE) && SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
void *buffer = self->next_buffer;
size_t buffer_size = self->next_buffer_size;
#endif
i2s_fill_buffer(self);
#if defined(SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE) && SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
// Internal RAM is cached. IDF writes the buffer back right after on_sent, before
// we fill it here, so write it back again or the DMA plays stale data.
if (buffer != NULL) {
esp_cache_msync(buffer, buffer_size, ESP_CACHE_MSYNC_FLAG_DIR_C2M);
}
#endif
audiocore_unlock();
}
#endif
}

static bool i2s_event_interrupt(i2s_chan_handle_t handle, i2s_event_data_t *event, void *self_in) {
i2s_t *self = self_in;
self->underrun = self->underrun || self->next_buffer != NULL;
self->next_buffer = (int16_t *)event->dma_buf;
self->next_buffer_size = event->size;
background_callback_add(&self->callback, i2s_callback_fun, self_in);
return false;
BaseType_t woken = pdFALSE;
vTaskNotifyGiveFromISR(self->fill_task, &woken);
return woken == pdTRUE;
}

void port_i2s_allocate_init(i2s_t *self, bool left_justified) {
Expand All @@ -152,6 +180,19 @@ void port_i2s_allocate_init(i2s_t *self, bool left_justified) {
if (err == ESP_ERR_NOT_FOUND) {
mp_raise_RuntimeError(MP_ERROR_TEXT("Peripheral in use"));
}
if (audiocore_mutex == NULL) {
audiocore_mutex = xSemaphoreCreateRecursiveMutex();
if (audiocore_mutex == NULL) {
i2s_del_channel(self->handle);
m_malloc_fail(sizeof(StaticSemaphore_t));
}
}
self->fill_task = NULL;
if (xTaskCreatePinnedToCore(i2s_fill_task, "i2s fill", I2S_FILL_TASK_STACK_SIZE, self,
I2S_FILL_TASK_PRIORITY, &self->fill_task, CONFIG_ESP_MAIN_TASK_AFFINITY) != pdPASS) {
port_i2s_deinit(self);
m_malloc_fail(I2S_FILL_TASK_STACK_SIZE);
}
self->playing = false;
self->paused = false;
self->stopping = false;
Expand All @@ -169,12 +210,27 @@ void port_i2s_deinit(i2s_t *self) {
port_i2s_stop(self);
i2s_del_channel(self->handle);
self->handle = NULL;
if (self->fill_task != NULL) {
// The channel is gone, so nothing wakes the task again. Holding the lock means the task
// isn't mid-fill.
audiocore_lock();
vTaskDelete(self->fill_task);
self->fill_task = NULL;
audiocore_unlock();
}
}

void port_i2s_play(i2s_t *self, mp_obj_t sample, bool loop) {
audiosample_check(sample);
// Pause to disable the I2S channel so we can adjust the clock.
port_i2s_pause(self);
// Set the clock first, because it can raise and nothing below may raise while locked.
uint32_t sample_rate = audiosample_get_sample_rate(sample);
i2s_std_clk_config_t clk_config = I2S_STD_CLK_DEFAULT_CONFIG(sample_rate);
CHECK_ESP_RESULT(i2s_channel_reconfig_std_clock(self->handle, &clk_config));
// Keep refill out while the sample changes. Samples report load errors by return value, so
// nothing here raises with the lock held.
audiocore_lock();
self->sample = sample;
self->loop = loop;
self->bytes_per_sample = audiosample_get_bits_per_sample(sample) / 8;
Expand All @@ -192,10 +248,6 @@ void port_i2s_play(i2s_t *self, mp_obj_t sample, bool loop) {

audiosample_reset_buffer(self->sample, false, 0);

uint32_t sample_rate = audiosample_get_sample_rate(sample);
i2s_std_clk_config_t clk_config = I2S_STD_CLK_DEFAULT_CONFIG(sample_rate);
CHECK_ESP_RESULT(i2s_channel_reconfig_std_clock(self->handle, &clk_config));

// preload the data
self->playing = true;
self->paused = false;
Expand All @@ -215,6 +267,7 @@ void port_i2s_play(i2s_t *self, mp_obj_t sample, bool loop) {
i2s_channel_preload_data(self->handle, &starting_frame, sizeof(uint32_t), &bytes_loaded);
preloaded += bytes_loaded;
}
audiocore_unlock();

// enable the channel
i2s_channel_enable(self->handle);
Expand All @@ -235,10 +288,12 @@ bool port_i2s_paused(i2s_t *self) {

void port_i2s_stop(i2s_t *self) {
port_i2s_pause(self);
audiocore_lock();
self->sample = NULL;
self->playing = false;
self->stopping = false;
self->last_buffer = false;
audiocore_unlock();
}

void port_i2s_pause(i2s_t *self) {
Expand Down
6 changes: 3 additions & 3 deletions ports/espressif/common-hal/audiobusio/__init__.h
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@

#include "py/obj.h"

#include "supervisor/background_callback.h"

#include "driver/i2s_std.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

typedef struct {
mp_obj_t *sample;
Expand All @@ -28,7 +28,7 @@ typedef struct {
void *next_buffer;
size_t next_buffer_size;
i2s_chan_handle_t handle;
background_callback_t callback;
TaskHandle_t fill_task; // Refills DMA buffers when the I2S interrupt wakes it.
bool underrun;
} i2s_t;

Expand Down
2 changes: 1 addition & 1 deletion ports/espressif/esp-idf
6 changes: 6 additions & 0 deletions shared-module/audiocore/__init__.c
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,12 @@
#include "shared-bindings/audiomixer/Mixer.h"
#include "shared-module/audiomixer/Mixer.h"

MP_WEAK void audiocore_lock(void) {
}

MP_WEAK void audiocore_unlock(void) {
}

void audiosample_reset_buffer(mp_obj_t sample_obj, bool single_channel_output, uint8_t audio_channel) {
const audiosample_p_t *proto = mp_proto_get_or_throw(MP_QSTR_protocol_audiosample, sample_obj);
if (audiosample_deinited(audiosample_cast_obj(sample_obj))) {
Expand Down
7 changes: 7 additions & 0 deletions shared-module/audiocore/__init__.h
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,13 @@ static inline uint8_t audiosample_get_channel_count(audiosample_base_t *self) {
return self->channel_count;
}

// Ports that fetch sample buffers on their own task, not the CircuitPython task, hold this lock
// while they fetch. Code that changes a sample that may be playing holds it too, so the fetch
// never sees the sample half changed. Calls nest. Never call from an interrupt. The default does
// nothing, for ports that fetch on the CircuitPython task.
void audiocore_lock(void);
void audiocore_unlock(void);

void audiosample_reset_buffer(mp_obj_t sample_obj, bool single_channel_output, uint8_t audio_channel);
audioio_get_buffer_result_t audiosample_get_buffer(mp_obj_t sample_obj,
bool single_channel_output,
Expand Down
28 changes: 24 additions & 4 deletions shared-module/audiomp3/MP3Decoder.c
Original file line number Diff line number Diff line change
Expand Up @@ -115,16 +115,19 @@ static void stream_set_blocking(audiomp3_mp3file_obj_t *self, bool block_ok) {
* false otherwise. (The input buffer will be padded to the end with
* 0 bytes, which do not interfere with MP3 decoding)
*
* Raises OSError if stream_read fails.
* Sets self->read_error and self->eof if stream_read fails, instead of raising, because this also
* runs where nothing can catch an exception (a port's audio fill task).
*
* Sets self->eof if any read of the file returns 0 bytes
*/
static bool mp3file_update_inbuf_always(audiomp3_mp3file_obj_t *self, bool block_ok) {
// Every return from this function must be preceded by background_callback_allow();
background_callback_prevent();
audiocore_lock();

if (self->eof || INPUT_BUFFER_SPACE(self->inbuf) == 0) {
bool result = INPUT_BUFFER_AVAILABLE(self->inbuf) > 0;
audiocore_unlock();
background_callback_allow();
return result;
}
Expand All @@ -151,8 +154,8 @@ static bool mp3file_update_inbuf_always(audiomp3_mp3file_obj_t *self, bool block
break;
}
self->eof = true;
background_callback_allow();
mp_raise_OSError(errcode);
self->read_error = errcode;
break;
}

if (n_read == 0) {
Expand All @@ -169,6 +172,7 @@ static bool mp3file_update_inbuf_always(audiomp3_mp3file_obj_t *self, bool block
// Return true iff there are at least some useful bytes in the buffer
bool result = INPUT_BUFFER_AVAILABLE(self->inbuf) > 0;

audiocore_unlock();
background_callback_allow();
return result;
}
Expand Down Expand Up @@ -358,6 +362,7 @@ static bool mp3file_set_file_and_get_frame_info(audiomp3_mp3file_obj_t *self, mp

INPUT_BUFFER_CLEAR(self->inbuf);
self->eof = 0;
self->read_error = 0;

self->block_ok = false;
stream_set_blocking(self, true);
Expand Down Expand Up @@ -388,6 +393,7 @@ static bool mp3file_set_file_and_get_frame_info(audiomp3_mp3file_obj_t *self, mp

void common_hal_audiomp3_mp3file_set_file(audiomp3_mp3file_obj_t *self, mp_obj_t stream) {
background_callback_prevent();
audiocore_lock();

MP3FrameInfo fi;
bool result;
Expand All @@ -396,10 +402,15 @@ void common_hal_audiomp3_mp3file_set_file(audiomp3_mp3file_obj_t *self, mp_obj_t
result = mp3file_set_file_and_get_frame_info(self, stream, &fi);
nlr_pop();
} else {
audiocore_unlock();
background_callback_allow();
nlr_jump(nlr.ret_val);
}
audiocore_unlock();
background_callback_allow();
if (self->read_error) {
mp_raise_OSError(self->read_error);
}
if (!result) {
mp_raise_msg(&mp_type_RuntimeError,
MP_ERROR_TEXT("Failed to parse MP3 file"));
Expand All @@ -416,6 +427,7 @@ void common_hal_audiomp3_mp3file_set_file(audiomp3_mp3file_obj_t *self, mp_obj_t
}

void common_hal_audiomp3_mp3file_deinit(audiomp3_mp3file_obj_t *self) {
audiocore_lock();
audiosample_mark_deinit(&self->base);
if (self->decoder) {
MP3FreeDecoder(self->decoder);
Expand All @@ -427,6 +439,7 @@ void common_hal_audiomp3_mp3file_deinit(audiomp3_mp3file_obj_t *self) {
self->stream = mp_const_none;
self->settimeout_args[0] = MP_OBJ_NULL;
self->samples_decoded = 0;
audiocore_unlock();
}

void audiomp3_mp3file_reset_buffer(audiomp3_mp3file_obj_t *self,
Expand All @@ -438,14 +451,17 @@ void audiomp3_mp3file_reset_buffer(audiomp3_mp3file_obj_t *self,
// We don't reset the buffer index in case we're looping and we have an odd number of buffer
// loads
background_callback_prevent();
audiocore_lock();
if (self->eof && stream_lseek(self->stream, 0, SEEK_SET) == 0) {
INPUT_BUFFER_CLEAR(self->inbuf);
self->eof = 0;
self->read_error = 0;
self->samples_decoded = 0;
self->other_channel = -1;
mp3file_skip_id3v2(self, false);
mp3file_find_sync_word(self, false);
}
audiocore_unlock();
background_callback_allow();
}

Expand All @@ -461,6 +477,10 @@ audioio_get_buffer_result_t audiomp3_mp3file_get_buffer(audiomp3_mp3file_obj_t *
}
return GET_BUFFER_ERROR;
}
if (self->read_error) {
*buffer_length = 0;
return GET_BUFFER_ERROR;
}
if (!single_channel_output) {
channel = 0;
}
Expand Down Expand Up @@ -489,7 +509,7 @@ audioio_get_buffer_result_t audiomp3_mp3file_get_buffer(audiomp3_mp3file_obj_t *
if (!mp3file_find_sync_word(self, false)) {
memset(buffer, 0, self->base.max_buffer_length);
*buffer_length = 0;
return self->eof ? GET_BUFFER_DONE : GET_BUFFER_ERROR;
return self->eof && !self->read_error ? GET_BUFFER_DONE : GET_BUFFER_ERROR;
}
int bytes_left = BYTES_LEFT(self);
uint8_t *inbuf = READ_PTR(self);
Expand Down
1 change: 1 addition & 0 deletions shared-module/audiomp3/MP3Decoder.h
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ typedef struct {
uint8_t buffer_index;
bool eof;
bool block_ok;
int read_error; // errno from a failed stream read, 0 if none. Raised from Python context.
mp_obj_t settimeout_args[3];

int8_t other_channel;
Expand Down
Loading