async_spi: SPI transfers for asyncio

async_spi.SPI is configured and locked like busio.SPI, and write(),
readinto() and write_readinto() are awaited: other tasks run during a
transfer. Tasks that share the bus can use an asyncio.Lock. Enabled on
raspberrypi. A manual test is in tests/circuitpython-manual/async_spi.

Co-authored-by: Marshal Horn <175229+kamocat@users.noreply.github.com>

Author: lynt-smitka

ports/raspberrypi/mpconfigport.mk

@@ -7,6 +7,7 @@ CIRCUITPY_WIFI_RADIO_SETTABLE_MAC_ADDRESS = 0
 
 CIRCUITPY_RP2PIO ?= 1
 CIRCUITPY_BUSIO_SPI_ASYNC ?= 1
+CIRCUITPY_ASYNC_SPI ?= $(call enable-if-all,$(MICROPY_PY_ASYNC_AWAIT) $(CIRCUITPY_BUSIO_SPI) $(CIRCUITPY_BUSIO_SPI_ASYNC))
 # The 24 KB stack has room for a larger display refresh buffer.
 CIRCUITPY_DISPLAY_AREA_BUFFER_SIZE ?= 2048
 CIRCUITPY_NEOPIXEL_WRITE ?= $(CIRCUITPY_RP2PIO)

py/circuitpy_defns.mk

@@ -116,6 +116,9 @@ endif
 ifeq ($(CIRCUITPY_ANALOGIO),1)
 SRC_PATTERNS += analogio/%
 endif
+ifeq ($(CIRCUITPY_ASYNC_SPI),1)
+SRC_PATTERNS += async_spi/%
+endif
 ifeq ($(CIRCUITPY_ATEXIT),1)
 SRC_PATTERNS += atexit/%
 endif
@@ -735,6 +738,8 @@ SRC_SHARED_MODULE_ALL = \
 	picogame/Canvas.c \
 	aesio/__init__.c \
 	aesio/aes.c \
+	async_spi/SPI.c \
+	async_spi/__init__.c \
 	atexit/__init__.c \
 	audiocore/RawSample.c \
 	audiocore/WaveFile.c \

shared-bindings/async_spi/SPI.c

