From d0ca24c6ae4014a3e9068565eccf237a995ca660 Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Thu, 19 Nov 2026 09:15:32 -0800 Subject: [PATCH 1/9] espressif: update esp-idf to give the SD controller lock back sd_host_del_sdmmc_controller() deleted its mutex while holding it, which left the calling task counted as holding a mutex forever. That task then kept any priority it inherited. See espressif/esp-idf#19402. Co-Authored-By: Claude Opus 5.5 --- ports/espressif/esp-idf | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ports/espressif/esp-idf b/ports/espressif/esp-idf index 5b29db3c115..a17cc0560b8 160000 --- a/ports/espressif/esp-idf +++ b/ports/espressif/esp-idf @@ -1 +1 @@ -Subproject commit 5b29db3c11506dc79366d544f9c8358a68bc5dfb +Subproject commit a17cc0560b847618c48036a6f605c63d985fbb23 From 5c6ec8caaa510c45b7b1a1c653663273d7dceb79 Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Wed, 18 Nov 2026 14:39:49 -0800 Subject: [PATCH 2/9] lvgl: yield during display auto-refresh too Framebuffer auto-refresh now renders on the CircuitPython thread from a background callback, the way BusDisplay already does. Both allow other callbacks to run while they render, like the legacy framebufferio, so audio can refill. A refresh skipped because another render is yielding is queued again instead of dropped. Co-Authored-By: Claude Opus 5.5 --- ports/espressif/supervisor/lvgl_port.c | 31 +++++++-- .../common-hal/zephyr_display/lvgl/Display.c | 2 +- shared-module/displayio/lvgl/Group.c | 67 ++++++++++++------- shared-module/displayio/lvgl/lvgl_internal.h | 21 ++++-- .../framebufferio/lvgl/FramebufferDisplay.c | 10 +-- 5 files changed, 85 insertions(+), 46 deletions(-) diff --git a/ports/espressif/supervisor/lvgl_port.c b/ports/espressif/supervisor/lvgl_port.c index 0c5f6bd260d..0c4a29301d3 100644 --- a/ports/espressif/supervisor/lvgl_port.c +++ b/ports/espressif/supervisor/lvgl_port.c @@ -32,9 +32,12 @@ static TaskHandle_t lvgl_task_handle = NULL; static volatile uint32_t lvgl_frame_generation = 0; static uint32_t lvgl_frame_seen = 0; -// BusDisplay flushes stay on the CircuitPython thread. Its LVGL refresh timer is proxied to this -// background callback, so no supervisor tick is involved. +// Display auto-refreshes render on the CircuitPython thread, from these background callbacks. +// BusDisplay's LVGL refresh timer is proxied to the first; a framebuffer frame boundary queues the +// second. Like the legacy framebufferio, they allow other callbacks (audio refill) to run while +// they render. static background_callback_t lvgl_cp_refresh_cb; +static background_callback_t lvgl_cp_paced_refresh_cb; // LVGL's allocator hooks (LV_USE_STDLIB_MALLOC == LV_STDLIB_CUSTOM). Displays and // their buffers outlive the VM, so they come from the port heap. @@ -153,7 +156,23 @@ void displayio_lvgl_port_unlock(void) { static void lvgl_cp_refresh(void *unused) { LV_UNUSED(unused); - displayio_lvgl_refresh_unsafe_displays(); + background_callback_allow(); + bool rendered = displayio_lvgl_refresh_unsafe_displays(true); + background_callback_prevent(); + if (!rendered) { + // Another render was running background tasks. Try again after it. + background_callback_add(&lvgl_cp_refresh_cb, lvgl_cp_refresh, NULL); + } +} + +static void lvgl_cp_paced_refresh(void *unused) { + LV_UNUSED(unused); + background_callback_allow(); + bool rendered = displayio_lvgl_refresh_paced_displays(true); + background_callback_prevent(); + if (!rendered) { + background_callback_add(&lvgl_cp_paced_refresh_cb, lvgl_cp_paced_refresh, NULL); + } } // BusDisplay's LVGL refresh timer normally flushes on the render task. Replace its callback with @@ -184,8 +203,8 @@ IRAM_ATTR void displayio_lvgl_port_frame_boundary(void) { return; } // UVC invokes its frame callback from a background task on the CircuitPython thread. Render - // directly there; there is no task handoff. - displayio_lvgl_refresh_paced_displays(); + // directly there, before the frame is converted; there is no task handoff. + displayio_lvgl_refresh_paced_displays(false); } static void lvgl_task(void *arg) { @@ -211,7 +230,7 @@ static void lvgl_task(void *arg) { uint32_t frame_generation = lvgl_frame_generation; if (frame_generation != lvgl_frame_seen) { lvgl_frame_seen = frame_generation; - displayio_lvgl_refresh_paced_displays(); + background_callback_add(&lvgl_cp_paced_refresh_cb, lvgl_cp_paced_refresh, NULL); } } } diff --git a/ports/zephyr-cp/common-hal/zephyr_display/lvgl/Display.c b/ports/zephyr-cp/common-hal/zephyr_display/lvgl/Display.c index 3f34c0957a0..a9c6d6c495e 100644 --- a/ports/zephyr-cp/common-hal/zephyr_display/lvgl/Display.c +++ b/ports/zephyr-cp/common-hal/zephyr_display/lvgl/Display.c @@ -67,7 +67,7 @@ void displayio_lvgl_port_install_busdisplay_refresh(lv_display_t *display) { void displayio_lvgl_port_frame_boundary(void) { // No Zephyr framebuffer exposes a frame callback yet. If one does, this must be made ISR // safe (for example by scheduling the refresh on the LVGL workqueue). - displayio_lvgl_refresh_paced_displays(); + displayio_lvgl_refresh_paced_displays(false); } static void zephyr_display_lvgl_flush_argb_alpha0(lv_display_t *display, const lv_area_t *area, diff --git a/shared-module/displayio/lvgl/Group.c b/shared-module/displayio/lvgl/Group.c index 8580748d6e0..dcc7d1079f4 100644 --- a/shared-module/displayio/lvgl/Group.c +++ b/shared-module/displayio/lvgl/Group.c @@ -52,6 +52,36 @@ static displayio_group_t *cp_lvgl_root_group = NULL; static bool cp_lvgl_inited = false; bool displayio_lvgl_refresh_yield = false; +// Set while a display renders on the CircuitPython thread. A background callback run from inside +// that render (see displayio_lvgl_refresh_yield) must not start a nested one: LVGL keeps the +// display being rendered in a global and doesn't restore it. +static bool cp_lvgl_rendering = false; + +static bool _render_begin(bool yield) { + if (cp_lvgl_rendering) { + return false; + } + cp_lvgl_rendering = true; + displayio_lvgl_lock(); + displayio_lvgl_refresh_yield = yield; + return true; +} + +static void _render_end(void) { + displayio_lvgl_refresh_yield = false; + displayio_lvgl_unlock(); + cp_lvgl_rendering = false; +} + +bool displayio_lvgl_render_now(lv_display_t *display, bool yield) { + if (!_render_begin(yield)) { + return false; + } + lv_refr_now(display); + _render_end(); + return true; +} + // The port lock is recursive. Keeping the recursion at the port instead of counting here matters // once LVGL renders on its own task: a shared depth counter would let the render task believe it // owns a lock that the CircuitPython task is holding. @@ -170,18 +200,12 @@ bool displayio_lvgl_auto_refresh(void) { return true; } -// Render the displays that can't run on the render task. The guard keeps the proxy from -// re-entering LVGL rendering if a background callback is processed while a refresh is already -// active on the CircuitPython thread, including an explicit display.refresh() that is running -// background tasks mid-render. -void displayio_lvgl_refresh_unsafe_displays(void) { +// Render the displays that can't run on the render task. +bool displayio_lvgl_refresh_unsafe_displays(bool yield) { #if CIRCUITPY_BUSDISPLAY - static bool refreshing = false; - if (refreshing || displayio_lvgl_refresh_yield) { - return; + if (!_render_begin(yield)) { + return false; } - refreshing = true; - displayio_lvgl_lock(); for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) { mp_const_obj_t display_type = displays[i].display_base.type; if (display_type != &busdisplay_busdisplay_type) { @@ -192,24 +216,17 @@ void displayio_lvgl_refresh_unsafe_displays(void) { lv_refr_now(busdisplay->lv_display); } } - displayio_lvgl_unlock(); - refreshing = false; + _render_end(); #endif + return true; } -// Render the framebuffer displays that pace themselves from a frame boundary. Like the BusDisplay -// proxy, this runs on the CircuitPython thread and takes the LVGL lock; a frame callback may be -// running on the render task at the same time, so the lock serializes them. -void displayio_lvgl_refresh_paced_displays(void) { +// Render the framebuffer displays that pace themselves from a frame boundary. +bool displayio_lvgl_refresh_paced_displays(bool yield) { #if CIRCUITPY_FRAMEBUFFERIO - static bool refreshing = false; - // An explicit display.refresh() runs background tasks while it renders. A frame callback - // queued among them must not start a nested render; it draws at the next frame instead. - if (refreshing || displayio_lvgl_refresh_yield) { - return; + if (!_render_begin(yield)) { + return false; } - refreshing = true; - displayio_lvgl_lock(); for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) { mp_const_obj_t display_type = displays[i].display_base.type; if (display_type != &framebufferio_framebufferdisplay_type) { @@ -220,9 +237,9 @@ void displayio_lvgl_refresh_paced_displays(void) { lv_refr_now(display->lv_display); } } - displayio_lvgl_unlock(); - refreshing = false; + _render_end(); #endif + return true; } void displayio_lvgl_init(void) { diff --git a/shared-module/displayio/lvgl/lvgl_internal.h b/shared-module/displayio/lvgl/lvgl_internal.h index 8facf95c06f..6f3e529cecc 100644 --- a/shared-module/displayio/lvgl/lvgl_internal.h +++ b/shared-module/displayio/lvgl/lvgl_internal.h @@ -69,16 +69,23 @@ void displayio_lvgl_register_display(lv_display_t *display); bool displayio_lvgl_auto_refresh(void); // Render displays that can't flush from the LVGL task (currently BusDisplay when the port asks -// for it). Called on the CircuitPython thread by the port's proxy, under the LVGL lock. -void displayio_lvgl_refresh_unsafe_displays(void); +// for it). Called on the CircuitPython thread by the port's proxy. With `yield`, the render runs +// background tasks between steps, so the caller must be in a background callback that has called +// background_callback_allow(). Returns false, without rendering, when another render on this +// thread is already in progress; the caller should try again later. +bool displayio_lvgl_refresh_unsafe_displays(bool yield); // Render the framebuffer displays that pace themselves from a frame boundary. Called on the -// CircuitPython thread (directly or from the render task after an ISR notification), under the -// LVGL lock. -void displayio_lvgl_refresh_paced_displays(void); +// CircuitPython thread. `yield` and the return value are as for +// displayio_lvgl_refresh_unsafe_displays(). +bool displayio_lvgl_refresh_paced_displays(bool yield); -// True while an explicit display.refresh() renders on the CircuitPython thread. Long -// render steps (TileGrid compose, display flush) run background tasks when it is set. +// Render one display now on the CircuitPython thread, as display.refresh() does. `yield` and the +// return value are as above. +bool displayio_lvgl_render_now(lv_display_t *display, bool yield); + +// True while a render on the CircuitPython thread may run background tasks. Long render steps +// (TileGrid compose, display flush) run them when it is set, so audio can refill. extern bool displayio_lvgl_refresh_yield; // Attach/detach the compositor's root group. Implemented in lvgl/Group.c. NULL detach. diff --git a/shared-module/framebufferio/lvgl/FramebufferDisplay.c b/shared-module/framebufferio/lvgl/FramebufferDisplay.c index e3bdf34629d..f31ccd4c62d 100644 --- a/shared-module/framebufferio/lvgl/FramebufferDisplay.c +++ b/shared-module/framebufferio/lvgl/FramebufferDisplay.c @@ -224,7 +224,7 @@ static void framebufferio_lvgl_flush_cb(lv_display_t *disp, const lv_area_t *are lv_display_flush_ready(disp); // A refresh can take longer than the audio buffers last. Like the legacy - // framebufferio, let background tasks run between chunks of an explicit refresh. + // framebufferio, let background tasks run between chunks. if (displayio_lvgl_refresh_yield) { RUN_BACKGROUND_TASKS; } @@ -493,12 +493,8 @@ bool common_hal_framebufferio_framebufferdisplay_refresh(framebufferio_framebuff } self->first_manual_refresh = false; if (self->lv_display != NULL) { - // The renderer refreshes on its own thread too, so this has to exclude it. - displayio_lvgl_lock(); - displayio_lvgl_refresh_yield = true; - lv_refr_now(self->lv_display); - displayio_lvgl_refresh_yield = false; - displayio_lvgl_unlock(); + // Yield like the legacy framebufferio so audio can refill during a long render. + displayio_lvgl_render_now(self->lv_display, true); } self->core.last_refresh = supervisor_ticks_ms64(); return true; From 5c75ccc8e7c54aaef78eb8c5823843874ae66d2c Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Thu, 19 Nov 2026 09:39:34 -0800 Subject: [PATCH 3/9] lvgl: tidy auto-refresh yield comments Say what a yielding render needs from its caller instead of naming one kind of caller, say why the UVC frame boundary renders without yielding, comment the paced re-queue like its twin, and drop history from the yield comments. Co-Authored-By: Claude Opus 5.5 --- ports/espressif/supervisor/lvgl_port.c | 10 ++++++---- shared-module/displayio/lvgl/lvgl_internal.h | 7 ++++--- shared-module/framebufferio/lvgl/FramebufferDisplay.c | 2 +- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/ports/espressif/supervisor/lvgl_port.c b/ports/espressif/supervisor/lvgl_port.c index 0c4a29301d3..f217ed4a96f 100644 --- a/ports/espressif/supervisor/lvgl_port.c +++ b/ports/espressif/supervisor/lvgl_port.c @@ -34,8 +34,7 @@ static uint32_t lvgl_frame_seen = 0; // Display auto-refreshes render on the CircuitPython thread, from these background callbacks. // BusDisplay's LVGL refresh timer is proxied to the first; a framebuffer frame boundary queues the -// second. Like the legacy framebufferio, they allow other callbacks (audio refill) to run while -// they render. +// second. They allow other callbacks (audio refill) to run while they render. static background_callback_t lvgl_cp_refresh_cb; static background_callback_t lvgl_cp_paced_refresh_cb; @@ -171,6 +170,7 @@ static void lvgl_cp_paced_refresh(void *unused) { bool rendered = displayio_lvgl_refresh_paced_displays(true); background_callback_prevent(); if (!rendered) { + // Another render was running background tasks. Try again after it. background_callback_add(&lvgl_cp_paced_refresh_cb, lvgl_cp_paced_refresh, NULL); } } @@ -203,7 +203,9 @@ IRAM_ATTR void displayio_lvgl_port_frame_boundary(void) { return; } // UVC invokes its frame callback from a background task on the CircuitPython thread. Render - // directly there, before the frame is converted; there is no task handoff. + // directly there, before the frame is converted; there is no task handoff. No yield: other + // callbacks, including this one, must not run before the frame is converted. If another render + // is in progress this frame is skipped, and the next frame boundary renders. displayio_lvgl_refresh_paced_displays(false); } @@ -266,7 +268,7 @@ void displayio_lvgl_port_init(void) { // The task must run above the CircuitPython task so a tight Python loop can't starve // rendering. Pin it to the CircuitPython core as well: background_callback_add() (used by the - // BusDisplay proxy) is interrupt-safe on a single core, and sharing the core keeps it from + // BusDisplay proxy and the frame boundary) is interrupt-safe on a single core, and sharing the core keeps it from // racing the CircuitPython thread's callback list. A recursive mutex (priority inheritance) // keeps that from blocking the main task for long. 16 KB covers the draw paths plus LVGL's // internal compositor state; 8 KB overflowed on complex screens. diff --git a/shared-module/displayio/lvgl/lvgl_internal.h b/shared-module/displayio/lvgl/lvgl_internal.h index 6f3e529cecc..c30b7b6b405 100644 --- a/shared-module/displayio/lvgl/lvgl_internal.h +++ b/shared-module/displayio/lvgl/lvgl_internal.h @@ -70,9 +70,10 @@ bool displayio_lvgl_auto_refresh(void); // Render displays that can't flush from the LVGL task (currently BusDisplay when the port asks // for it). Called on the CircuitPython thread by the port's proxy. With `yield`, the render runs -// background tasks between steps, so the caller must be in a background callback that has called -// background_callback_allow(). Returns false, without rendering, when another render on this -// thread is already in progress; the caller should try again later. +// background tasks between steps, so background callbacks must not be prevented at the call (a +// background callback calls background_callback_allow() first). Returns false, without +// rendering, when another render on this thread is already in progress; the caller should try +// again later. bool displayio_lvgl_refresh_unsafe_displays(bool yield); // Render the framebuffer displays that pace themselves from a frame boundary. Called on the diff --git a/shared-module/framebufferio/lvgl/FramebufferDisplay.c b/shared-module/framebufferio/lvgl/FramebufferDisplay.c index f31ccd4c62d..3e912d4370c 100644 --- a/shared-module/framebufferio/lvgl/FramebufferDisplay.c +++ b/shared-module/framebufferio/lvgl/FramebufferDisplay.c @@ -493,7 +493,7 @@ bool common_hal_framebufferio_framebufferdisplay_refresh(framebufferio_framebuff } self->first_manual_refresh = false; if (self->lv_display != NULL) { - // Yield like the legacy framebufferio so audio can refill during a long render. + // Yield so audio can refill during a long render. displayio_lvgl_render_now(self->lv_display, true); } self->core.last_refresh = supervisor_ticks_ms64(); From d3765be580c2c4e745d96411bf7d73a696b4012f Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Thu, 19 Nov 2026 19:03:03 -0800 Subject: [PATCH 4/9] espressif: refill I2S audio from its own task The I2S interrupt now wakes a task, above the LVGL render task, instead of queuing a background callback. So a long display render can't starve audio. Preventing background callbacks still keeps refill out: a new port hook, port_background_lock(), is taken while they are prevented or running, and the fill task holds the same lock while it refills. Co-Authored-By: Claude Opus 5.5 --- .../common-hal/audiobusio/__init__.c | 85 +++++++++++++++---- .../common-hal/audiobusio/__init__.h | 6 +- supervisor/port.h | 7 ++ supervisor/shared/background_callback.c | 11 +++ 4 files changed, 90 insertions(+), 19 deletions(-) diff --git a/ports/espressif/common-hal/audiobusio/__init__.c b/ports/espressif/common-hal/audiobusio/__init__.c index 4843e457f1a..544d91e1f50 100644 --- a/ports/espressif/common-hal/audiobusio/__init__.c +++ b/ports/espressif/common-hal/audiobusio/__init__.c @@ -10,14 +10,16 @@ #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" #endif #include "shared-module/audiocore/__init__.h" +#include "supervisor/background_callback.h" +#include "supervisor/port.h" // The maximum DMA buffer size (in bytes) #define I2S_DMA_BUFFER_MAX_SIZE 4092 @@ -27,6 +29,30 @@ #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 the CircuitPython task while background callbacks +// are prevented or running. So code that prevents background callbacks to change a sample (like +// MP3Decoder.file) still keeps refill out. Recursive because a sample may prevent them itself +// while it fills. +static StaticSemaphore_t background_lock_storage; +static SemaphoreHandle_t background_lock; + +void port_background_lock(void) { + if (background_lock == NULL) { + background_lock = xSemaphoreCreateRecursiveMutexStatic(&background_lock_storage); + } + xSemaphoreTakeRecursive(background_lock, portMAX_DELAY); +} + +void port_background_unlock(void) { + if (background_lock != NULL && xSemaphoreGetMutexHolder(background_lock) == xTaskGetCurrentTaskHandle()) { + xSemaphoreGiveRecursive(background_lock); + } +} static void i2s_fill_buffer(i2s_t *self) { if (self->next_buffer_size == 0) { @@ -116,20 +142,25 @@ 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); + port_background_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 + port_background_unlock(); } - #endif } static bool i2s_event_interrupt(i2s_chan_handle_t handle, i2s_event_data_t *event, void *self_in) { @@ -137,8 +168,9 @@ static bool i2s_event_interrupt(i2s_chan_handle_t handle, i2s_event_data_t *even 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) { @@ -152,6 +184,12 @@ 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")); } + 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; @@ -169,12 +207,24 @@ 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. Preventing background callbacks + // takes the lock, so the task isn't mid-fill. + background_callback_prevent(); + vTaskDelete(self->fill_task); + self->fill_task = NULL; + background_callback_allow(); + } } 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); + // Keep refill out while the sample changes. Loading it can raise, so allow again if it does. + MP_DEFINE_NLR_JUMP_CALLBACK_FUNCTION_1(allow, background_callback_allow, NULL); + background_callback_prevent(); + nlr_push_jump_callback(&allow.callback, mp_call_function_1_from_nlr_jump_callback); self->sample = sample; self->loop = loop; self->bytes_per_sample = audiosample_get_bits_per_sample(sample) / 8; @@ -215,6 +265,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; } + nlr_pop_jump_callback(true); // enable the channel i2s_channel_enable(self->handle); @@ -235,10 +286,12 @@ bool port_i2s_paused(i2s_t *self) { void port_i2s_stop(i2s_t *self) { port_i2s_pause(self); + background_callback_prevent(); self->sample = NULL; self->playing = false; self->stopping = false; self->last_buffer = false; + background_callback_allow(); } void port_i2s_pause(i2s_t *self) { diff --git a/ports/espressif/common-hal/audiobusio/__init__.h b/ports/espressif/common-hal/audiobusio/__init__.h index af341460e49..022ff7951a5 100644 --- a/ports/espressif/common-hal/audiobusio/__init__.h +++ b/ports/espressif/common-hal/audiobusio/__init__.h @@ -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; @@ -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; diff --git a/supervisor/port.h b/supervisor/port.h index 3d927318a1c..6e88a6db5f1 100644 --- a/supervisor/port.h +++ b/supervisor/port.h @@ -94,6 +94,13 @@ void port_wake_main_task(void); // default weak implementation is provided that does nothing. void port_wake_main_task_from_isr(void); +// Ports that run background work, like audio refill, on another task take a lock here so that +// work is kept out while background callbacks are prevented (background_callback_prevent() or +// while they run). Calls nest and come from the CircuitPython task or a port's own task, never +// an interrupt. Default weak implementations do nothing. +void port_background_lock(void); +void port_background_unlock(void); + // Some ports may use real RTOS tasks besides the background task framework of // CircuitPython. Calling this will yield to other tasks at the same priority level // (or higher priority level if pre-emption is not immediate in the RTOS) diff --git a/supervisor/shared/background_callback.c b/supervisor/shared/background_callback.c index 65a0bcbf4c0..09d5d595915 100644 --- a/supervisor/shared/background_callback.c +++ b/supervisor/shared/background_callback.c @@ -26,6 +26,12 @@ static volatile background_callback_t *volatile callback_head, *volatile callbac MP_WEAK void PLACE_IN_ITCM(port_wake_main_task)(void) { } +MP_WEAK void PLACE_IN_ITCM(port_background_lock)(void) { +} + +MP_WEAK void PLACE_IN_ITCM(port_background_unlock)(void) { +} + void PLACE_IN_ITCM(background_callback_add_core)(background_callback_t * cb) { CALLBACK_CRITICAL_BEGIN; if (cb->prev || callback_head == cb) { @@ -63,9 +69,11 @@ void PLACE_IN_ITCM(background_callback_run_all)(void) { if (!background_callback_pending()) { return; } + port_background_lock(); CALLBACK_CRITICAL_BEGIN; if (background_prevention_count) { CALLBACK_CRITICAL_END; + port_background_unlock(); return; } ++background_prevention_count; @@ -97,9 +105,11 @@ void PLACE_IN_ITCM(background_callback_run_all)(void) { } --background_prevention_count; CALLBACK_CRITICAL_END; + port_background_unlock(); } void background_callback_prevent(void) { + port_background_lock(); CALLBACK_CRITICAL_BEGIN; ++background_prevention_count; CALLBACK_CRITICAL_END; @@ -109,6 +119,7 @@ void background_callback_allow(void) { CALLBACK_CRITICAL_BEGIN; --background_prevention_count; CALLBACK_CRITICAL_END; + port_background_unlock(); } From ea9abbed117ba59f4f2f48d4c36ff68758bc60f0 Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Thu, 19 Nov 2026 19:08:08 -0800 Subject: [PATCH 5/9] lvgl: render auto-refresh on the LVGL task again Audio now refills from its own task above LVGL, so auto-refresh no longer needs to move to the CircuitPython thread and yield. This undoes the earlier auto-refresh yield and its comment tidy. Co-Authored-By: Claude Opus 5.5 --- ports/espressif/supervisor/lvgl_port.c | 35 ++-------- .../common-hal/zephyr_display/lvgl/Display.c | 2 +- shared-module/displayio/lvgl/Group.c | 67 +++++++------------ shared-module/displayio/lvgl/lvgl_internal.h | 22 ++---- .../framebufferio/lvgl/FramebufferDisplay.c | 10 ++- 5 files changed, 47 insertions(+), 89 deletions(-) diff --git a/ports/espressif/supervisor/lvgl_port.c b/ports/espressif/supervisor/lvgl_port.c index f217ed4a96f..0c5f6bd260d 100644 --- a/ports/espressif/supervisor/lvgl_port.c +++ b/ports/espressif/supervisor/lvgl_port.c @@ -32,11 +32,9 @@ static TaskHandle_t lvgl_task_handle = NULL; static volatile uint32_t lvgl_frame_generation = 0; static uint32_t lvgl_frame_seen = 0; -// Display auto-refreshes render on the CircuitPython thread, from these background callbacks. -// BusDisplay's LVGL refresh timer is proxied to the first; a framebuffer frame boundary queues the -// second. They allow other callbacks (audio refill) to run while they render. +// BusDisplay flushes stay on the CircuitPython thread. Its LVGL refresh timer is proxied to this +// background callback, so no supervisor tick is involved. static background_callback_t lvgl_cp_refresh_cb; -static background_callback_t lvgl_cp_paced_refresh_cb; // LVGL's allocator hooks (LV_USE_STDLIB_MALLOC == LV_STDLIB_CUSTOM). Displays and // their buffers outlive the VM, so they come from the port heap. @@ -155,24 +153,7 @@ void displayio_lvgl_port_unlock(void) { static void lvgl_cp_refresh(void *unused) { LV_UNUSED(unused); - background_callback_allow(); - bool rendered = displayio_lvgl_refresh_unsafe_displays(true); - background_callback_prevent(); - if (!rendered) { - // Another render was running background tasks. Try again after it. - background_callback_add(&lvgl_cp_refresh_cb, lvgl_cp_refresh, NULL); - } -} - -static void lvgl_cp_paced_refresh(void *unused) { - LV_UNUSED(unused); - background_callback_allow(); - bool rendered = displayio_lvgl_refresh_paced_displays(true); - background_callback_prevent(); - if (!rendered) { - // Another render was running background tasks. Try again after it. - background_callback_add(&lvgl_cp_paced_refresh_cb, lvgl_cp_paced_refresh, NULL); - } + displayio_lvgl_refresh_unsafe_displays(); } // BusDisplay's LVGL refresh timer normally flushes on the render task. Replace its callback with @@ -203,10 +184,8 @@ IRAM_ATTR void displayio_lvgl_port_frame_boundary(void) { return; } // UVC invokes its frame callback from a background task on the CircuitPython thread. Render - // directly there, before the frame is converted; there is no task handoff. No yield: other - // callbacks, including this one, must not run before the frame is converted. If another render - // is in progress this frame is skipped, and the next frame boundary renders. - displayio_lvgl_refresh_paced_displays(false); + // directly there; there is no task handoff. + displayio_lvgl_refresh_paced_displays(); } static void lvgl_task(void *arg) { @@ -232,7 +211,7 @@ static void lvgl_task(void *arg) { uint32_t frame_generation = lvgl_frame_generation; if (frame_generation != lvgl_frame_seen) { lvgl_frame_seen = frame_generation; - background_callback_add(&lvgl_cp_paced_refresh_cb, lvgl_cp_paced_refresh, NULL); + displayio_lvgl_refresh_paced_displays(); } } } @@ -268,7 +247,7 @@ void displayio_lvgl_port_init(void) { // The task must run above the CircuitPython task so a tight Python loop can't starve // rendering. Pin it to the CircuitPython core as well: background_callback_add() (used by the - // BusDisplay proxy and the frame boundary) is interrupt-safe on a single core, and sharing the core keeps it from + // BusDisplay proxy) is interrupt-safe on a single core, and sharing the core keeps it from // racing the CircuitPython thread's callback list. A recursive mutex (priority inheritance) // keeps that from blocking the main task for long. 16 KB covers the draw paths plus LVGL's // internal compositor state; 8 KB overflowed on complex screens. diff --git a/ports/zephyr-cp/common-hal/zephyr_display/lvgl/Display.c b/ports/zephyr-cp/common-hal/zephyr_display/lvgl/Display.c index a9c6d6c495e..3f34c0957a0 100644 --- a/ports/zephyr-cp/common-hal/zephyr_display/lvgl/Display.c +++ b/ports/zephyr-cp/common-hal/zephyr_display/lvgl/Display.c @@ -67,7 +67,7 @@ void displayio_lvgl_port_install_busdisplay_refresh(lv_display_t *display) { void displayio_lvgl_port_frame_boundary(void) { // No Zephyr framebuffer exposes a frame callback yet. If one does, this must be made ISR // safe (for example by scheduling the refresh on the LVGL workqueue). - displayio_lvgl_refresh_paced_displays(false); + displayio_lvgl_refresh_paced_displays(); } static void zephyr_display_lvgl_flush_argb_alpha0(lv_display_t *display, const lv_area_t *area, diff --git a/shared-module/displayio/lvgl/Group.c b/shared-module/displayio/lvgl/Group.c index dcc7d1079f4..8580748d6e0 100644 --- a/shared-module/displayio/lvgl/Group.c +++ b/shared-module/displayio/lvgl/Group.c @@ -52,36 +52,6 @@ static displayio_group_t *cp_lvgl_root_group = NULL; static bool cp_lvgl_inited = false; bool displayio_lvgl_refresh_yield = false; -// Set while a display renders on the CircuitPython thread. A background callback run from inside -// that render (see displayio_lvgl_refresh_yield) must not start a nested one: LVGL keeps the -// display being rendered in a global and doesn't restore it. -static bool cp_lvgl_rendering = false; - -static bool _render_begin(bool yield) { - if (cp_lvgl_rendering) { - return false; - } - cp_lvgl_rendering = true; - displayio_lvgl_lock(); - displayio_lvgl_refresh_yield = yield; - return true; -} - -static void _render_end(void) { - displayio_lvgl_refresh_yield = false; - displayio_lvgl_unlock(); - cp_lvgl_rendering = false; -} - -bool displayio_lvgl_render_now(lv_display_t *display, bool yield) { - if (!_render_begin(yield)) { - return false; - } - lv_refr_now(display); - _render_end(); - return true; -} - // The port lock is recursive. Keeping the recursion at the port instead of counting here matters // once LVGL renders on its own task: a shared depth counter would let the render task believe it // owns a lock that the CircuitPython task is holding. @@ -200,12 +170,18 @@ bool displayio_lvgl_auto_refresh(void) { return true; } -// Render the displays that can't run on the render task. -bool displayio_lvgl_refresh_unsafe_displays(bool yield) { +// Render the displays that can't run on the render task. The guard keeps the proxy from +// re-entering LVGL rendering if a background callback is processed while a refresh is already +// active on the CircuitPython thread, including an explicit display.refresh() that is running +// background tasks mid-render. +void displayio_lvgl_refresh_unsafe_displays(void) { #if CIRCUITPY_BUSDISPLAY - if (!_render_begin(yield)) { - return false; + static bool refreshing = false; + if (refreshing || displayio_lvgl_refresh_yield) { + return; } + refreshing = true; + displayio_lvgl_lock(); for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) { mp_const_obj_t display_type = displays[i].display_base.type; if (display_type != &busdisplay_busdisplay_type) { @@ -216,17 +192,24 @@ bool displayio_lvgl_refresh_unsafe_displays(bool yield) { lv_refr_now(busdisplay->lv_display); } } - _render_end(); + displayio_lvgl_unlock(); + refreshing = false; #endif - return true; } -// Render the framebuffer displays that pace themselves from a frame boundary. -bool displayio_lvgl_refresh_paced_displays(bool yield) { +// Render the framebuffer displays that pace themselves from a frame boundary. Like the BusDisplay +// proxy, this runs on the CircuitPython thread and takes the LVGL lock; a frame callback may be +// running on the render task at the same time, so the lock serializes them. +void displayio_lvgl_refresh_paced_displays(void) { #if CIRCUITPY_FRAMEBUFFERIO - if (!_render_begin(yield)) { - return false; + static bool refreshing = false; + // An explicit display.refresh() runs background tasks while it renders. A frame callback + // queued among them must not start a nested render; it draws at the next frame instead. + if (refreshing || displayio_lvgl_refresh_yield) { + return; } + refreshing = true; + displayio_lvgl_lock(); for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) { mp_const_obj_t display_type = displays[i].display_base.type; if (display_type != &framebufferio_framebufferdisplay_type) { @@ -237,9 +220,9 @@ bool displayio_lvgl_refresh_paced_displays(bool yield) { lv_refr_now(display->lv_display); } } - _render_end(); + displayio_lvgl_unlock(); + refreshing = false; #endif - return true; } void displayio_lvgl_init(void) { diff --git a/shared-module/displayio/lvgl/lvgl_internal.h b/shared-module/displayio/lvgl/lvgl_internal.h index c30b7b6b405..8facf95c06f 100644 --- a/shared-module/displayio/lvgl/lvgl_internal.h +++ b/shared-module/displayio/lvgl/lvgl_internal.h @@ -69,24 +69,16 @@ void displayio_lvgl_register_display(lv_display_t *display); bool displayio_lvgl_auto_refresh(void); // Render displays that can't flush from the LVGL task (currently BusDisplay when the port asks -// for it). Called on the CircuitPython thread by the port's proxy. With `yield`, the render runs -// background tasks between steps, so background callbacks must not be prevented at the call (a -// background callback calls background_callback_allow() first). Returns false, without -// rendering, when another render on this thread is already in progress; the caller should try -// again later. -bool displayio_lvgl_refresh_unsafe_displays(bool yield); +// for it). Called on the CircuitPython thread by the port's proxy, under the LVGL lock. +void displayio_lvgl_refresh_unsafe_displays(void); // Render the framebuffer displays that pace themselves from a frame boundary. Called on the -// CircuitPython thread. `yield` and the return value are as for -// displayio_lvgl_refresh_unsafe_displays(). -bool displayio_lvgl_refresh_paced_displays(bool yield); +// CircuitPython thread (directly or from the render task after an ISR notification), under the +// LVGL lock. +void displayio_lvgl_refresh_paced_displays(void); -// Render one display now on the CircuitPython thread, as display.refresh() does. `yield` and the -// return value are as above. -bool displayio_lvgl_render_now(lv_display_t *display, bool yield); - -// True while a render on the CircuitPython thread may run background tasks. Long render steps -// (TileGrid compose, display flush) run them when it is set, so audio can refill. +// True while an explicit display.refresh() renders on the CircuitPython thread. Long +// render steps (TileGrid compose, display flush) run background tasks when it is set. extern bool displayio_lvgl_refresh_yield; // Attach/detach the compositor's root group. Implemented in lvgl/Group.c. NULL detach. diff --git a/shared-module/framebufferio/lvgl/FramebufferDisplay.c b/shared-module/framebufferio/lvgl/FramebufferDisplay.c index 3e912d4370c..e3bdf34629d 100644 --- a/shared-module/framebufferio/lvgl/FramebufferDisplay.c +++ b/shared-module/framebufferio/lvgl/FramebufferDisplay.c @@ -224,7 +224,7 @@ static void framebufferio_lvgl_flush_cb(lv_display_t *disp, const lv_area_t *are lv_display_flush_ready(disp); // A refresh can take longer than the audio buffers last. Like the legacy - // framebufferio, let background tasks run between chunks. + // framebufferio, let background tasks run between chunks of an explicit refresh. if (displayio_lvgl_refresh_yield) { RUN_BACKGROUND_TASKS; } @@ -493,8 +493,12 @@ bool common_hal_framebufferio_framebufferdisplay_refresh(framebufferio_framebuff } self->first_manual_refresh = false; if (self->lv_display != NULL) { - // Yield so audio can refill during a long render. - displayio_lvgl_render_now(self->lv_display, true); + // The renderer refreshes on its own thread too, so this has to exclude it. + displayio_lvgl_lock(); + displayio_lvgl_refresh_yield = true; + lv_refr_now(self->lv_display); + displayio_lvgl_refresh_yield = false; + displayio_lvgl_unlock(); } self->core.last_refresh = supervisor_ticks_ms64(); return true; From e7168671df5c4cc3025e92b6559936edba60ae4a Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Fri, 20 Nov 2026 07:35:16 -0800 Subject: [PATCH 6/9] espressif: allocate the background lock from the heap Static storage for it overflowed internal RAM on the ESP32-S2 devkit. It is now created with the first I2SOut. Until then there is no fill task, so lock and unlock do nothing. Co-Authored-By: Claude Opus 5.5 --- ports/espressif/common-hal/audiobusio/__init__.c | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/ports/espressif/common-hal/audiobusio/__init__.c b/ports/espressif/common-hal/audiobusio/__init__.c index 544d91e1f50..2c66a35e319 100644 --- a/ports/espressif/common-hal/audiobusio/__init__.c +++ b/ports/espressif/common-hal/audiobusio/__init__.c @@ -37,15 +37,14 @@ // Held by a fill task while it refills, and by the CircuitPython task while background callbacks // are prevented or running. So code that prevents background callbacks to change a sample (like // MP3Decoder.file) still keeps refill out. Recursive because a sample may prevent them itself -// while it fills. -static StaticSemaphore_t background_lock_storage; +// 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 background_lock; void port_background_lock(void) { - if (background_lock == NULL) { - background_lock = xSemaphoreCreateRecursiveMutexStatic(&background_lock_storage); + if (background_lock != NULL) { + xSemaphoreTakeRecursive(background_lock, portMAX_DELAY); } - xSemaphoreTakeRecursive(background_lock, portMAX_DELAY); } void port_background_unlock(void) { @@ -184,6 +183,13 @@ 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 (background_lock == NULL) { + background_lock = xSemaphoreCreateRecursiveMutex(); + if (background_lock == 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) { From 718d308378ef7ef2790675f784e69680220e35ea Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Fri, 20 Nov 2026 10:10:48 -0800 Subject: [PATCH 7/9] espressif: point esp-idf at the merged SD controller lock fix Same code as before. adafruit/esp-idf#25 has merged, so use its merge commit on circuitpython-v6.1. Co-Authored-By: Claude Opus 5.5 --- ports/espressif/esp-idf | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ports/espressif/esp-idf b/ports/espressif/esp-idf index a17cc0560b8..cb733171022 160000 --- a/ports/espressif/esp-idf +++ b/ports/espressif/esp-idf @@ -1 +1 @@ -Subproject commit a17cc0560b847618c48036a6f605c63d985fbb23 +Subproject commit cb7331710226bb08461b1bde337f87610e5c53a9 From 36f2d0369bb77247fc2306369f4b87e5a87b99de Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Fri, 20 Nov 2026 12:18:33 -0800 Subject: [PATCH 8/9] audiocore: add a lock for audio fetched on another task tannewt asked for an audiocore lock rather than a hook in background callbacks, which go away under an RTOS. Drop port_background_lock and add audiocore_lock()/audiocore_unlock(): a no-op by default, a recursive mutex on Espressif. The I2S fill task holds it while it fetches. I2S play, stop and deinit take it, and so does MP3Decoder wherever it changes the decoder, including deinit so the fill task can't use freed buffers. Co-Authored-By: Claude Opus 5.5 --- .../common-hal/audiobusio/__init__.c | 53 +++++++++---------- shared-module/audiocore/__init__.c | 6 +++ shared-module/audiocore/__init__.h | 7 +++ shared-module/audiomp3/MP3Decoder.c | 11 ++++ supervisor/port.h | 7 --- supervisor/shared/background_callback.c | 11 ---- 6 files changed, 49 insertions(+), 46 deletions(-) diff --git a/ports/espressif/common-hal/audiobusio/__init__.c b/ports/espressif/common-hal/audiobusio/__init__.c index 2c66a35e319..368ddf37c04 100644 --- a/ports/espressif/common-hal/audiobusio/__init__.c +++ b/ports/espressif/common-hal/audiobusio/__init__.c @@ -18,8 +18,6 @@ #endif #include "shared-module/audiocore/__init__.h" -#include "supervisor/background_callback.h" -#include "supervisor/port.h" // The maximum DMA buffer size (in bytes) #define I2S_DMA_BUFFER_MAX_SIZE 4092 @@ -34,22 +32,21 @@ #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 the CircuitPython task while background callbacks -// are prevented or running. So code that prevents background callbacks to change a sample (like -// MP3Decoder.file) still keeps refill out. Recursive because a sample may prevent them 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 background_lock; +// 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 port_background_lock(void) { - if (background_lock != NULL) { - xSemaphoreTakeRecursive(background_lock, portMAX_DELAY); +void audiocore_lock(void) { + if (audiocore_mutex != NULL) { + xSemaphoreTakeRecursive(audiocore_mutex, portMAX_DELAY); } } -void port_background_unlock(void) { - if (background_lock != NULL && xSemaphoreGetMutexHolder(background_lock) == xTaskGetCurrentTaskHandle()) { - xSemaphoreGiveRecursive(background_lock); +void audiocore_unlock(void) { + if (audiocore_mutex != NULL) { + xSemaphoreGiveRecursive(audiocore_mutex); } } @@ -145,7 +142,7 @@ static void i2s_fill_task(void *self_in) { i2s_t *self = self_in; for (;;) { ulTaskNotifyTake(pdTRUE, portMAX_DELAY); - port_background_lock(); + 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; @@ -158,7 +155,7 @@ static void i2s_fill_task(void *self_in) { esp_cache_msync(buffer, buffer_size, ESP_CACHE_MSYNC_FLAG_DIR_C2M); } #endif - port_background_unlock(); + audiocore_unlock(); } } @@ -183,9 +180,9 @@ 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 (background_lock == NULL) { - background_lock = xSemaphoreCreateRecursiveMutex(); - if (background_lock == NULL) { + if (audiocore_mutex == NULL) { + audiocore_mutex = xSemaphoreCreateRecursiveMutex(); + if (audiocore_mutex == NULL) { i2s_del_channel(self->handle); m_malloc_fail(sizeof(StaticSemaphore_t)); } @@ -214,12 +211,12 @@ void port_i2s_deinit(i2s_t *self) { i2s_del_channel(self->handle); self->handle = NULL; if (self->fill_task != NULL) { - // The channel is gone, so nothing wakes the task again. Preventing background callbacks - // takes the lock, so the task isn't mid-fill. - background_callback_prevent(); + // 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; - background_callback_allow(); + audiocore_unlock(); } } @@ -227,9 +224,9 @@ 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); - // Keep refill out while the sample changes. Loading it can raise, so allow again if it does. - MP_DEFINE_NLR_JUMP_CALLBACK_FUNCTION_1(allow, background_callback_allow, NULL); - background_callback_prevent(); + // Keep refill out while the sample changes. Loading it can raise, so unlock again if it does. + MP_DEFINE_NLR_JUMP_CALLBACK_FUNCTION_1(allow, audiocore_unlock, NULL); + audiocore_lock(); nlr_push_jump_callback(&allow.callback, mp_call_function_1_from_nlr_jump_callback); self->sample = sample; self->loop = loop; @@ -292,12 +289,12 @@ bool port_i2s_paused(i2s_t *self) { void port_i2s_stop(i2s_t *self) { port_i2s_pause(self); - background_callback_prevent(); + audiocore_lock(); self->sample = NULL; self->playing = false; self->stopping = false; self->last_buffer = false; - background_callback_allow(); + audiocore_unlock(); } void port_i2s_pause(i2s_t *self) { diff --git a/shared-module/audiocore/__init__.c b/shared-module/audiocore/__init__.c index 9cd561208f3..97849da3f38 100644 --- a/shared-module/audiocore/__init__.c +++ b/shared-module/audiocore/__init__.c @@ -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))) { diff --git a/shared-module/audiocore/__init__.h b/shared-module/audiocore/__init__.h index d135ee6c9e9..6ad24a115b0 100644 --- a/shared-module/audiocore/__init__.h +++ b/shared-module/audiocore/__init__.h @@ -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, diff --git a/shared-module/audiomp3/MP3Decoder.c b/shared-module/audiomp3/MP3Decoder.c index 6d8c4522529..58faadc7c9c 100644 --- a/shared-module/audiomp3/MP3Decoder.c +++ b/shared-module/audiomp3/MP3Decoder.c @@ -122,9 +122,11 @@ static void stream_set_blocking(audiomp3_mp3file_obj_t *self, bool block_ok) { 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; } @@ -151,6 +153,7 @@ static bool mp3file_update_inbuf_always(audiomp3_mp3file_obj_t *self, bool block break; } self->eof = true; + audiocore_unlock(); background_callback_allow(); mp_raise_OSError(errcode); } @@ -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; } @@ -388,6 +392,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; @@ -396,9 +401,11 @@ 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 (!result) { mp_raise_msg(&mp_type_RuntimeError, @@ -416,6 +423,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); @@ -427,6 +435,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, @@ -438,6 +447,7 @@ 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; @@ -446,6 +456,7 @@ void audiomp3_mp3file_reset_buffer(audiomp3_mp3file_obj_t *self, mp3file_skip_id3v2(self, false); mp3file_find_sync_word(self, false); } + audiocore_unlock(); background_callback_allow(); } diff --git a/supervisor/port.h b/supervisor/port.h index 6e88a6db5f1..3d927318a1c 100644 --- a/supervisor/port.h +++ b/supervisor/port.h @@ -94,13 +94,6 @@ void port_wake_main_task(void); // default weak implementation is provided that does nothing. void port_wake_main_task_from_isr(void); -// Ports that run background work, like audio refill, on another task take a lock here so that -// work is kept out while background callbacks are prevented (background_callback_prevent() or -// while they run). Calls nest and come from the CircuitPython task or a port's own task, never -// an interrupt. Default weak implementations do nothing. -void port_background_lock(void); -void port_background_unlock(void); - // Some ports may use real RTOS tasks besides the background task framework of // CircuitPython. Calling this will yield to other tasks at the same priority level // (or higher priority level if pre-emption is not immediate in the RTOS) diff --git a/supervisor/shared/background_callback.c b/supervisor/shared/background_callback.c index 09d5d595915..65a0bcbf4c0 100644 --- a/supervisor/shared/background_callback.c +++ b/supervisor/shared/background_callback.c @@ -26,12 +26,6 @@ static volatile background_callback_t *volatile callback_head, *volatile callbac MP_WEAK void PLACE_IN_ITCM(port_wake_main_task)(void) { } -MP_WEAK void PLACE_IN_ITCM(port_background_lock)(void) { -} - -MP_WEAK void PLACE_IN_ITCM(port_background_unlock)(void) { -} - void PLACE_IN_ITCM(background_callback_add_core)(background_callback_t * cb) { CALLBACK_CRITICAL_BEGIN; if (cb->prev || callback_head == cb) { @@ -69,11 +63,9 @@ void PLACE_IN_ITCM(background_callback_run_all)(void) { if (!background_callback_pending()) { return; } - port_background_lock(); CALLBACK_CRITICAL_BEGIN; if (background_prevention_count) { CALLBACK_CRITICAL_END; - port_background_unlock(); return; } ++background_prevention_count; @@ -105,11 +97,9 @@ void PLACE_IN_ITCM(background_callback_run_all)(void) { } --background_prevention_count; CALLBACK_CRITICAL_END; - port_background_unlock(); } void background_callback_prevent(void) { - port_background_lock(); CALLBACK_CRITICAL_BEGIN; ++background_prevention_count; CALLBACK_CRITICAL_END; @@ -119,7 +109,6 @@ void background_callback_allow(void) { CALLBACK_CRITICAL_BEGIN; --background_prevention_count; CALLBACK_CRITICAL_END; - port_background_unlock(); } From a6afcf81bf8c50118761c354ee81bec503f5cb4c Mon Sep 17 00:00:00 2001 From: Mikey Sklar Date: Fri, 20 Nov 2026 12:18:41 -0800 Subject: [PATCH 9/9] audiomp3: report read errors by return value, not by raising As tannewt suggested, loading code reports errors so the caller can give the lock back first. MP3Decoder keeps a failed read's errno and returns GET_BUFFER_ERROR, and set_file raises it after unlocking. I2S play sets the clock, which can raise, before locking, so it no longer needs the NLR jump callback. This also stops an OSError being raised on the fill task, where nothing can catch it. A read error mid-track now ends playback instead. Co-Authored-By: Claude Opus 5.5 --- .../common-hal/audiobusio/__init__.c | 15 +++++++-------- shared-module/audiomp3/MP3Decoder.c | 19 ++++++++++++++----- shared-module/audiomp3/MP3Decoder.h | 1 + 3 files changed, 22 insertions(+), 13 deletions(-) diff --git a/ports/espressif/common-hal/audiobusio/__init__.c b/ports/espressif/common-hal/audiobusio/__init__.c index 368ddf37c04..b594176a75f 100644 --- a/ports/espressif/common-hal/audiobusio/__init__.c +++ b/ports/espressif/common-hal/audiobusio/__init__.c @@ -224,10 +224,13 @@ 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); - // Keep refill out while the sample changes. Loading it can raise, so unlock again if it does. - MP_DEFINE_NLR_JUMP_CALLBACK_FUNCTION_1(allow, audiocore_unlock, NULL); + // 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(); - nlr_push_jump_callback(&allow.callback, mp_call_function_1_from_nlr_jump_callback); self->sample = sample; self->loop = loop; self->bytes_per_sample = audiosample_get_bits_per_sample(sample) / 8; @@ -245,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; @@ -268,7 +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; } - nlr_pop_jump_callback(true); + audiocore_unlock(); // enable the channel i2s_channel_enable(self->handle); diff --git a/shared-module/audiomp3/MP3Decoder.c b/shared-module/audiomp3/MP3Decoder.c index 58faadc7c9c..a23a73291d1 100644 --- a/shared-module/audiomp3/MP3Decoder.c +++ b/shared-module/audiomp3/MP3Decoder.c @@ -115,7 +115,8 @@ 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 */ @@ -153,9 +154,8 @@ static bool mp3file_update_inbuf_always(audiomp3_mp3file_obj_t *self, bool block break; } self->eof = true; - audiocore_unlock(); - background_callback_allow(); - mp_raise_OSError(errcode); + self->read_error = errcode; + break; } if (n_read == 0) { @@ -362,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); @@ -407,6 +408,9 @@ void common_hal_audiomp3_mp3file_set_file(audiomp3_mp3file_obj_t *self, mp_obj_t } 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")); @@ -451,6 +455,7 @@ void audiomp3_mp3file_reset_buffer(audiomp3_mp3file_obj_t *self, 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); @@ -472,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; } @@ -500,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); diff --git a/shared-module/audiomp3/MP3Decoder.h b/shared-module/audiomp3/MP3Decoder.h index 9af3300047b..a12eb80a815 100644 --- a/shared-module/audiomp3/MP3Decoder.h +++ b/shared-module/audiomp3/MP3Decoder.h @@ -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;