From 651280ce223cc3efddf8ec078aca7e2764548e74 Mon Sep 17 00:00:00 2001 From: foamyguy Date: Thu, 19 Nov 2026 13:37:40 -0600 Subject: [PATCH 1/4] ring buffer for isochronous USBIn --- ports/espressif/background.c | 2 +- ports/espressif/common-hal/usb_host/Port.c | 54 ++++-- ports/espressif/mpconfigport.h | 6 + shared-bindings/usb_host_audio/USBIn.c | 19 +- shared-module/usb/core/Device.c | 29 ++- shared-module/usb_host_audio/USBIn.c | 194 +++++++++++++++------ shared-module/usb_host_audio/USBIn.h | 43 +++-- supervisor/shared/usb/host_keyboard.c | 53 +++++- supervisor/shared/usb/usb.c | 2 +- supervisor/usb.h | 8 + 10 files changed, 314 insertions(+), 96 deletions(-) diff --git a/ports/espressif/background.c b/ports/espressif/background.c index 08a58a2128e..1ce9c18a19d 100644 --- a/ports/espressif/background.c +++ b/ports/espressif/background.c @@ -21,7 +21,7 @@ #include "freertos/task.h" void port_background_tick(void) { - #if CIRCUITPY_USB_HOST + #if CIRCUITPY_USB_HOST && !CIRCUITPY_USB_HOST_TASK // Enumeration delays need polling even when no new USB IRQ arrives. if (tuh_task_event_ready()) { usb_background_schedule(); diff --git a/ports/espressif/common-hal/usb_host/Port.c b/ports/espressif/common-hal/usb_host/Port.c index 702d4889c31..8a629fe3b61 100644 --- a/ports/espressif/common-hal/usb_host/Port.c +++ b/ports/espressif/common-hal/usb_host/Port.c @@ -7,9 +7,11 @@ #include "bindings/espidf/__init__.h" #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/usb_host/Port.h" +#include "supervisor/port.h" #include "supervisor/usb.h" -#include "supervisor/shared/tick.h" #include "esp_private/usb_phy.h" +#include "freertos/FreeRTOS.h" +#include "freertos/task.h" #include "tusb.h" #if defined(CONFIG_IDF_TARGET_ESP32P4) @@ -27,10 +29,42 @@ #if CIRCUITPY_USB_DEVICE && CIRCUITPY_USB_DEVICE_INSTANCE == CIRCUITPY_USB_HOST_INSTANCE #error "USB host and device must use different controllers" #endif +#if !CIRCUITPY_USB_HOST_TASK +#error "The espressif USB host runs TinyUSB in a task of its own" +#endif + +// TinyUSB's host stack runs in this task, which waits on TinyUSB's event queue +// and so runs as soon as the controller interrupt posts an event. The VM +// doesn't have to get to its background tasks first: an isochronous stream +// queues its next transfer within the frame while the VM writes to an SD card +// or collects garbage. +// +// It runs above the VM's priority, like the MAX3421E's host task, so that a +// busy VM doesn't hold it up. Like the other USB tasks it is pinned to the +// same core as CircuitPython, which leaves the other core for networking. +#define USB_HOST_TASK_PRIORITY (5) +// Bytes. Enumeration and the class and Python module callbacks run on it. +#define USB_HOST_TASK_STACK_SIZE (4096) static usb_host_port_obj_t usb_host_instance; static usb_phy_handle_t host_phy; +static StackType_t _host_task_stack[USB_HOST_TASK_STACK_SIZE]; +static StaticTask_t _host_task_tcb; +static TaskHandle_t _host_task = NULL; + +static void _usb_host_task(void *param) { + (void)param; + while (true) { + // Returns once the events that came in are handled. It waits only as + // long as no TinyUSB timer (enumeration delays, control transfer + // timeouts) is due. + tuh_task_ext(UINT32_MAX, false); + // Python code may be waiting for what the events completed. + port_wake_main_task(); + } +} + usb_host_port_obj_t *common_hal_usb_host_port_construct(const mcu_pin_obj_t *dp, const mcu_pin_obj_t *dm) { // The high-speed PHY has dedicated pads, not GPIOs. if (dp != &pin_USB_HS_DP || dm != &pin_USB_HS_DM) { @@ -53,18 +87,16 @@ usb_host_port_obj_t *common_hal_usb_host_port_construct(const mcu_pin_obj_t *dp, host_phy = NULL; CHECK_ESP_RESULT(ESP_FAIL); } + // The port is never deinited, so neither is the task. It is the only + // caller of tuh_task_ext(), which is why it only starts after tuh_init(). + // This runs on the VM, so xPortGetCoreID() is CircuitPython's core. + if (_host_task == NULL) { + _host_task = xTaskCreateStaticPinnedToCore(_usb_host_task, "usbh", + USB_HOST_TASK_STACK_SIZE, NULL, USB_HOST_TASK_PRIORITY, + _host_task_stack, &_host_task_tcb, xPortGetCoreID()); + } self->base.type = &usb_host_port_type; self->dp = dp; self->dm = dm; - // Keep polling enumeration timers even without an active display. - supervisor_enable_tick(); return self; } - -// TinyUSB installs the controller IRQ. Process its events on the VM task, -// where the Python USB device and keyboard callbacks are safe to run. -void tuh_event_hook_cb(uint8_t rhport, uint32_t eventid, bool in_isr) { - // Don't wait for the background tick: an isochronous stream must queue its - // next transfer within the frame. - usb_background_schedule(); -} diff --git a/ports/espressif/mpconfigport.h b/ports/espressif/mpconfigport.h index ed00873ec89..5eae27068b4 100644 --- a/ports/espressif/mpconfigport.h +++ b/ports/espressif/mpconfigport.h @@ -80,6 +80,12 @@ extern portMUX_TYPE background_task_mutex; #define CIRCUITPY_ESP32P4_SWAP_LSFS (0) #endif +// TinyUSB's host stack runs in a FreeRTOS task of its own that waits on its +// event queue, instead of as a background callback of the VM. Completion +// callbacks then run, and isochronous streams queue their next transfer, while +// the VM is busy. See common-hal/usb_host/Port.c. +#define CIRCUITPY_USB_HOST_TASK (CIRCUITPY_USB_HOST) + #if MICROPY_PERSISTENT_CODE_LOAD_NATIVE // Loaded native code is copied out of the GC heap into executable RAM. void *esp_native_code_commit(void *buf, size_t len, void *reloc); diff --git a/shared-bindings/usb_host_audio/USBIn.c b/shared-bindings/usb_host_audio/USBIn.c index 62255177f50..e181ad544e9 100644 --- a/shared-bindings/usb_host_audio/USBIn.c +++ b/shared-bindings/usb_host_audio/USBIn.c @@ -49,11 +49,16 @@ //| //| On RP2 boards, whose host port is PIO-USB, the host controller buffers //| the stream between reads, in a buffer of ``iso_buffer_size`` bytes that -//| `USBIn` allocates and `deinit` frees. On boards whose host port is the -//| chip's own USB controller, such as the Metro ESP32-P4, there is no such -//| buffer and ``iso_buffer_size`` is not used: each packet is received as -//| it arrives, and packets that arrive while background tasks can't run, -//| such as during a long garbage collection, are lost and set `overflow`. +//| `USBIn` allocates and `deinit` frees. On the ESP32-P4 the USB host runs in a task of its own, +//| so packets keep arriving while Python is busy, such as during an SD +//| card write or a long garbage collection. On other such boards packets +//| that arrive while background tasks can't run are lost and set +//| `overflow`. +//| +//| Audio waits for `record` or playback in a buffer of +//| ``32 * buffer_frames`` frames on the ESP32-P4 and ``8 * buffer_frames`` +//| elsewhere. When that fills up, the newest audio is dropped and +//| `overflow` is set. //| //| Only one isochronous IN endpoint is received at a time, so only one //| `USBIn` can stream, and a USB camera cannot stream video meanwhile. @@ -194,8 +199,8 @@ static void check_for_deinit(usb_host_audio_usbin_obj_t *self) { //| (``'B'`` when unsigned) or a ``bytearray`` for 8. //| //| Audio is received between calls too, so that consecutive recordings -//| join up. When more arrived than is buffered, the recording starts -//| with the audio that arrives after the call. +//| join up. When more arrived than is buffered, the newest of it was +//| dropped: the recording has the buffered audio, then a gap. //| //| :return: The number of samples recorded. If this is less than //| ``destination_length``, the microphone stopped sending audio.""" diff --git a/shared-module/usb/core/Device.c b/shared-module/usb/core/Device.c index aa3da1217a5..3985df2d117 100644 --- a/shared-module/usb/core/Device.c +++ b/shared-module/usb/core/Device.c @@ -47,9 +47,12 @@ static inline void usb_host_audio_stop_device(uint8_t device_address) { } #endif +// The TinyUSB callbacks below run in tuh_task(), which is a task of its own on +// some ports (CIRCUITPY_USB_HOST_TASK). What they set is read by the VM. + // Track what device numbers are mounted. We can't use tuh_ready() because it is // true before enumeration completes and TinyUSB drivers are started. -static size_t _mounted_devices = 0; +static volatile size_t _mounted_devices = 0; void tuh_mount_cb(uint8_t dev_addr) { _mounted_devices |= 1 << dev_addr; @@ -60,8 +63,8 @@ void tuh_umount_cb(uint8_t dev_addr) { usb_host_bulk_stop_device(dev_addr); } -static xfer_result_t _xfer_result; -static size_t _actual_len; +static volatile xfer_result_t _xfer_result; +static volatile size_t _actual_len; #if !CIRCUITPY_ALL_MEMORY_DMA_CAPABLE // Helper to ensure buffer is DMA-capable for transfer operations @@ -110,6 +113,8 @@ void common_hal_usb_core_device_deinit(usb_core_device_obj_t *self) { return; } usb_host_bulk_device_deinit(self); + // A usb_host_audio stream ends with its endpoint, without a completion. + usb_host_audio_stop_device(self->device_address); size_t open_size = sizeof(self->open_endpoints); for (size_t i = 0; i < open_size; i++) { if (self->open_endpoints[i] != 0) { @@ -139,11 +144,21 @@ uint16_t common_hal_usb_core_device_get_idProduct(usb_core_device_obj_t *self) { } static void _transfer_done_cb(tuh_xfer_t *xfer) { - // Store the result so we stop waiting for the transfer. - _xfer_result = xfer->result; // The passed in xfer is not the original one we passed in, so we need to // copy any info out that we want (like actual_len.) _actual_len = xfer->actual_len; + // Store the result so we stop waiting for the transfer. The waiter reads + // _actual_len once it sees the result, so the result has to come last. + __atomic_thread_fence(__ATOMIC_RELEASE); + _xfer_result = xfer->result; +} + +// The result of the transfer, once the callback has stored it. +static xfer_result_t _get_xfer_result(void) { + xfer_result_t result = _xfer_result; + // _actual_len is read after this, and must be at least as new. + __atomic_thread_fence(__ATOMIC_ACQUIRE); + return result; } static bool _wait_for_callback(void) { @@ -158,7 +173,7 @@ static bool _wait_for_callback(void) { return false; } // Handle callback result code from TinyUSB - xfer_result_t result = _xfer_result; + xfer_result_t result = _get_xfer_result(); _xfer_result = XFER_RESULT_INVALID; switch (result) { case XFER_RESULT_SUCCESS: @@ -222,7 +237,7 @@ static size_t _handle_timed_transfer_callback(tuh_xfer_t *xfer, mp_int_t timeout return 0; } // Handle transfer result code from TinyUSB - xfer_result_t result = _xfer_result; + xfer_result_t result = _get_xfer_result(); _xfer_result = XFER_RESULT_INVALID; // Free the bounce buffer only on paths that raise: raising unwinds past // the caller's cleanup, so it must be freed here. Paths that return diff --git a/shared-module/usb_host_audio/USBIn.c b/shared-module/usb_host_audio/USBIn.c index 20863302778..ec23c1dd173 100644 --- a/shared-module/usb_host_audio/USBIn.c +++ b/shared-module/usb_host_audio/USBIn.c @@ -46,27 +46,65 @@ // one streaming object at most. TinyUSB copies the transfer and calls back with // only user_data, which carries _seq so that a completion which was already on // its way when its stream ended is recognised and dropped. +// Only the VM changes these, and the completion callback reads them. static usb_host_audio_usbin_obj_t *_active; static uintptr_t _seq; +// The completion callback runs in tuh_task(), which may be a task of its own +// (CIRCUITPY_USB_HOST_TASK). It holds this lock while it uses _active and +// queues the next transfer, and the VM holds it while it changes _active or +// _seq or aborts the transfer. Then a callback never queues a transfer, or +// writes the ring, of a stream that the VM ended and is freeing. Without an +// RTOS the callback runs on the VM, and the lock is nothing. The VM never +// holds it while it waits for TinyUSB, which would wait for the callback. +#if OSAL_MUTEX_REQUIRED +static osal_mutex_def_t _lock_def; +static osal_mutex_t _lock; +#else +#define _lock NULL +#endif + +static void _lock_take(void) { + (void)osal_mutex_lock(_lock, OSAL_TIMEOUT_WAIT_FOREVER); +} + +static void _lock_give(void) { + (void)osal_mutex_unlock(_lock); +} + +// The PCM ring is written by the completion callback and read by the VM, each +// moving only its own index (see USBIn.h). An index runs from 0 to +// 2 * ring_frames - 1. + +static uint32_t _ring_index_add(usb_host_audio_usbin_obj_t *self, uint32_t index, uint32_t frames) { + index += frames; + return index >= 2 * self->ring_frames ? index - 2 * self->ring_frames : index; +} + +static uint32_t _ring_frames_between(usb_host_audio_usbin_obj_t *self, uint32_t from, uint32_t to) { + return to >= from ? to - from : to + 2 * self->ring_frames - from; +} + +static uint8_t *_ring_at(usb_host_audio_usbin_obj_t *self, uint32_t index) { + return self->ring + (index >= self->ring_frames ? index - self->ring_frames : index) * self->frame_bytes; +} + +// Called by the completion callback only. static void _ring_append(usb_host_audio_usbin_obj_t *self, const uint8_t *data, uint32_t frames) { - if (frames > self->ring_frames) { - data += (frames - self->ring_frames) * self->wire_frame_bytes; - frames = self->ring_frames; - } - if (self->ring_count + frames > self->ring_frames) { - // Nothing is reading fast enough. Keep the newest audio. - uint32_t excess = self->ring_count + frames - self->ring_frames; - self->ring_head = (self->ring_head + excess) % self->ring_frames; - self->ring_count -= excess; - self->overflowed = true; - self->overflow = true; - } - uint32_t tail = (self->ring_head + self->ring_count) % self->ring_frames; - self->ring_count += frames; + uint32_t wr = self->ring_wr; + // The VM has read what it moved its index past. + uint32_t rd = __atomic_load_n(&self->ring_rd, __ATOMIC_ACQUIRE); + uint32_t room = self->ring_frames - _ring_frames_between(self, rd, wr); + if (frames > room) { + // Nothing is reading fast enough. The reader owns the oldest audio, so + // keep that and drop what doesn't fit. The reader skips ahead. + frames = room; + self->dropped++; + } while (frames > 0) { - uint32_t run = MIN(frames, self->ring_frames - tail); - uint8_t *dest = self->ring + tail * self->frame_bytes; + uint32_t offset = wr >= self->ring_frames ? wr - self->ring_frames : wr; + uint32_t run = MIN(frames, self->ring_frames - offset); + uint8_t *dest = _ring_at(self, wr); if (self->bit_depth > 16) { // Keep the top two bytes of each little endian 3 or 4 byte sample. const uint32_t sample_bytes = self->bit_depth / 8; @@ -79,23 +117,42 @@ static void _ring_append(usb_host_audio_usbin_obj_t *self, const uint8_t *data, memcpy(dest, data, run * self->frame_bytes); data += run * self->frame_bytes; } - tail = (tail + run) % self->ring_frames; + wr = _ring_index_add(self, wr, run); frames -= run; } + // Publish the frames after they are in the ring. + __atomic_store_n(&self->ring_wr, wr, __ATOMIC_RELEASE); +} + +// The frames waiting in the ring. VM only. +static uint32_t _ring_count(usb_host_audio_usbin_obj_t *self) { + uint32_t wr = __atomic_load_n(&self->ring_wr, __ATOMIC_ACQUIRE); + return _ring_frames_between(self, self->ring_rd, wr); } +// Takes frames, which must be waiting, out of the ring into dest, or drops them +// when dest is NULL. VM only. static void _ring_take(usb_host_audio_usbin_obj_t *self, uint8_t *dest, uint32_t frames) { - uint32_t first = MIN(frames, self->ring_frames - self->ring_head); + uint32_t rd = self->ring_rd; if (dest != NULL) { - memcpy(dest, self->ring + self->ring_head * self->frame_bytes, first * self->frame_bytes); + uint32_t offset = rd >= self->ring_frames ? rd - self->ring_frames : rd; + uint32_t first = MIN(frames, self->ring_frames - offset); + memcpy(dest, _ring_at(self, rd), first * self->frame_bytes); memcpy(dest + first * self->frame_bytes, self->ring, (frames - first) * self->frame_bytes); } - self->ring_head = (self->ring_head + frames) % self->ring_frames; - self->ring_count -= frames; + // The callback may write over the frames once the index is past them. + __atomic_store_n(&self->ring_rd, _ring_index_add(self, rd, frames), __ATOMIC_RELEASE); +} + +// Drops all the frames waiting. +static void _ring_drop_all(usb_host_audio_usbin_obj_t *self) { + _ring_take(self, NULL, _ring_count(self)); } static void _transfer_done_cb(tuh_xfer_t *xfer); +static void _stream_done(usb_host_audio_usbin_obj_t *self, tuh_xfer_t *xfer); +// Called with the lock held. static bool _queue_transfer(usb_host_audio_usbin_obj_t *self) { #if !CIRCUITPY_USB_HOST_ISO_RECORDS // The transfer receives the packet of the endpoint's next service interval. @@ -104,7 +161,7 @@ static bool _queue_transfer(usb_host_audio_usbin_obj_t *self) { if (self->frame_known) { uint16_t elapsed = (frame - self->queued_frame) & USBIN_FRAME_MASK; if (elapsed > self->frame_interval) { - self->overflow = true; + self->lost++; } } self->queued_frame = frame; @@ -122,13 +179,23 @@ static bool _queue_transfer(usb_host_audio_usbin_obj_t *self) { return self->streaming; } -// Runs inside tuh_task(), so as a background callback on core 0. +// Runs inside tuh_task(): a background callback on the VM, or a task of its +// own (CIRCUITPY_USB_HOST_TASK) that runs while the VM is busy. static void _transfer_done_cb(tuh_xfer_t *xfer) { + _lock_take(); usb_host_audio_usbin_obj_t *self = _active; if (self == NULL || xfer->user_data != _seq) { // Late completion of a stream that already ended. + _lock_give(); return; } + _stream_done(self, xfer); + _lock_give(); +} + +// Stores the audio of a completed transfer and queues the next one. Called +// with the lock held. +static void _stream_done(usb_host_audio_usbin_obj_t *self, tuh_xfer_t *xfer) { #if CIRCUITPY_USB_HOST_ISO_RECORDS if (xfer->result != XFER_RESULT_SUCCESS) { self->streaming = false; @@ -143,7 +210,7 @@ static void _transfer_done_cb(tuh_xfer_t *xfer) { uint32_t record_len = buf[pos] | (buf[pos + 1] << 8); pos += 2; if (record_len == USBIN_LOST_RECORD) { - self->overflow = true; + self->lost++; continue; } record_len = MIN(record_len, len - pos); @@ -160,7 +227,7 @@ static void _transfer_done_cb(tuh_xfer_t *xfer) { // A packet that was damaged or not received in its frame. Isochronous // packets are not retried. self->failures++; - self->overflow = true; + self->lost++; } else { self->streaming = false; return; @@ -244,12 +311,19 @@ void common_hal_usb_host_audio_usbin_construct(usb_host_audio_usbin_obj_t *self, self->output_buffer = NULL; self->output_index = 0; self->ring_frames = buffer_frames * USBIN_RING_BUFFERS; - self->ring_head = 0; - self->ring_count = 0; + self->ring_wr = 0; + self->ring_rd = 0; self->primed = false; - self->overflowed = false; - self->overflow = false; + self->dropped = 0; + self->lost = 0; + self->dropped_skipped = 0; + self->overflow_reported = 0; self->streaming = false; + #if OSAL_MUTEX_REQUIRED + if (_lock == NULL) { + _lock = osal_mutex_create(&_lock_def); + } + #endif if (!common_hal_usb_core_device_open_endpoint(device, endpoint)) { mp_raise_usb_core_USBError(NULL); @@ -298,9 +372,12 @@ void common_hal_usb_host_audio_usbin_construct(usb_host_audio_usbin_obj_t *self, m_malloc_fail(ring_bytes + self->xfer_buffer_len); } + _lock_take(); _seq++; _active = self; - if (!_queue_transfer(self)) { + bool queued = _queue_transfer(self); + _lock_give(); + if (!queued) { common_hal_usb_host_audio_usbin_deinit(self); mp_raise_usb_core_USBError(NULL); } @@ -321,6 +398,7 @@ void common_hal_usb_host_audio_usbin_deinit(usb_host_audio_usbin_obj_t *self) { _stop_device(self); } if (_active == self) { + _lock_take(); if (self->streaming) { // It fails when the device is gone, and then its endpoints are // closed already. @@ -332,6 +410,7 @@ void common_hal_usb_host_audio_usbin_deinit(usb_host_audio_usbin_obj_t *self) { // Drop a completion that is queued already. _seq++; _active = NULL; + _lock_give(); #if CIRCUITPY_USB_HOST_ISO_RECORDS // Whatever ended the stream also stopped the host controller writing // to its ring, and once the abort returned it no longer writes the @@ -353,7 +432,6 @@ void common_hal_usb_host_audio_usbin_deinit(usb_host_audio_usbin_obj_t *self) { self->ring = NULL; self->output_buffer = NULL; self->device = NULL; - self->ring_count = 0; } void usb_host_audio_reset(void) { @@ -367,6 +445,7 @@ void usb_host_audio_stop_device(uint8_t device_address) { if (self == NULL || self->device_address != device_address) { return; } + _lock_take(); if (self->streaming) { // The host controller stops polling the endpoint when it sends the // request. A transfer queued after that would start polling it again, @@ -379,20 +458,18 @@ void usb_host_audio_stop_device(uint8_t device_address) { } // Drop a completion that is queued already, so it queues nothing. _seq++; + _lock_give(); } uint32_t common_hal_usb_host_audio_usbin_record_to_buffer(usb_host_audio_usbin_obj_t *self, uint8_t *buffer, uint32_t length) { uint32_t frames = length / self->base.channel_count; uint32_t done = 0; - if (self->overflowed) { - // There is a gap behind the buffered audio. Record what comes after it. - _ring_take(self, NULL, self->ring_count); - self->overflowed = false; - } + // A full ring keeps the older audio, so what is waiting comes before any + // gap and is recorded too. uint32_t last_audio = supervisor_ticks_ms32(); while (done < frames) { - uint32_t take = MIN(frames - done, self->ring_count); + uint32_t take = MIN(frames - done, _ring_count(self)); if (take > 0) { _ring_take(self, buffer + done * self->frame_bytes, take); done += take; @@ -403,7 +480,7 @@ uint32_t common_hal_usb_host_audio_usbin_record_to_buffer(usb_host_audio_usbin_o supervisor_ticks_ms32() - last_audio > USBIN_RECORD_TIMEOUT_MS) { break; } - // The background tasks include TinyUSB, which fills the ring. + // TinyUSB fills the ring, in the background tasks or in a task of its own. RUN_BACKGROUND_TASKS; } return done * self->base.channel_count; @@ -418,17 +495,21 @@ bool common_hal_usb_host_audio_usbin_get_samples_signed(usb_host_audio_usbin_obj } bool common_hal_usb_host_audio_usbin_get_streaming(usb_host_audio_usbin_obj_t *self) { - // Closing the endpoint, as usb.core.Device.set_configuration() does, ends - // the transfer without a completion. - if (self->streaming && !usbh_edpt_busy(self->device_address, self->endpoint)) { + // Unplugging the device ends the transfer without a completion. (usb.core + // stops the stream itself before it closes the endpoint.) The endpoint + // isn't busy for a moment after each completion, until the callback queues + // the next transfer, which a callback in a task of its own may be doing + // right now, so that doesn't tell. + if (self->streaming && !tuh_mounted(self->device_address)) { self->streaming = false; } return self->streaming; } bool common_hal_usb_host_audio_usbin_get_overflow(usb_host_audio_usbin_obj_t *self) { - bool overflow = self->overflow; - self->overflow = false; + uint32_t count = self->dropped + self->lost; + bool overflow = count != self->overflow_reported; + self->overflow_reported = count; return overflow; } @@ -451,10 +532,10 @@ void common_hal_usb_host_audio_usbin_reset_buffer(usb_host_audio_usbin_obj_t *se self->output_index = 0; // Start on live audio rather than on what piled up while nothing played. // Dropping that is not an overflow. - _ring_take(self, NULL, self->ring_count); + _ring_drop_all(self); self->primed = false; - self->overflowed = false; - self->overflow = false; + self->dropped_skipped = self->dropped; + self->overflow_reported = self->dropped + self->lost; } static void _fill_silence(usb_host_audio_usbin_obj_t *self, uint8_t *buffer, uint32_t bytes) { @@ -525,20 +606,23 @@ audioio_get_buffer_result_t common_hal_usb_host_audio_usbin_get_buffer( self->output_index = 1 - self->output_index; uint32_t target = self->buffer_frames * USBIN_TARGET_BUFFERS; - if (self->overflowed) { + uint32_t count = _ring_count(self); + uint32_t dropped = self->dropped; + if (dropped != self->dropped_skipped) { // The consumer stalled or runs slower than the microphone. Skip ahead // so that the latency stays bounded. - self->overflowed = false; - if (self->ring_count > target) { - _ring_take(self, NULL, self->ring_count - target); + self->dropped_skipped = dropped; + if (count > target) { + _ring_take(self, NULL, count - target); + count = target; } } - if (!self->primed && self->ring_count >= target) { + if (!self->primed && count >= target) { self->primed = true; - self->level = self->ring_count << USBIN_LEVEL_SHIFT; + self->level = count << USBIN_LEVEL_SHIFT; self->drift = 0; } - if (self->primed && self->ring_count >= self->buffer_frames) { + if (self->primed && count >= self->buffer_frames) { // The microphone's clock and the consumer's drift apart, which shows // as a slow change of how much audio is waiting. The count at any one // call depends on when both sides were last serviced, so follow its @@ -547,12 +631,12 @@ audioio_get_buffer_result_t common_hal_usb_host_audio_usbin_get_buffer( // the differences says when. That spreads the corrections evenly, // where correcting only beyond a threshold would bunch them up into // an audible wobble of the pitch. - self->level += (int32_t)self->ring_count - (int32_t)(self->level >> USBIN_LEVEL_SHIFT); + self->level += (int32_t)count - (int32_t)(self->level >> USBIN_LEVEL_SHIFT); const int32_t every = self->buffer_frames; self->drift += (int32_t)(self->level >> USBIN_LEVEL_SHIFT) - (int32_t)target; self->drift = MAX(-2 * every, MIN(2 * every, self->drift)); uint32_t take = self->buffer_frames; - if (self->drift >= every && self->ring_count > take) { + if (self->drift >= every && count > take) { take++; self->drift -= every; } else if (self->drift <= -every) { diff --git a/shared-module/usb_host_audio/USBIn.h b/shared-module/usb_host_audio/USBIn.h index 439e7a8e558..607ad5bf215 100644 --- a/shared-module/usb_host_audio/USBIn.h +++ b/shared-module/usb_host_audio/USBIn.h @@ -10,10 +10,22 @@ #include "shared-module/audiocore/__init__.h" #include "shared-module/usb/core/Device.h" +#include "supervisor/usb.h" // The PCM ring holds this many get_buffer() buffers. Playback starts, and // restarts after an underrun, once USBIN_TARGET_BUFFERS of them are waiting. +// The ring is what holds the stream while its consumer is held up. Where +// TinyUSB runs in a task of its own, packets keep arriving while the VM is +// held up by other workp. A consumer that doesn't catch up afterwards, such as +// an audio output, is left with up to that much more latency, which drift +// correction then takes out slowly. +#ifndef USBIN_RING_BUFFERS +#if CIRCUITPY_USB_HOST_TASK +#define USBIN_RING_BUFFERS (32) +#else #define USBIN_RING_BUFFERS (8) +#endif +#endif #define USBIN_TARGET_BUFFERS (2) #define USBIN_NO_INTERFACE (0xff) @@ -30,24 +42,33 @@ typedef struct { uint8_t wire_frame_bytes; uint8_t frame_bytes; // A transfer is queued. False once the stream stopped - bool streaming; + volatile bool streaming; // Both buffers below are outside the VM heap; NULL xfer_buffer means deinited. uint8_t *xfer_buffer; uint16_t xfer_buffer_len; - // Converted PCM frames. Filled by the transfer's completion callback and - // drained by get_buffer() and record(). All of them run on core 0 outside - // interrupts (TinyUSB's task and the audio refill are background callbacks). + // Converted PCM frames. Filled by the transfer's completion callback, which + // runs in tuh_task(), and drained by get_buffer(), record() and + // reset_buffer() on the VM. tuh_task() may be a task of its own + // (CIRCUITPY_USB_HOST_TASK), so the ring has one writer and one reader that + // each move only their own index: ring_wr is the callback's, ring_rd the + // VM's. Both run from 0 to 2 * ring_frames - 1, so that a full ring and an + // empty one differ. uint8_t *ring; uint32_t ring_frames; - uint32_t ring_head; - uint32_t ring_count; + uint32_t ring_wr; + uint32_t ring_rd; uint32_t buffer_frames; bool primed; - // The ring dropped audio; the next reader skips ahead. - bool overflowed; - // Audio was dropped since the user last read the overflow property. - bool overflow; - // Average of ring_count as get_buffer() finds it, scaled by 2^USBIN_LEVEL_SHIFT. + // Counted by the callback: times the ring was full and audio was dropped, + // and packets that were lost before they got to the ring. The VM compares + // them with the counts it last acted on. + volatile uint32_t dropped; + volatile uint32_t lost; + // dropped when get_buffer() last skipped ahead. + uint32_t dropped_skipped; + // dropped + lost when the user last read the overflow property. + uint32_t overflow_reported; + // Average of the frames waiting as get_buffer() finds them, scaled by 2^USBIN_LEVEL_SHIFT. uint32_t level; // Sum of how far level was from the target, less what was corrected. int32_t drift; diff --git a/supervisor/shared/usb/host_keyboard.c b/supervisor/shared/usb/host_keyboard.c index de4f719d175..b00ab35e33e 100644 --- a/supervisor/shared/usb/host_keyboard.c +++ b/supervisor/shared/usb/host_keyboard.c @@ -44,6 +44,25 @@ static uint8_t _report_kbd_report_id; static uint8_t user_keymap[384]; static size_t user_keymap_len = 0; +// The TinyUSB callbacks below run in tuh_task(), which may be a task of its own +// (CIRCUITPY_USB_HOST_TASK), while the VM reads keys, repeats them and attaches +// and detaches the keyboard. This lock keeps them apart. Without an RTOS it is +// nothing. Nothing waits for TinyUSB while holding it. +#if OSAL_MUTEX_REQUIRED +static osal_mutex_def_t _lock_def; +static osal_mutex_t _lock; +#else +#define _lock NULL +#endif + +static void _lock_take(void) { + (void)osal_mutex_lock(_lock, OSAL_TIMEOUT_WAIT_FOREVER); +} + +static void _lock_give(void) { + (void)osal_mutex_unlock(_lock); +} + void usb_keymap_set(const uint8_t *buf, size_t len) { user_keymap_len = len = MIN(len, sizeof(user_keymap)); memcpy(user_keymap, buf, len); @@ -205,7 +224,9 @@ static void send_repeat(void) { } static void repeat_f(void *unused) { + _lock_take(); send_repeat(); + _lock_give(); } hid_keyboard_report_t old_report; @@ -322,7 +343,9 @@ bool usb_keyboard_in_use(uint8_t dev_addr, uint8_t interface) { } void usb_keyboard_detach(uint8_t dev_addr, uint8_t interface) { + _lock_take(); if (!usb_keyboard_in_use(dev_addr, interface)) { + _lock_give(); return; } // No more key repeats @@ -331,11 +354,14 @@ void usb_keyboard_detach(uint8_t dev_addr, uint8_t interface) { tuh_hid_receive_abort(dev_addr, interface); _dev_addr = 0; _interface = 0; + _lock_give(); supervisor_status_bar_request_update(false); } void usb_keyboard_attach(uint8_t dev_addr, uint8_t interface) { + _lock_take(); if (usb_keyboard_in_use(dev_addr, interface) || _dev_addr != 0) { + _lock_give(); return; } uint8_t const itf_protocol = tuh_hid_interface_protocol(dev_addr, interface); @@ -348,6 +374,7 @@ void usb_keyboard_attach(uint8_t dev_addr, uint8_t interface) { _interface = interface; tuh_hid_receive_report(dev_addr, interface); } + _lock_give(); supervisor_status_bar_request_update(false); } @@ -357,6 +384,7 @@ void tuh_hid_mount_cb(uint8_t dev_addr, uint8_t interface, uint8_t const *desc_r // Otherwise its interrupt IN endpoint is never drained, and a CircuitPython // device plugged into us raises OSError("USB busy") on its second // send_report() (#10721). + _lock_take(); if (tuh_hid_interface_protocol(dev_addr, interface) == HID_ITF_PROTOCOL_NONE && _report_kbd_dev_addr == 0) { tuh_hid_report_info_t report_info[8]; @@ -372,19 +400,23 @@ void tuh_hid_mount_cb(uint8_t dev_addr, uint8_t interface, uint8_t const *desc_r } } } + _lock_give(); usb_keyboard_attach(dev_addr, interface); } void tuh_hid_umount_cb(uint8_t dev_addr, uint8_t interface) { + _lock_take(); if (dev_addr == _report_kbd_dev_addr && interface == _report_kbd_interface) { _report_kbd_dev_addr = 0; _report_kbd_interface = 0; _report_kbd_report_id = 0; } + _lock_give(); usb_keyboard_detach(dev_addr, interface); } void tuh_hid_report_received_cb(uint8_t dev_addr, uint8_t instance, uint8_t const *report, uint16_t len) { + _lock_take(); if (len == sizeof(hid_keyboard_report_t)) { process_event(dev_addr, instance, (hid_keyboard_report_t *)report); } else if (dev_addr == _report_kbd_dev_addr && instance == _report_kbd_interface && @@ -394,6 +426,7 @@ void tuh_hid_report_received_cb(uint8_t dev_addr, uint8_t instance, uint8_t cons // Report-protocol keyboards prefix the report with its report ID. process_event(dev_addr, instance, (const hid_keyboard_report_t *)(report + 1)); } + _lock_give(); // Always request the next report, even when this one wasn't a keyboard // report we understand (a mouse or consumer control report ID from a // composite device, for instance), so that the device's endpoint keeps @@ -402,18 +435,32 @@ void tuh_hid_report_received_cb(uint8_t dev_addr, uint8_t instance, uint8_t cons } void usb_keyboard_init(void) { + #if OSAL_MUTEX_REQUIRED + // This runs again for each VM, while the keyboard may stay attached. + if (_lock == NULL) { + _lock = osal_mutex_create(&_lock_def); + } + #endif + _lock_take(); ringbuf_init(&_incoming_ringbuf, _buf, sizeof(_buf)); + _lock_give(); } uint32_t usb_keyboard_chars_available(void) { - return ringbuf_num_filled(&_incoming_ringbuf); + _lock_take(); + uint32_t count = ringbuf_num_filled(&_incoming_ringbuf); + _lock_give(); + return count; } char usb_keyboard_read_char(void) { + char c = -1; + _lock_take(); if (ringbuf_num_filled(&_incoming_ringbuf) > 0) { - return ringbuf_get(&_incoming_ringbuf); + c = ringbuf_get(&_incoming_ringbuf); } - return -1; + _lock_give(); + return c; } void usb_keyboard_status(void) { diff --git a/supervisor/shared/usb/usb.c b/supervisor/shared/usb/usb.c index c2be8998d44..fa8245ae6b2 100644 --- a/supervisor/shared/usb/usb.c +++ b/supervisor/shared/usb/usb.c @@ -177,7 +177,7 @@ void usb_background(void) { #elif CFG_TUSB_OS == OPT_OS_FREERTOS // TinyUSB may run in a separate task, at the same priority as CircuitPython. port_task_yield(); - #if CIRCUITPY_USB_HOST + #if CIRCUITPY_USB_HOST && !CIRCUITPY_USB_HOST_TASK if (tuh_inited()) { tuh_task_ext(0, false); } diff --git a/supervisor/usb.h b/supervisor/usb.h index 02953509ab5..67dfaae2e74 100644 --- a/supervisor/usb.h +++ b/supervisor/usb.h @@ -19,6 +19,14 @@ void usb_background(void); // Schedule usb background void usb_background_schedule(void); +#include "py/mpconfig.h" +// The port runs tuh_task() in a task of its own rather than from +// usb_background(). TinyUSB host callbacks then run outside the VM's task, so +// what they share with the VM has to be safe for that. +#ifndef CIRCUITPY_USB_HOST_TASK +#define CIRCUITPY_USB_HOST_TASK (0) +#endif + // Ports must call this from their particular USB IRQ handler void usb_irq_handler(int instance); From cff74950a933f325ac6203e083824a89fb2bc93f Mon Sep 17 00:00:00 2001 From: foamyguy Date: Thu, 19 Nov 2026 15:56:36 -0600 Subject: [PATCH 2/4] disable max3421e on esp32s2_devkitc_1_n8r2 --- .../boards/espressif_esp32c61_devkitc_1_n8r2/mpconfigboard.mk | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ports/espressif/boards/espressif_esp32c61_devkitc_1_n8r2/mpconfigboard.mk b/ports/espressif/boards/espressif_esp32c61_devkitc_1_n8r2/mpconfigboard.mk index 1092a874a68..d0463f70fc1 100644 --- a/ports/espressif/boards/espressif_esp32c61_devkitc_1_n8r2/mpconfigboard.mk +++ b/ports/espressif/boards/espressif_esp32c61_devkitc_1_n8r2/mpconfigboard.mk @@ -11,3 +11,5 @@ CIRCUITPY_ESP_FLASH_SIZE = 8MB CIRCUITPY_ESP_PSRAM_SIZE = 2MB CIRCUITPY_ESP_PSRAM_MODE = qio CIRCUITPY_ESP_PSRAM_FREQ = 80m + +CIRCUITPY_MAX3421E = 0 From 4537ea57a8eade59471bc56021565df2be4a65db Mon Sep 17 00:00:00 2001 From: foamyguy Date: Thu, 19 Nov 2026 16:24:07 -0600 Subject: [PATCH 3/4] disable max3421e on esp32s2_devkitc_1_n8r2 (correct mk file) --- .../boards/espressif_esp32c61_devkitc_1_n8r2/mpconfigboard.mk | 2 -- .../boards/espressif_esp32s2_devkitc_1_n8r2/mpconfigboard.mk | 2 ++ 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ports/espressif/boards/espressif_esp32c61_devkitc_1_n8r2/mpconfigboard.mk b/ports/espressif/boards/espressif_esp32c61_devkitc_1_n8r2/mpconfigboard.mk index d0463f70fc1..1092a874a68 100644 --- a/ports/espressif/boards/espressif_esp32c61_devkitc_1_n8r2/mpconfigboard.mk +++ b/ports/espressif/boards/espressif_esp32c61_devkitc_1_n8r2/mpconfigboard.mk @@ -11,5 +11,3 @@ CIRCUITPY_ESP_FLASH_SIZE = 8MB CIRCUITPY_ESP_PSRAM_SIZE = 2MB CIRCUITPY_ESP_PSRAM_MODE = qio CIRCUITPY_ESP_PSRAM_FREQ = 80m - -CIRCUITPY_MAX3421E = 0 diff --git a/ports/espressif/boards/espressif_esp32s2_devkitc_1_n8r2/mpconfigboard.mk b/ports/espressif/boards/espressif_esp32s2_devkitc_1_n8r2/mpconfigboard.mk index 4475b249b63..45becf7efd8 100644 --- a/ports/espressif/boards/espressif_esp32s2_devkitc_1_n8r2/mpconfigboard.mk +++ b/ports/espressif/boards/espressif_esp32s2_devkitc_1_n8r2/mpconfigboard.mk @@ -12,3 +12,5 @@ CIRCUITPY_ESP_FLASH_SIZE=8MB CIRCUITPY_ESP_PSRAM_SIZE = 2MB CIRCUITPY_ESP_PSRAM_MODE = qio CIRCUITPY_ESP_PSRAM_FREQ = 80m + +CIRCUITPY_MAX3421E = 0 From 8e2afd3b430b556736f173554ab1e7ae685239ae Mon Sep 17 00:00:00 2001 From: foamyguy Date: Sat, 21 Nov 2026 11:11:18 -0600 Subject: [PATCH 4/4] use existing ringbuf, add discard_n function --- ports/unix/coverage.c | 29 +++++ py/ringbuf.c | 48 +++++--- py/ringbuf.h | 1 + shared-module/usb_host_audio/USBIn.c | 165 ++++++++++++--------------- shared-module/usb_host_audio/USBIn.h | 34 +++--- tests/unix/extra_coverage.py.exp | 11 ++ 6 files changed, 161 insertions(+), 127 deletions(-) diff --git a/ports/unix/coverage.c b/ports/unix/coverage.c index 8809148652f..b15bef1cabc 100644 --- a/ports/unix/coverage.c +++ b/ports/unix/coverage.c @@ -917,6 +917,35 @@ static mp_obj_t extra_coverage(void) { ringbuf_clear(&ringbuf); ringbuf_put(&ringbuf, 0xaa); mp_printf(&mp_plat_print, "%d\n", ringbuf_get16(&ringbuf)); + + // Multi-byte put/get that wrap around, and discard. + { + byte data[RINGBUF_SIZE + 1]; + byte out[RINGBUF_SIZE + 1]; + for (int i = 0; i < RINGBUF_SIZE + 1; ++i) { + data[i] = i; + } + ringbuf_clear(&ringbuf); + for (int i = 0; i < RINGBUF_SIZE - 10; ++i) { + ringbuf_put(&ringbuf, i); + ringbuf_get(&ringbuf); + } + // 20 bytes from 10 before the end: wraps. + mp_printf(&mp_plat_print, "%d\n", (int)ringbuf_put_n(&ringbuf, data, 20)); + mp_printf(&mp_plat_print, "%d %d\n", (int)ringbuf_num_empty(&ringbuf), (int)ringbuf_num_filled(&ringbuf)); + // Only what fits. + mp_printf(&mp_plat_print, "%d\n", (int)ringbuf_put_n(&ringbuf, data + 20, RINGBUF_SIZE + 1 - 20)); + mp_printf(&mp_plat_print, "%d %d\n", (int)ringbuf_num_empty(&ringbuf), (int)ringbuf_num_filled(&ringbuf)); + mp_printf(&mp_plat_print, "%d\n", (int)ringbuf_put_n(&ringbuf, data, 1)); + // Discard 5, then get what is left, which wraps. + mp_printf(&mp_plat_print, "%d\n", (int)ringbuf_discard_n(&ringbuf, 5)); + mp_printf(&mp_plat_print, "%d\n", (int)ringbuf_get_n(&ringbuf, out, sizeof(out))); + mp_printf(&mp_plat_print, "%d\n", memcmp(out, data + 5, RINGBUF_SIZE - 5) == 0); + mp_printf(&mp_plat_print, "%d %d\n", (int)ringbuf_num_empty(&ringbuf), (int)ringbuf_num_filled(&ringbuf)); + // Nothing to get or discard. + mp_printf(&mp_plat_print, "%d\n", (int)ringbuf_get_n(&ringbuf, out, 1)); + mp_printf(&mp_plat_print, "%d\n", (int)ringbuf_discard_n(&ringbuf, 1)); + } } // pairheap diff --git a/py/ringbuf.c b/py/ringbuf.c index b81f671fdd9..c97b6350db4 100644 --- a/py/ringbuf.c +++ b/py/ringbuf.c @@ -9,6 +9,9 @@ // CIRCUITPY-CHANGE: API and implementation thoroughly reworked // No attempt to have atomic operations. Add guards if atomicity required. +#include + +#include "py/misc.h" #include "ringbuf.h" bool ringbuf_init(ringbuf_t *r, uint8_t *buf, size_t size) { @@ -103,24 +106,41 @@ size_t ringbuf_num_filled(ringbuf_t *r) { // If the ring buffer fills up, not all bytes will be written. // Returns how many bytes were successfully written. size_t ringbuf_put_n(ringbuf_t *r, const uint8_t *buf, size_t bufsize) { - for (size_t i = 0; i < bufsize; i++) { - if (ringbuf_put(r, buf[i]) < 0) { - // If ringbuf is full, give up and return how many bytes - // we wrote so far. - return i; - } + size_t n = MIN(bufsize, r->size - r->used); + if (n == 0) { + return 0; + } + // At most two copies: up to the end of buf, then from its start. + size_t first = MIN(n, r->size - r->next_write); + memcpy(r->buf + r->next_write, buf, first); + memcpy(r->buf, buf + first, n - first); + r->next_write += n; + if (r->next_write >= r->size) { + r->next_write -= r->size; } - return bufsize; + r->used += n; + return n; } // Returns how many bytes were fetched. size_t ringbuf_get_n(ringbuf_t *r, uint8_t *buf, size_t bufsize) { - for (size_t i = 0; i < bufsize; i++) { - int b = ringbuf_get(r); - if (b < 0) { - return i; - } - buf[i] = b; + size_t n = MIN(bufsize, r->used); + if (n == 0) { + return 0; + } + size_t first = MIN(n, r->size - r->next_read); + memcpy(buf, r->buf + r->next_read, first); + memcpy(buf + first, r->buf, n - first); + return ringbuf_discard_n(r, n); +} + +// Drops up to n of the oldest bytes. Returns how many were dropped. +size_t ringbuf_discard_n(ringbuf_t *r, size_t n) { + n = MIN(n, r->used); + r->next_read += n; + if (r->next_read >= r->size) { + r->next_read -= r->size; } - return bufsize; + r->used -= n; + return n; } diff --git a/py/ringbuf.h b/py/ringbuf.h index 52f50cd9c0b..120153093a9 100644 --- a/py/ringbuf.h +++ b/py/ringbuf.h @@ -40,6 +40,7 @@ size_t ringbuf_num_empty(ringbuf_t *r); size_t ringbuf_num_filled(ringbuf_t *r); size_t ringbuf_put_n(ringbuf_t *r, const uint8_t *buf, size_t bufsize); size_t ringbuf_get_n(ringbuf_t *r, uint8_t *buf, size_t bufsize); +size_t ringbuf_discard_n(ringbuf_t *r, size_t n); // Note: big-endian. Return -1 if can't read or write two bytes. int ringbuf_get16(ringbuf_t *r); diff --git a/shared-module/usb_host_audio/USBIn.c b/shared-module/usb_host_audio/USBIn.c index ec23c1dd173..9f766fba9e0 100644 --- a/shared-module/usb_host_audio/USBIn.c +++ b/shared-module/usb_host_audio/USBIn.c @@ -51,12 +51,15 @@ static usb_host_audio_usbin_obj_t *_active; static uintptr_t _seq; // The completion callback runs in tuh_task(), which may be a task of its own -// (CIRCUITPY_USB_HOST_TASK). It holds this lock while it uses _active and -// queues the next transfer, and the VM holds it while it changes _active or -// _seq or aborts the transfer. Then a callback never queues a transfer, or -// writes the ring, of a stream that the VM ended and is freeing. Without an -// RTOS the callback runs on the VM, and the lock is nothing. The VM never -// holds it while it waits for TinyUSB, which would wait for the callback. +// (CIRCUITPY_USB_HOST_TASK). It holds this lock while it uses _active, writes +// the ring and queues the next transfer, and the VM holds it while it changes +// _active or _seq, aborts the transfer or uses the ring. Then a callback never +// queues a transfer, or writes the ring, of a stream that the VM ended and is +// freeing, and the ring has one user at a time. Without +// an RTOS the callback runs on the VM, and the lock is nothing. The VM never +// holds it while it waits for TinyUSB, which would wait for the callback, and +// holds it only for a copy into or out of the ring. The callback holds it no +// longer than it takes to store one transfer. #if OSAL_MUTEX_REQUIRED static osal_mutex_def_t _lock_def; static osal_mutex_t _lock; @@ -72,81 +75,54 @@ static void _lock_give(void) { (void)osal_mutex_unlock(_lock); } -// The PCM ring is written by the completion callback and read by the VM, each -// moving only its own index (see USBIn.h). An index runs from 0 to -// 2 * ring_frames - 1. +// The PCM ring holds whole frames. It is used with the lock held. -static uint32_t _ring_index_add(usb_host_audio_usbin_obj_t *self, uint32_t index, uint32_t frames) { - index += frames; - return index >= 2 * self->ring_frames ? index - 2 * self->ring_frames : index; -} - -static uint32_t _ring_frames_between(usb_host_audio_usbin_obj_t *self, uint32_t from, uint32_t to) { - return to >= from ? to - from : to + 2 * self->ring_frames - from; -} - -static uint8_t *_ring_at(usb_host_audio_usbin_obj_t *self, uint32_t index) { - return self->ring + (index >= self->ring_frames ? index - self->ring_frames : index) * self->frame_bytes; -} +// Room for this many bytes of narrowed samples on the stack. +#define USBIN_NARROW_CHUNK (128) // Called by the completion callback only. static void _ring_append(usb_host_audio_usbin_obj_t *self, const uint8_t *data, uint32_t frames) { - uint32_t wr = self->ring_wr; - // The VM has read what it moved its index past. - uint32_t rd = __atomic_load_n(&self->ring_rd, __ATOMIC_ACQUIRE); - uint32_t room = self->ring_frames - _ring_frames_between(self, rd, wr); + uint32_t room = ringbuf_num_empty(&self->ring) / self->frame_bytes; if (frames > room) { - // Nothing is reading fast enough. The reader owns the oldest audio, so - // keep that and drop what doesn't fit. The reader skips ahead. + // Nothing is reading fast enough. Keep the older audio, which comes + // before the gap, and drop what doesn't fit. The reader skips ahead. frames = room; - self->dropped++; - } - while (frames > 0) { - uint32_t offset = wr >= self->ring_frames ? wr - self->ring_frames : wr; - uint32_t run = MIN(frames, self->ring_frames - offset); - uint8_t *dest = _ring_at(self, wr); - if (self->bit_depth > 16) { - // Keep the top two bytes of each little endian 3 or 4 byte sample. - const uint32_t sample_bytes = self->bit_depth / 8; - for (uint32_t i = 0; i < run * self->base.channel_count; i++) { - *dest++ = data[sample_bytes - 2]; - *dest++ = data[sample_bytes - 1]; - data += sample_bytes; - } - } else { - memcpy(dest, data, run * self->frame_bytes); - data += run * self->frame_bytes; + self->overflowed = true; + self->overflow = true; + } + if (self->bit_depth <= 16) { + ringbuf_put_n(&self->ring, data, frames * self->frame_bytes); + return; + } + // Keep the top two bytes of each little endian 3 or 4 byte sample. + const uint32_t sample_bytes = self->bit_depth / 8; + uint32_t samples = frames * self->base.channel_count; + uint8_t narrowed[USBIN_NARROW_CHUNK]; + while (samples > 0) { + uint32_t n = MIN(samples, sizeof(narrowed) / 2); + for (uint32_t i = 0; i < n; i++) { + narrowed[2 * i] = data[sample_bytes - 2]; + narrowed[2 * i + 1] = data[sample_bytes - 1]; + data += sample_bytes; } - wr = _ring_index_add(self, wr, run); - frames -= run; + ringbuf_put_n(&self->ring, narrowed, 2 * n); + samples -= n; } - // Publish the frames after they are in the ring. - __atomic_store_n(&self->ring_wr, wr, __ATOMIC_RELEASE); } -// The frames waiting in the ring. VM only. +// The frames waiting in the ring. static uint32_t _ring_count(usb_host_audio_usbin_obj_t *self) { - uint32_t wr = __atomic_load_n(&self->ring_wr, __ATOMIC_ACQUIRE); - return _ring_frames_between(self, self->ring_rd, wr); + return ringbuf_num_filled(&self->ring) / self->frame_bytes; } // Takes frames, which must be waiting, out of the ring into dest, or drops them -// when dest is NULL. VM only. +// when dest is NULL. static void _ring_take(usb_host_audio_usbin_obj_t *self, uint8_t *dest, uint32_t frames) { - uint32_t rd = self->ring_rd; if (dest != NULL) { - uint32_t offset = rd >= self->ring_frames ? rd - self->ring_frames : rd; - uint32_t first = MIN(frames, self->ring_frames - offset); - memcpy(dest, _ring_at(self, rd), first * self->frame_bytes); - memcpy(dest + first * self->frame_bytes, self->ring, (frames - first) * self->frame_bytes); + ringbuf_get_n(&self->ring, dest, frames * self->frame_bytes); + } else { + ringbuf_discard_n(&self->ring, frames * self->frame_bytes); } - // The callback may write over the frames once the index is past them. - __atomic_store_n(&self->ring_rd, _ring_index_add(self, rd, frames), __ATOMIC_RELEASE); -} - -// Drops all the frames waiting. -static void _ring_drop_all(usb_host_audio_usbin_obj_t *self) { - _ring_take(self, NULL, _ring_count(self)); } static void _transfer_done_cb(tuh_xfer_t *xfer); @@ -161,7 +137,7 @@ static bool _queue_transfer(usb_host_audio_usbin_obj_t *self) { if (self->frame_known) { uint16_t elapsed = (frame - self->queued_frame) & USBIN_FRAME_MASK; if (elapsed > self->frame_interval) { - self->lost++; + self->overflow = true; } } self->queued_frame = frame; @@ -210,7 +186,7 @@ static void _stream_done(usb_host_audio_usbin_obj_t *self, tuh_xfer_t *xfer) { uint32_t record_len = buf[pos] | (buf[pos + 1] << 8); pos += 2; if (record_len == USBIN_LOST_RECORD) { - self->lost++; + self->overflow = true; continue; } record_len = MIN(record_len, len - pos); @@ -227,7 +203,7 @@ static void _stream_done(usb_host_audio_usbin_obj_t *self, tuh_xfer_t *xfer) { // A packet that was damaged or not received in its frame. Isochronous // packets are not retried. self->failures++; - self->lost++; + self->overflow = true; } else { self->streaming = false; return; @@ -310,14 +286,10 @@ void common_hal_usb_host_audio_usbin_construct(usb_host_audio_usbin_obj_t *self, self->base.max_buffer_length = self->output_half_bytes * 2; self->output_buffer = NULL; self->output_index = 0; - self->ring_frames = buffer_frames * USBIN_RING_BUFFERS; - self->ring_wr = 0; - self->ring_rd = 0; + ringbuf_init(&self->ring, NULL, 0); self->primed = false; - self->dropped = 0; - self->lost = 0; - self->dropped_skipped = 0; - self->overflow_reported = 0; + self->overflowed = false; + self->overflow = false; self->streaming = false; #if OSAL_MUTEX_REQUIRED if (_lock == NULL) { @@ -357,20 +329,20 @@ void common_hal_usb_host_audio_usbin_construct(usb_host_audio_usbin_obj_t *self, self->aborted = false; self->failures = 0; #endif - size_t ring_bytes = self->ring_frames * self->frame_bytes; - self->ring = port_malloc(ring_bytes, false); + size_t ring_bytes = buffer_frames * USBIN_RING_BUFFERS * self->frame_bytes; + uint8_t *ring = port_malloc(ring_bytes, false); // The host controller writes the transfer buffer. self->xfer_buffer = port_malloc(self->xfer_buffer_len, true); - if (self->ring == NULL || self->xfer_buffer == NULL) { + if (ring == NULL || self->xfer_buffer == NULL) { #if CIRCUITPY_USB_HOST_ISO_RECORDS common_hal_usb_host_port_release_iso_buffer(); #endif - port_free(self->ring); + port_free(ring); port_free(self->xfer_buffer); - self->ring = NULL; self->xfer_buffer = NULL; m_malloc_fail(ring_bytes + self->xfer_buffer_len); } + ringbuf_init(&self->ring, ring, ring_bytes); _lock_take(); _seq++; @@ -426,10 +398,10 @@ void common_hal_usb_host_audio_usbin_deinit(usb_host_audio_usbin_obj_t *self) { #endif self->streaming = false; port_free(self->xfer_buffer); - port_free(self->ring); + port_free(self->ring.buf); port_free(self->output_buffer); self->xfer_buffer = NULL; - self->ring = NULL; + ringbuf_deinit(&self->ring); self->output_buffer = NULL; self->device = NULL; } @@ -469,9 +441,11 @@ uint32_t common_hal_usb_host_audio_usbin_record_to_buffer(usb_host_audio_usbin_o // gap and is recorded too. uint32_t last_audio = supervisor_ticks_ms32(); while (done < frames) { + _lock_take(); uint32_t take = MIN(frames - done, _ring_count(self)); + _ring_take(self, buffer + done * self->frame_bytes, take); + _lock_give(); if (take > 0) { - _ring_take(self, buffer + done * self->frame_bytes, take); done += take; last_audio = supervisor_ticks_ms32(); continue; @@ -507,9 +481,10 @@ bool common_hal_usb_host_audio_usbin_get_streaming(usb_host_audio_usbin_obj_t *s } bool common_hal_usb_host_audio_usbin_get_overflow(usb_host_audio_usbin_obj_t *self) { - uint32_t count = self->dropped + self->lost; - bool overflow = count != self->overflow_reported; - self->overflow_reported = count; + _lock_take(); + bool overflow = self->overflow; + self->overflow = false; + _lock_give(); return overflow; } @@ -532,10 +507,12 @@ void common_hal_usb_host_audio_usbin_reset_buffer(usb_host_audio_usbin_obj_t *se self->output_index = 0; // Start on live audio rather than on what piled up while nothing played. // Dropping that is not an overflow. - _ring_drop_all(self); + _lock_take(); + ringbuf_clear(&self->ring); + self->overflowed = false; + self->overflow = false; + _lock_give(); self->primed = false; - self->dropped_skipped = self->dropped; - self->overflow_reported = self->dropped + self->lost; } static void _fill_silence(usb_host_audio_usbin_obj_t *self, uint8_t *buffer, uint32_t bytes) { @@ -593,7 +570,8 @@ static void _stretch(usb_host_audio_usbin_obj_t *self, uint8_t *out, const uint8 } } -// Called by the output backend's refill, so it must never block. +// Called by the output backend's refill, so it must never block. It waits for +// the lock at most while the completion callback stores one transfer. audioio_get_buffer_result_t common_hal_usb_host_audio_usbin_get_buffer( usb_host_audio_usbin_obj_t *self, bool single_channel_output, uint8_t channel, uint8_t **buffer, uint32_t *buffer_length) { @@ -606,12 +584,12 @@ audioio_get_buffer_result_t common_hal_usb_host_audio_usbin_get_buffer( self->output_index = 1 - self->output_index; uint32_t target = self->buffer_frames * USBIN_TARGET_BUFFERS; + _lock_take(); uint32_t count = _ring_count(self); - uint32_t dropped = self->dropped; - if (dropped != self->dropped_skipped) { + if (self->overflowed) { // The consumer stalled or runs slower than the microphone. Skip ahead // so that the latency stays bounded. - self->dropped_skipped = dropped; + self->overflowed = false; if (count > target) { _ring_take(self, NULL, count - target); count = target; @@ -645,12 +623,15 @@ audioio_get_buffer_result_t common_hal_usb_host_audio_usbin_get_buffer( } if (take == self->buffer_frames) { _ring_take(self, out, take); + _lock_give(); } else { uint8_t *stretch = self->output_buffer + self->output_half_bytes * 2; _ring_take(self, stretch, take); + _lock_give(); _stretch(self, out, stretch, take); } } else { + _lock_give(); // Play silence until enough audio is waiting again to ride out the // jitter in how both sides are serviced. self->primed = false; diff --git a/shared-module/usb_host_audio/USBIn.h b/shared-module/usb_host_audio/USBIn.h index 607ad5bf215..4ccb066fc75 100644 --- a/shared-module/usb_host_audio/USBIn.h +++ b/shared-module/usb_host_audio/USBIn.h @@ -7,6 +7,7 @@ #pragma once #include "py/obj.h" +#include "py/ringbuf.h" #include "shared-module/audiocore/__init__.h" #include "shared-module/usb/core/Device.h" @@ -16,7 +17,7 @@ // restarts after an underrun, once USBIN_TARGET_BUFFERS of them are waiting. // The ring is what holds the stream while its consumer is held up. Where // TinyUSB runs in a task of its own, packets keep arriving while the VM is -// held up by other workp. A consumer that doesn't catch up afterwards, such as +// held up by other work. A consumer that doesn't catch up afterwards, such as // an audio output, is left with up to that much more latency, which drift // correction then takes out slowly. #ifndef USBIN_RING_BUFFERS @@ -46,28 +47,19 @@ typedef struct { // Both buffers below are outside the VM heap; NULL xfer_buffer means deinited. uint8_t *xfer_buffer; uint16_t xfer_buffer_len; - // Converted PCM frames. Filled by the transfer's completion callback, which - // runs in tuh_task(), and drained by get_buffer(), record() and - // reset_buffer() on the VM. tuh_task() may be a task of its own - // (CIRCUITPY_USB_HOST_TASK), so the ring has one writer and one reader that - // each move only their own index: ring_wr is the callback's, ring_rd the - // VM's. Both run from 0 to 2 * ring_frames - 1, so that a full ring and an - // empty one differ. - uint8_t *ring; - uint32_t ring_frames; - uint32_t ring_wr; - uint32_t ring_rd; + // Converted PCM frames, whole ones only. Filled by the transfer's + // completion callback, which runs in tuh_task(), and drained by + // get_buffer(), record() and reset_buffer() on the VM. tuh_task() may be a + // task of its own (CIRCUITPY_USB_HOST_TASK), so the ring, overflowed and + // overflow are only used with the lock in USBIn.c held. The buffer is + // outside the VM heap. + ringbuf_t ring; uint32_t buffer_frames; bool primed; - // Counted by the callback: times the ring was full and audio was dropped, - // and packets that were lost before they got to the ring. The VM compares - // them with the counts it last acted on. - volatile uint32_t dropped; - volatile uint32_t lost; - // dropped when get_buffer() last skipped ahead. - uint32_t dropped_skipped; - // dropped + lost when the user last read the overflow property. - uint32_t overflow_reported; + // The ring was full and audio was dropped; get_buffer() skips ahead. + bool overflowed; + // Audio was dropped since the user last read the overflow property. + bool overflow; // Average of the frames waiting as get_buffer() finds them, scaled by 2^USBIN_LEVEL_SHIFT. uint32_t level; // Sum of how far level was from the target, less what was corrected. diff --git a/tests/unix/extra_coverage.py.exp b/tests/unix/extra_coverage.py.exp index d474af62ea0..e4081976946 100644 --- a/tests/unix/extra_coverage.py.exp +++ b/tests/unix/extra_coverage.py.exp @@ -191,6 +191,17 @@ cc99 22ff -1 -1 +20 +79 20 +79 +0 99 +0 +5 +94 +1 +99 0 +0 +0 0 0 abc123