@@ -0,0 +1,254 @@
+// This file is part of the CircuitPython project: https://circuitpython.org
+//
+// SPDX-FileCopyrightText: Copyright (c) 2026 Vladimir Smitka
+//
+// SPDX-License-Identifier: MIT
+
+#include <stdint.h>
+
+#include "supervisor/shared/awaitable.h"
+#include "py/binary.h"
+#include "py/objproperty.h"
+#include "py/runtime.h"
+
+#include "shared/runtime/buffer_helper.h"
+#include "shared/runtime/context_manager_helpers.h"
+#include "shared-bindings/async_spi/SPI.h"
+#include "shared-bindings/busio/SPI.h"
+#include "shared-bindings/util.h"
+
+//| class SPI:
+//|     """An SPI bus whose transfers are awaited
+//|
+//|     Configuration and locking work as in `busio.SPI`. ``write``, ``readinto`` and
+//|     ``write_readinto`` return awaitables: the transfer runs while other asyncio tasks run.
+//|     Short transfers, and transfers that cannot use DMA (for example from a buffer in flash),
+//|     block other tasks until they finish. A transfer's arguments are checked when the result is
+//|     awaited. To share the bus between tasks, hold an `asyncio.Lock` around each use."""
+//|
+//|     def __init__(
+//|         self,
+//|         clock: microcontroller.Pin,
+//|         MOSI: Optional[microcontroller.Pin] = None,
+//|         MISO: Optional[microcontroller.Pin] = None,
+//|     ) -> None:
+//|         """Construct an SPI object on the given pins.
+//|
+//|         :param ~microcontroller.Pin clock: the pin to use for the clock.
+//|         :param ~microcontroller.Pin MOSI: the Main Out Selected In pin.
+//|         :param ~microcontroller.Pin MISO: the Main In Selected Out pin."""
+//|         ...
+//|
+//  Provided by busio.SPI.
+
+static async_spi_spi_obj_t *locked_spi(mp_obj_t self_in) {
+    async_spi_spi_obj_t *self = MP_OBJ_TO_PTR(mp_arg_validate_type(self_in, &async_spi_spi_type, MP_QSTR_self));
+    if (common_hal_busio_spi_deinited(&self->spi)) {
+        raise_deinited_error();
+    }
+    if (!common_hal_busio_spi_has_lock(&self->spi)) {
+        mp_raise_RuntimeError(MP_ERROR_TEXT("Function requires lock"));
+    }
+    return self;
+}
+
+// buffer[start:end], with start and end in elements as in busio.SPI. Returns the slice's address
+// and sets *len to its length in bytes.
+static uint8_t *buffer_slice(mp_obj_t buffer, int32_t start, int32_t end, mp_uint_t flags, size_t *len) {
+    mp_buffer_info_t bufinfo;
+    mp_get_buffer_raise(buffer, &bufinfo, flags);
+    int stride_in_bytes = mp_binary_get_size('@', bufinfo.typecode, NULL);
+    size_t length = bufinfo.len / stride_in_bytes;
+    normalize_buffer_bounds(&start, end, &length);
+    *len = length * stride_in_bytes;
+    return (uint8_t *)bufinfo.buf + start * stride_in_bytes;
+}
+
+//|     def deinit(self) -> None:
+//|         """Turn off the SPI bus. A transfer still running is finished first."""
+//|         ...
+//|
+//  Provided by busio.SPI.
+
+//|     def __enter__(self) -> SPI:
+//|         """No-op used by Context Managers."""
+//|         ...
+//|
+//  Provided by context manager helper.
+
+//|     def __exit__(self) -> None:
+//|         """Automatically deinitializes the hardware when exiting a context. See
+//|         :ref:`lifetime-and-contextmanagers` for more info."""
+//|         ...
+//|
+//  Provided by context manager helper.
+
+//|     def configure(
+//|         self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8
+//|     ) -> None:
+//|         """Configure the SPI bus, as `busio.SPI.configure`. The bus must be locked."""
+//|         ...
+//|
+//  Provided by busio.SPI.
+
+//|     def try_lock(self) -> bool:
+//|         """Attempts to grab the SPI lock. Returns True on success."""
+//|         ...
+//|
+//  Provided by busio.SPI.
+
+//|     def unlock(self) -> None:
+//|         """Releases the SPI lock."""
+//|         ...
+//|
+//  Provided by busio.SPI.
+
+//|     import sys
+//|
+//|     async def write(
+//|         self, buffer: ReadableBuffer, *, start: int = 0, end: int = sys.maxsize
+//|     ) -> None:
+//|         """Write the data in ``buffer[start:end]``. The bus must be locked.
+//|
+//|         :param ~circuitpython_typing.ReadableBuffer buffer: write out the data in this buffer
+//|         :param int start: beginning of buffer slice
+//|         :param int end: end of buffer slice; if not specified, use ``len(buffer)``"""
+//|         ...
+//|
+static void *async_spi_spi_write(circuitpy_async_flag_t *done, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    enum { ARG_buffer, ARG_start, ARG_end };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_buffer, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_start, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0} },
+        { MP_QSTR_end, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = INT_MAX} },
+    };
+    async_spi_spi_obj_t *self = locked_spi(pos_args[0]);
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+
+    size_t len;
+    uint8_t *data = buffer_slice(args[ARG_buffer].u_obj, args[ARG_start].u_int, args[ARG_end].u_int,
+        MP_BUFFER_READ, &len);
+    common_hal_busio_spi_write_start(&self->spi, data, len, done);
+    return self;
+}
+static CIRCUITPY_DEFINE_ASYNC_FUN_OBJ_KW(async_spi_spi_write_obj, 1, async_spi_spi_write);
+
+//|     async def readinto(
+//|         self,
+//|         buffer: WriteableBuffer,
+//|         *,
+//|         start: int = 0,
+//|         end: int = sys.maxsize,
+//|         write_value: int = 0,
+//|     ) -> None:
+//|         """Read into ``buffer[start:end]`` while writing ``write_value`` for each byte read.
+//|         The bus must be locked.
+//|
+//|         :param ~circuitpython_typing.WriteableBuffer buffer: read data into this buffer
+//|         :param int start: beginning of buffer slice
+//|         :param int end: end of buffer slice; if not specified, use ``len(buffer)``
+//|         :param int write_value: value to write while reading"""
+//|         ...
+//|
+static void *async_spi_spi_readinto(circuitpy_async_flag_t *done, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    enum { ARG_buffer, ARG_start, ARG_end, ARG_write_value };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_buffer, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_start, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0} },
+        { MP_QSTR_end, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = INT_MAX} },
+        { MP_QSTR_write_value, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0} },
+    };
+    async_spi_spi_obj_t *self = locked_spi(pos_args[0]);
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+
+    size_t len;
+    uint8_t *data = buffer_slice(args[ARG_buffer].u_obj, args[ARG_start].u_int, args[ARG_end].u_int,
+        MP_BUFFER_WRITE, &len);
+    common_hal_busio_spi_read_start(&self->spi, data, len, (uint8_t)args[ARG_write_value].u_int, done);
+    return self;
+}
+static CIRCUITPY_DEFINE_ASYNC_FUN_OBJ_KW(async_spi_spi_readinto_obj, 1, async_spi_spi_readinto);
+
+//|     async def write_readinto(
+//|         self,
+//|         out_buffer: ReadableBuffer,
+//|         in_buffer: WriteableBuffer,
+//|         *,
+//|         out_start: int = 0,
+//|         out_end: int = sys.maxsize,
+//|         in_start: int = 0,
+//|         in_end: int = sys.maxsize,
+//|     ) -> None:
+//|         """Write out the data in ``out_buffer`` while simultaneously reading data into ``in_buffer``.
+//|         The two slices must have the same length. The bus must be locked.
+//|
+//|         :param ~circuitpython_typing.ReadableBuffer out_buffer: write out the data in this buffer
+//|         :param ~circuitpython_typing.WriteableBuffer in_buffer: read data into this buffer
+//|         :param int out_start: beginning of ``out_buffer`` slice
+//|         :param int out_end: end of ``out_buffer`` slice; if not specified, use ``len(out_buffer)``
+//|         :param int in_start: beginning of ``in_buffer`` slice
+//|         :param int in_end: end of ``in_buffer`` slice; if not specified, use ``len(in_buffer)``"""
+//|         ...
+//|
+static void *async_spi_spi_write_readinto(circuitpy_async_flag_t *done, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    enum { ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_out_buffer, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_in_buffer, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_out_start, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0} },
+        { MP_QSTR_out_end, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = INT_MAX} },
+        { MP_QSTR_in_start, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0} },
+        { MP_QSTR_in_end, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = INT_MAX} },
+    };
+    async_spi_spi_obj_t *self = locked_spi(pos_args[0]);
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+
+    size_t out_len, in_len;
+    const uint8_t *data_out = buffer_slice(args[ARG_out_buffer].u_obj, args[ARG_out_start].u_int,
+        args[ARG_out_end].u_int, MP_BUFFER_READ, &out_len);
+    uint8_t *data_in = buffer_slice(args[ARG_in_buffer].u_obj, args[ARG_in_start].u_int,
+        args[ARG_in_end].u_int, MP_BUFFER_WRITE, &in_len);
+    if (out_len != in_len) {
+        mp_raise_ValueError(MP_ERROR_TEXT("buffer slices must be of equal length"));
+    }
+    common_hal_busio_spi_transfer_start(&self->spi, data_out, data_in, out_len, done);
+    return self;
+}
+static CIRCUITPY_DEFINE_ASYNC_FUN_OBJ_KW(async_spi_spi_write_readinto_obj, 2, async_spi_spi_write_readinto);
+
+//|     frequency: int
+//|     """The actual SPI bus frequency. This may not match the frequency requested
+//|     due to internal limitations."""
+//|
+//|
+MP_PROPERTY_GETTER(async_spi_spi_frequency_obj,
+    (mp_obj_t)&busio_spi_get_frequency_obj);
+
+static const mp_rom_map_elem_t async_spi_spi_locals_dict_table[] = {
+    { MP_ROM_QSTR(MP_QSTR_deinit), MP_ROM_PTR(&busio_spi_deinit_obj) },
+    { MP_ROM_QSTR(MP_QSTR___del__), MP_ROM_PTR(&busio_spi_deinit_obj) },
+    { MP_ROM_QSTR(MP_QSTR___enter__), MP_ROM_PTR(&default___enter___obj) },
+    { MP_ROM_QSTR(MP_QSTR___exit__), MP_ROM_PTR(&default___exit___obj) },
+
+    { MP_ROM_QSTR(MP_QSTR_configure), MP_ROM_PTR(&busio_spi_configure_obj) },
+    { MP_ROM_QSTR(MP_QSTR_try_lock), MP_ROM_PTR(&busio_spi_try_lock_obj) },
+    { MP_ROM_QSTR(MP_QSTR_unlock), MP_ROM_PTR(&busio_spi_unlock_obj) },
+
+    { MP_ROM_QSTR(MP_QSTR_write), MP_ROM_PTR(&async_spi_spi_write_obj) },
+    { MP_ROM_QSTR(MP_QSTR_readinto), MP_ROM_PTR(&async_spi_spi_readinto_obj) },
+    { MP_ROM_QSTR(MP_QSTR_write_readinto), MP_ROM_PTR(&async_spi_spi_write_readinto_obj) },
+
+    { MP_ROM_QSTR(MP_QSTR_frequency), MP_ROM_PTR(&async_spi_spi_frequency_obj) },
+};
+static MP_DEFINE_CONST_DICT(async_spi_spi_locals_dict, async_spi_spi_locals_dict_table);
+
+MP_DEFINE_CONST_OBJ_TYPE(
+    async_spi_spi_type,
+    MP_QSTR_SPI,
+    MP_TYPE_FLAG_HAS_SPECIAL_ACCESSORS,
+    make_new, busio_spi_make_new,
+    locals_dict, &async_spi_spi_locals_dict
+    );

