From 8bbb53de267f0a1329fff49ae3e974ad1fef4b99 Mon Sep 17 00:00:00 2001 From: foamyguy Date: Thu, 19 Nov 2026 10:30:32 -0600 Subject: [PATCH] USB host iso ring --- ports/espressif/Makefile | 3 + ports/espressif/common-hal/usb_host/Port.c | 75 ++++++++++++++++++++++ shared-bindings/usb_host_audio/USBIn.c | 26 ++++---- shared-module/usb_host_audio/USBIn.c | 22 +++++-- shared-module/usb_host_audio/USBIn.h | 5 ++ supervisor/shared/usb/tusb_config.h | 2 + 6 files changed, 114 insertions(+), 19 deletions(-) diff --git a/ports/espressif/Makefile b/ports/espressif/Makefile index c972a835326..0352798fcf3 100644 --- a/ports/espressif/Makefile +++ b/ports/espressif/Makefile @@ -245,6 +245,9 @@ REGISTRATION_FUNCTIONS = \ # supervisor/port.c aligns the PSRAM heap areas to the same value. ifeq ($(IDF_TARGET),esp32p4) CFLAGS += -DMICROPY_BYTES_PER_GC_BLOCK=64 +# TinyUSB's DWC2 host driver keeps receiving isochronous IN packets between +# transfers (CFG_TUH_DWC2_ISO_RING, which needs its buffer DMA mode). +CFLAGS += -DCIRCUITPY_USB_HOST_ISO_RECORDS=1 endif # RISC-V picolibc ships optimized memcpy/memset/etc. that need forcing diff --git a/ports/espressif/common-hal/usb_host/Port.c b/ports/espressif/common-hal/usb_host/Port.c index 702d4889c31..826a875a2b3 100644 --- a/ports/espressif/common-hal/usb_host/Port.c +++ b/ports/espressif/common-hal/usb_host/Port.c @@ -5,8 +5,12 @@ // SPDX-License-Identifier: MIT #include "bindings/espidf/__init__.h" +#include "py/runtime.h" +#include "shared-bindings/microcontroller/__init__.h" #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/usb_host/Port.h" +#include "supervisor/port.h" +#include "supervisor/port_heap.h" #include "supervisor/usb.h" #include "supervisor/shared/tick.h" #include "esp_private/usb_phy.h" @@ -31,6 +35,21 @@ static usb_host_port_obj_t usb_host_instance; static usb_phy_handle_t host_phy; +#if CIRCUITPY_USB_HOST_ISO_RECORDS +// The ring that TinyUSB's DWC2 host driver keeps isochronous IN packets in +// between transfers, and the buffer each packet is received into first. +static uint8_t *_iso_ring = NULL; +static uint8_t *_iso_packet = NULL; +// The largest isochronous packet of a full or high speed endpoint, without +// high-bandwidth transactions. +#define ISO_PACKET_SIZE (1024) +// The largest ring. +#define ISO_RING_MAX (1024 * 1024) +// Once its channel is told to stop, the stream's last packet can still be +// received into the packet buffer until the end of the frame. +#define ISO_STOP_SETTLE_US (2000) +#endif + 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) { @@ -68,3 +87,59 @@ void tuh_event_hook_cb(uint8_t rhport, uint32_t eventid, bool in_isr) { // next transfer within the frame. usb_background_schedule(); } + +bool common_hal_usb_host_port_claim_iso_buffer(size_t size) { + #if CIRCUITPY_USB_HOST_ISO_RECORDS + // There is one ring, for one stream at a time. Ending an older stream + // here would take its packets from another user, so refuse instead. + if (_iso_ring != NULL) { + return false; + } + uint32_t rounded = 2048; + while (rounded < size && rounded < ISO_RING_MAX) { + rounded <<= 1; + } + // Only the CPU touches the ring, in the interrupt handler, so it can be in + // PSRAM. The controller writes the packet buffer by DMA. + uint8_t *ring = port_malloc(rounded, false); + uint8_t *packet = port_malloc(ISO_PACKET_SIZE, true); + if (ring == NULL || packet == NULL) { + port_free(ring); + port_free(packet); + m_malloc_fail(rounded + ISO_PACKET_SIZE); + } + const tuh_configure_dwc2_iso_ring_t config = { + .buffer = ring, + .size = rounded, + .packet_buffer = packet, + .packet_size = ISO_PACKET_SIZE, + }; + if (!tuh_configure(TUH_OPT_RHPORT, TUH_CFGID_DWC2_ISO_RING, &config)) { + port_free(ring); + port_free(packet); + return false; + } + _iso_ring = ring; + _iso_packet = packet; + return true; + #else + (void)size; + return false; + #endif +} + +void common_hal_usb_host_port_release_iso_buffer(void) { + #if CIRCUITPY_USB_HOST_ISO_RECORDS + if (_iso_ring == NULL) { + return; + } + // This also ends a stream into the ring that is still running. + const tuh_configure_dwc2_iso_ring_t config = { 0 }; + tuh_configure(TUH_OPT_RHPORT, TUH_CFGID_DWC2_ISO_RING, &config); + common_hal_mcu_delay_us(ISO_STOP_SETTLE_US); + port_free(_iso_ring); + port_free(_iso_packet); + _iso_ring = NULL; + _iso_packet = NULL; + #endif +} diff --git a/shared-bindings/usb_host_audio/USBIn.c b/shared-bindings/usb_host_audio/USBIn.c index 62255177f50..444cc2333f9 100644 --- a/shared-bindings/usb_host_audio/USBIn.c +++ b/shared-bindings/usb_host_audio/USBIn.c @@ -47,13 +47,15 @@ //| the microphone stops also when a ``with`` block is left by an //| exception, or when the program ends. //| -//| 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 +//| On RP2 boards, whose host port is PIO-USB, and on the ESP32-P4, the +//| host controller buffers the stream between reads, in a buffer of +//| ``iso_buffer_size`` bytes that `USBIn` allocates and `deinit` frees. +//| Packets that arrive while background tasks can't run, such as during a +//| long garbage collection or a write to an SD card, wait there. On other +//| boards whose host port is the chip's own USB controller 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`. +//| it arrives, and packets that arrive while background tasks can't run +//| are lost and set `overflow`. //| //| Only one isochronous IN endpoint is received at a time, so only one //| `USBIn` can stream, and a USB camera cannot stream video meanwhile. @@ -80,11 +82,11 @@ //| :param int max_packet_size: The endpoint's ``wMaxPacketSize`` //| :param int buffer_frames: The number of frames handed to the audio pipeline at a time //| :param int iso_buffer_size: The size in bytes of the host controller's buffer for -//| the stream, from 2048 to 65536, rounded up to a power of two. It holds the -//| packets that arrive while background tasks don't run, each with 2 bytes of -//| overhead: 16384 is about half a second of 16 kHz mono audio or 80 ms of 48 kHz -//| stereo. Only used on RP2 boards; ignored on the Metro ESP32-P4 and other -//| boards whose host port is the chip's own USB controller. +//| the stream, rounded up to a power of two: from 2048 to 65536 on RP2 boards, and +//| to 1048576 on the ESP32-P4. It holds the packets that arrive while background +//| tasks don't run, each with 2 bytes of overhead: 16384 is about half a second of +//| 16 kHz mono audio or 80 ms of 48 kHz stereo. Only used on RP2 boards and the +//| ESP32-P4; ignored on boards whose host port is another USB controller. //| //| Example, recording a second from the microphone of a Logitech C270 //| webcam. It streams 16 bit mono on interface 3, alternate setting 1, @@ -144,7 +146,7 @@ static mp_obj_t usb_host_audio_usbin_make_new(const mp_obj_type_t *type, size_t } mp_int_t max_packet_size = mp_arg_validate_int_range(args[ARG_max_packet_size].u_int, 0, 1024, MP_QSTR_max_packet_size); mp_int_t buffer_frames = mp_arg_validate_int_range(args[ARG_buffer_frames].u_int, 32, 4096, MP_QSTR_buffer_frames); - mp_int_t iso_buffer_size = mp_arg_validate_int_range(args[ARG_iso_buffer_size].u_int, 2048, 65536, MP_QSTR_iso_buffer_size); + mp_int_t iso_buffer_size = mp_arg_validate_int_range(args[ARG_iso_buffer_size].u_int, 2048, 1048576, MP_QSTR_iso_buffer_size); usb_host_audio_usbin_obj_t *self = mp_obj_malloc_with_finaliser(usb_host_audio_usbin_obj_t, &usb_host_audio_usbin_type); common_hal_usb_host_audio_usbin_construct(self, device, endpoint, sample_rate, channel_count, diff --git a/shared-module/usb_host_audio/USBIn.c b/shared-module/usb_host_audio/USBIn.c index 20863302778..361025ea5eb 100644 --- a/shared-module/usb_host_audio/USBIn.c +++ b/shared-module/usb_host_audio/USBIn.c @@ -24,7 +24,7 @@ // Room for a good number of records per transfer, for when the ring in the // host controller has a backlog. -#define USBIN_MIN_XFER_BUFFER (1024) +#define USBIN_MIN_XFER_BUFFER (4096) // The host controller marks lost packets with a record of this length. #define USBIN_LOST_RECORD (0xffff) // get_buffer() averages the frames waiting over about 2^this calls. @@ -255,9 +255,14 @@ void common_hal_usb_host_audio_usbin_construct(usb_host_audio_usbin_obj_t *self, mp_raise_usb_core_USBError(NULL); } const tusb_desc_endpoint_t *endpoint_desc = _find_endpoint(device, endpoint, &self->interface); + uint8_t interval = 1; + if (endpoint_desc != NULL) { + max_packet_size = tu_edpt_packet_size(endpoint_desc); + interval = endpoint_desc->bInterval; + } #if CIRCUITPY_USB_HOST_ISO_RECORDS - (void)endpoint_desc; + (void)interval; // The host controller keeps the packets that arrive between transfers in a // ring of its own. Only one isochronous stream at a time can use it. if (!common_hal_usb_host_port_claim_iso_buffer(iso_buffer_size)) { @@ -271,11 +276,6 @@ void common_hal_usb_host_audio_usbin_construct(usb_host_audio_usbin_obj_t *self, (void)iso_buffer_size; // Each transfer receives one packet. A longer one would ask for more // packets in the same frame. - uint8_t interval = 1; - if (endpoint_desc != NULL) { - max_packet_size = tu_edpt_packet_size(endpoint_desc); - interval = endpoint_desc->bInterval; - } mp_arg_validate_int_min(max_packet_size, 1, MP_QSTR_max_packet_size); self->xfer_buffer_len = max_packet_size; self->frame_interval = 1 << (MIN(MAX(interval, 1), 16) - 1); @@ -377,6 +377,14 @@ void usb_host_audio_stop_device(uint8_t device_address) { self->aborted = true; #endif } + #if CIRCUITPY_USB_HOST_ISO_RECORDS + // The host controller may poll the endpoint into its ring between + // transfers, which the abort above can't stop when no transfer was queued + // at that moment. Releasing the ring stops it, or, where the controller is + // still polling and can't give the ring back yet, keeps it claimed for + // deinit to release. + common_hal_usb_host_port_release_iso_buffer(); + #endif // Drop a completion that is queued already, so it queues nothing. _seq++; } diff --git a/shared-module/usb_host_audio/USBIn.h b/shared-module/usb_host_audio/USBIn.h index 439e7a8e558..56b05d4e134 100644 --- a/shared-module/usb_host_audio/USBIn.h +++ b/shared-module/usb_host_audio/USBIn.h @@ -13,8 +13,13 @@ // The PCM ring holds this many get_buffer() buffers. Playback starts, and // restarts after an underrun, once USBIN_TARGET_BUFFERS of them are waiting. +#if CIRCUITPY_USB_HOST_ISO_RECORDS +#define USBIN_RING_BUFFERS (32) +#define USBIN_TARGET_BUFFERS (4) +#else #define USBIN_RING_BUFFERS (8) #define USBIN_TARGET_BUFFERS (2) +#endif #define USBIN_NO_INTERFACE (0xff) typedef struct { diff --git a/supervisor/shared/usb/tusb_config.h b/supervisor/shared/usb/tusb_config.h index 5e7f9265e7a..571570b022a 100644 --- a/supervisor/shared/usb/tusb_config.h +++ b/supervisor/shared/usb/tusb_config.h @@ -174,6 +174,8 @@ extern "C" { #if defined(CONFIG_IDF_TARGET_ESP32P4) #define CFG_TUH_DWC2_DMA_ENABLE (1) +// Isochronous IN packets are kept in a ring between transfers. +#define CFG_TUH_DWC2_ISO_RING (CIRCUITPY_USB_HOST_ISO_RECORDS) #endif // Always use PIO to do host on RP2.