async_spi: SPI transfers for asyncio

async_spi.SPI is configured and locked like busio.SPI, and lock(), write(),
readinto() and write_readinto() are awaited: other tasks run during a
transfer. Enabled on raspberrypi. Manual tests are 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,301 @@
+// 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/microcontroller/Pin.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.
+//|     Arguments are checked when the result is awaited."""
+//|
+//|     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."""
+//|         ...
+//|
+static mp_obj_t async_spi_spi_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) {
+    enum { ARG_clock, ARG_MOSI, ARG_MISO };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_clock, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_MOSI, MP_ARG_OBJ, {.u_obj = mp_const_none} },
+        { MP_QSTR_MISO, MP_ARG_OBJ, {.u_obj = mp_const_none} },
+    };
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all_kw_array(n_args, n_kw, all_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+
+    const mcu_pin_obj_t *clock = validate_obj_is_free_pin(args[ARG_clock].u_obj, MP_QSTR_clock);
+    const mcu_pin_obj_t *mosi = validate_obj_is_free_pin_or_none(args[ARG_MOSI].u_obj, MP_QSTR_MOSI);
+    const mcu_pin_obj_t *miso = validate_obj_is_free_pin_or_none(args[ARG_MISO].u_obj, MP_QSTR_MISO);
+    if (!miso && !mosi) {
+        mp_raise_ValueError(MP_ERROR_TEXT("Must provide MISO or MOSI pin"));
+    }
+
+    async_spi_spi_obj_t *self = mp_obj_malloc_with_finaliser(async_spi_spi_obj_t, &async_spi_spi_type);
+    common_hal_busio_spi_construct(&self->spi, clock, mosi, miso, false);
+    return MP_OBJ_FROM_PTR(self);
+}
+
+static async_spi_spi_obj_t *native_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();
+    }
+    return self;
+}
+
+static async_spi_spi_obj_t *locked_spi(mp_obj_t self_in) {
+    async_spi_spi_obj_t *self = native_spi(self_in);
+    if (!common_hal_busio_spi_has_lock(&self->spi)) {
+        mp_raise_RuntimeError(MP_ERROR_TEXT("Function requires lock"));
+    }
+    return self;
+}
+
+//|     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.
+
+//|     async def lock(self) -> None:
+//|         """Waits until the SPI lock is free and takes it. Other tasks run while it waits."""
+//|         ...
+//|
+static void *async_spi_spi_lock(circuitpy_async_flag_t *done, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    mp_arg_check_num(n_args, kw_args->used, 1, 1, false);
+    return native_spi(pos_args[0]);
+}
+static CIRCUITPY_DEFINE_ASYNC_POLL_FUN_OBJ_KW(async_spi_spi_lock_obj, 1, async_spi_spi_lock);
+
+//|     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);
+
+    mp_buffer_info_t bufinfo;
+    mp_get_buffer_raise(args[ARG_buffer].u_obj, &bufinfo, MP_BUFFER_READ);
+    // Bounds are in elements, as in busio.SPI.
+    int stride_in_bytes = mp_binary_get_size('@', bufinfo.typecode, NULL);
+    int32_t start = args[ARG_start].u_int;
+    size_t length = bufinfo.len / stride_in_bytes;
+    normalize_buffer_bounds(&start, args[ARG_end].u_int, &length);
+    start *= stride_in_bytes;
+    length *= stride_in_bytes;
+    return common_hal_async_spi_spi_write_start(self, ((const uint8_t *)bufinfo.buf) + start, length, done);
+}
+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);
+
+    mp_buffer_info_t bufinfo;
+    mp_get_buffer_raise(args[ARG_buffer].u_obj, &bufinfo, MP_BUFFER_WRITE);
+    int stride_in_bytes = mp_binary_get_size('@', bufinfo.typecode, NULL);
+    int32_t start = args[ARG_start].u_int;
+    size_t length = bufinfo.len / stride_in_bytes;
+    normalize_buffer_bounds(&start, args[ARG_end].u_int, &length);
+    start *= stride_in_bytes;
+    length *= stride_in_bytes;
+    return common_hal_async_spi_spi_readinto_start(self, ((uint8_t *)bufinfo.buf) + start, length,
+        (uint8_t)args[ARG_write_value].u_int, done);
+}
+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, and must not overlap. 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);
+
+    mp_buffer_info_t buf_out_info;
+    mp_get_buffer_raise(args[ARG_out_buffer].u_obj, &buf_out_info, MP_BUFFER_READ);
+    int out_stride_in_bytes = mp_binary_get_size('@', buf_out_info.typecode, NULL);
+    int32_t out_start = args[ARG_out_start].u_int;
+    size_t out_length = buf_out_info.len / out_stride_in_bytes;
+    normalize_buffer_bounds(&out_start, args[ARG_out_end].u_int, &out_length);
+    out_start *= out_stride_in_bytes;
+    out_length *= out_stride_in_bytes;
+
+    mp_buffer_info_t buf_in_info;
+    mp_get_buffer_raise(args[ARG_in_buffer].u_obj, &buf_in_info, MP_BUFFER_WRITE);
+    int in_stride_in_bytes = mp_binary_get_size('@', buf_in_info.typecode, NULL);
+    int32_t in_start = args[ARG_in_start].u_int;
+    size_t in_length = buf_in_info.len / in_stride_in_bytes;
+    normalize_buffer_bounds(&in_start, args[ARG_in_end].u_int, &in_length);
+    in_start *= in_stride_in_bytes;
+    in_length *= in_stride_in_bytes;
+
+    if (out_length != in_length) {
+        mp_raise_ValueError(MP_ERROR_TEXT("buffer slices must be of equal length"));
+    }
+    return common_hal_async_spi_spi_write_readinto_start(self,
+        ((const uint8_t *)buf_out_info.buf) + out_start, ((uint8_t *)buf_in_info.buf) + in_start,
+        out_length, done);
+}
+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_lock), MP_ROM_PTR(&async_spi_spi_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, async_spi_spi_make_new,
+    locals_dict, &async_spi_spi_locals_dict
+    );

shared-bindings/async_spi/SPI.h

@@ -0,0 +1,36 @@
+// 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;
+
+// Each start returns the context for transfer_end() and transfer_cancel(); both act only on the
+// transfer started with done.
+void *common_hal_async_spi_spi_write_start(async_spi_spi_obj_t *self, const uint8_t *data,
+    size_t len, circuitpy_async_flag_t *done);
+void *common_hal_async_spi_spi_readinto_start(async_spi_spi_obj_t *self, uint8_t *data,
+    size_t len, uint8_t write_value, circuitpy_async_flag_t *done);
+void *common_hal_async_spi_spi_write_readinto_start(async_spi_spi_obj_t *self,
+    const uint8_t *data_out, uint8_t *data_in, size_t len, circuitpy_async_flag_t *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);
+// lock(): the context is the SPI object; poll tries to take the lock.
+mp_obj_t common_hal_async_spi_spi_lock_end(void *context, circuitpy_async_flag_t *done);
+void common_hal_async_spi_spi_lock_cancel(void *context, circuitpy_async_flag_t *done);
+bool common_hal_async_spi_spi_lock_poll(void *context);
+
+// 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