shared-bindings/async_spi/SPI.h

@@ -0,0 +1,26 @@
+// This file is part of the CircuitPython project: https://circuitpython.org
+//
+// SPDX-FileCopyrightText: Copyright (c) 2026 Vladimir Smitka
+//
+// SPDX-License-Identifier: MIT
+
+#pragma once
+
+#include "py/obj.h"
+#include "supervisor/shared/async_flag.h"
+#include "shared-module/async_spi/SPI.h"
+
+extern const mp_obj_type_t async_spi_spi_type;
+
+// The transfers are busio's async ones, with the SPI object as the context. transfer_end() and
+// transfer_cancel() act only on the transfer started with done.
+mp_obj_t common_hal_async_spi_spi_transfer_end(void *context, circuitpy_async_flag_t *done);
+void common_hal_async_spi_spi_transfer_cancel(void *context, circuitpy_async_flag_t *done);
+
+// The names CIRCUITPY_DEFINE_ASYNC_FUN_OBJ_KW looks up; all three transfers end the same way.
+#define common_hal_async_spi_spi_write_end common_hal_async_spi_spi_transfer_end
+#define common_hal_async_spi_spi_write_cancel common_hal_async_spi_spi_transfer_cancel
+#define common_hal_async_spi_spi_readinto_end common_hal_async_spi_spi_transfer_end
+#define common_hal_async_spi_spi_readinto_cancel common_hal_async_spi_spi_transfer_cancel
+#define common_hal_async_spi_spi_write_readinto_end common_hal_async_spi_spi_transfer_end
+#define common_hal_async_spi_spi_write_readinto_cancel common_hal_async_spi_spi_transfer_cancel

shared-bindings/async_spi/__init__.c

@@ -0,0 +1,47 @@
+// This file is part of the CircuitPython project: https://circuitpython.org
+//
+// SPDX-FileCopyrightText: Copyright (c) 2026 Vladimir Smitka
+//
+// SPDX-License-Identifier: MIT
+
+#include "py/obj.h"
+#include "py/runtime.h"
+
+#include "shared-bindings/async_spi/SPI.h"
+
+//| """SPI transfers for asyncio
+//|
+//| `async_spi.SPI` is an SPI bus whose transfers are awaited. While a transfer runs, other
+//| asyncio tasks run too.
+//|
+//| .. code-block:: python
+//|
+//|     import asyncio
+//|     import board
+//|     import async_spi
+//|
+//|     async def main():
+//|         spi = async_spi.SPI(board.SCK, MOSI=board.MOSI, MISO=board.MISO)
+//|         while not spi.try_lock():
+//|             pass
+//|         spi.configure(baudrate=8_000_000)
+//|         data = bytearray(512)
+//|         await spi.readinto(data)
+//|         spi.unlock()
+//|
+//|     asyncio.run(main())
+//| """
+
+static const mp_rom_map_elem_t async_spi_module_globals_table[] = {
+    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_async_spi) },
+    { MP_ROM_QSTR(MP_QSTR_SPI), MP_ROM_PTR(&async_spi_spi_type) },
+};
+
+static MP_DEFINE_CONST_DICT(async_spi_module_globals, async_spi_module_globals_table);
+
+const mp_obj_module_t async_spi_module = {
+    .base = { &mp_type_module },
+    .globals = (mp_obj_dict_t *)&async_spi_module_globals,
+};
+
+MP_REGISTER_MODULE(MP_QSTR_async_spi, async_spi_module);

shared-bindings/busio/SPI.c

@@ -86,7 +86,7 @@
 
 
 // TODO(tannewt): Support LSB SPI.
-static mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) {
+mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) {
     #if CIRCUITPY_BUSIO_SPI
     enum { ARG_clock, ARG_MOSI, ARG_MISO, ARG_half_duplex };
     static const mp_arg_t allowed_args[] = {
@@ -106,7 +106,7 @@ static mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, siz
         mp_raise_ValueError(MP_ERROR_TEXT("Must provide MISO or MOSI pin"));
     }
 
-    busio_spi_obj_t *self = mp_obj_malloc_with_finaliser(busio_spi_obj_t, &busio_spi_type);
+    busio_spi_obj_t *self = mp_obj_malloc_with_finaliser(busio_spi_obj_t, type);
     common_hal_busio_spi_construct(self, clock, mosi, miso, args[ARG_half_duplex].u_bool);
     return MP_OBJ_FROM_PTR(self);
     #else

shared-bindings/busio/SPI.h

@@ -15,6 +15,9 @@
 // Type object used in Python. Should be shared between ports.
 extern const mp_obj_type_t busio_spi_type;
 
+// Also used by async_spi.SPI.
+mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args);
+
 // Construct an underlying SPI object.
 extern void common_hal_busio_spi_construct(busio_spi_obj_t *self,
     const mcu_pin_obj_t *clock, const mcu_pin_obj_t *mosi,
@@ -57,6 +60,13 @@ extern void common_hal_busio_spi_transfer_start(busio_spi_obj_t *self, const uin
 // If the transfer started with done is still the bus's, finish it if done is set, and otherwise
 // stop it without setting done. Does nothing for an earlier transfer. Does not allocate.
 extern void common_hal_busio_spi_stop(busio_spi_obj_t *self, circuitpy_async_flag_t *done);
+
+// busio.SPI methods that async_spi.SPI shares: its objects start with a busio_spi_obj_t.
+extern const mp_obj_fun_builtin_fixed_t busio_spi_deinit_obj;
+extern const mp_obj_fun_builtin_var_t busio_spi_configure_obj;
+extern const mp_obj_fun_builtin_fixed_t busio_spi_try_lock_obj;
+extern const mp_obj_fun_builtin_fixed_t busio_spi_unlock_obj;
+extern const mp_obj_fun_builtin_fixed_t busio_spi_get_frequency_obj;
 #endif
 
 // Reads in len bytes while outputting the byte write_value.