async_spi: SPI transfers for asyncio by lynt-smitka · Pull Request #11489 · adafruit/circuitpython

lynt-smitka · 2026-10-02T09:38:07Z

Adds the async_spi module, based on @kamocat's work in #11040. Part of #10856.

async_spi.SPI is configured and locked like busio.SPI, but write(), readinto() and write_readinto() are awaited, so other asyncio tasks run during a transfer. Cancelling a task stops its transfer. Tasks that share the bus can use an asyncio.Lock.

busio on raspberrypi gets async reads, full-duplex transfers and cancel, next to the async write from displayio: send one area buffer while composing the next #11468. A DMA interrupt marks the transfer as done, and asyncio then resumes the waiting task.
supervisor/shared/awaitable.c lets C functions return awaitables, so other async modules (I2C, UART) can use it later.
Only raspberrypi enables the module so far. It adds about 1.9 KB there; other ports are unchanged.

Tested on a Pico W with MOSI jumpered to MISO: data reads back correctly at up to 62.5 MHz, other tasks keep running during transfers, and cancelling transfers works while audio plays.

tannewt

Thanks for picking this up! I'd prefer it to be more like a new module than changing the implementation in busio.SPI().

tannewt · 2026-10-02T17:48:24Z


 #define NO_INSTANCE 0xff

+#if CIRCUITPY_ASYNC_SPI


I'd prefer an new common-hal subfolder for this. If this implementation wants to use the async version under the hood that's ok.

tannewt · 2026-10-02T17:49:44Z

+#include "py/misc.h"
+#include "common-hal/busio/SPI.h"
+
+// busio_spi_obj_t first, so that busio.SPI's methods work on these objects too. busio.SPI's


I don't expect it to work like a busio.SPI. The async version should only be async.

tannewt · 2026-10-02T17:52:07Z

It'd be cool to test this on zephyr's native_sim.

I tried to make it possible in #11504

lynt-smitka · 2026-10-03T17:40:38Z

I would like to clarify why the PR looks the way it does:

The blocking transfers, displayio's async write and async_spi share one DMA path. A separate module would either carry a second copy of the DMA code for the same SPI block, or busio would have to call into the new module.
Reusing busio's constructor and configure()/try_lock()/unlock() keeps the module at about 1.9 KB. With its own bindings it is about 0.5 KB more.
The lock is busio's. An earlier version had an awaitable lock() that polled - in a test with two tasks it let one of them run 790 transfers while the other got 1. Without a native lock, tasks use asyncio.Lock, which costs nothing in flash.

What I'm working on:

Moving the RP2 driver out of busio into a port file (peripherals/spi.c), with busio.SPI and async_spi.SPI as thin layers over it. busio's bindings stay unchanged.
async_spi.SPI as its own type: constructor, configure(), deinit(), frequency and the three awaited transfers, no lock methods. Tasks share the bus with asyncio.Lock.
A Zephyr implementation tested on native_sim. That needed zephyr-cp: fix asyncio and busio.SPI on native_sim, add an SPI loopback for tests #11504 first: asyncio tasks from create_task() did not run there, and busio.SPI crashed.
The current result is about +2 KB on RP2 boards, and other ports get a few bytes smaller. It passes on a Pico W and a Pico 2 W so far. I'll push once zephyr-cp: fix asyncio and busio.SPI on native_sim, add an SPI loopback for tests #11504 is in.

Questions before I push

Is it ok to keep the shared driver in peripherals/, so busio does not depend on the Python module?
Is it ok for async_spi to reuse busio's argument tables? Same arguments, 160 B less flash, but a link between the two modules.
Is it ok that configure() and deinit() wait for a running transfer instead of raising?

tannewt · 2026-10-05T16:39:48Z

busio would have to call into the new module.

This is what I was thinking. Build busio on top of async under the hood.

Reusing busio's constructor and configure()/try_lock()/unlock() keeps the module at about 1.9 KB. With its own bindings it is about 0.5 KB more.

The constructor can be shared by building on the async portion.

I don't think we want busio's locking. Instead, we likely want something async friendly. (Like an async lock)

Questions before I push

* Is it ok to keep the shared driver in peripherals/, so busio does not depend on the Python module?

Yup, that's fine. Code in peripherals shouldn't have any python specific code though.

* Is it ok for async_spi to reuse busio's argument tables? Same arguments, 160 B less flash, but a link between the two modules.

The reverse but yes. Have it in async and reuse it in busio.

* Is it ok that configure() and deinit() wait for a running transfer instead of raising?

Yes, but I image they too should be async then.

buffer_slice() turns a buffer object and element bounds into a byte slice, as busio.SPI's write(), readinto() and write_readinto() did inline. busio.SPI gets a little smaller, and async_spi will use it too.

busio.SPI's port code becomes rp2_spi_t and rp2_spi_*() in peripherals/spi.c, with common-hal/busio/SPI.c as a thin layer over it, so that another module can drive an SPI bus the same way. No change in behaviour.

rp2_spi_read_start() and rp2_spi_transfer_start() start the other two transfers the way rp2_spi_write_start() starts a write. rp2_spi_stop() stops a transfer, or finishes it if it is already done; it does nothing once the bus has started a later transfer. rp2_spi_configure_start() applies new settings once the running transfer has finished, and rp2_spi_deinit() stops a running transfer. With CIRCUITPY_ASYNC_SPI, a DMA_IRQ_0 handler, shared like the audio and rp2pio ones, sets the done flag when the RX channel finishes, so a waiter does not need to call rp2_spi_end() to find out.

CIRCUITPY_DEFINE_ASYNC_FUN_OBJ_KW(obj, n_args_min, fun) defines a method that returns an awaitable. As with a CPython coroutine, its arguments are stored and only parsed when it is awaited. While an operation runs, the task waits on asyncio's I/O queue: the awaitable is a stream that polls readable once the operation's done flag is set, possibly from an interrupt. Based on the awaitable in adafruit#11040.

async_spi.SPI is configured like busio.SPI, and configure(), 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, where it drives the bus through peripherals/spi.c. A manual test is in tests/circuitpython-manual/async_spi. Co-authored-by: Marshal Horn <175229+kamocat@users.noreply.github.com>

busio.SPI takes the same arguments as async_spi.SPI, so where that module exists its tables are used. Saves 160 bytes on RP2040.

Transfers use spi_transceive_cb() where the driver has an async path, and otherwise run on the system work queue. Zephyr cannot stop a transfer, so cancel waits for it. Enabled on boards with an SPI bus; tested on native_sim through the loopback device.

The driver's result reaches the await as an exception. cancel() and deinit() wait for the transfer without running background tasks, since they may run from a finalizer during GC. async_spi needs asyncio, not only async/await, so raspberrypi enables it with MICROPY_PY_ASYNCIO.

…O_SPI Unused, so a build error, on boards without busio.SPI.

tannewt requested changes Oct 2, 2026

View reviewed changes

lynt-smitka mentioned this pull request Oct 3, 2026

zephyr-cp: fix asyncio and busio.SPI on native_sim, add an SPI loopback for tests #11504

Merged

lynt-smitka and others added 7 commits October 8, 2026 20:34

shared/runtime: add buffer_slice() and use it in busio.SPI

c1d61d2

buffer_slice() turns a buffer object and element bounds into a byte slice, as busio.SPI's write(), readinto() and write_readinto() did inline. busio.SPI gets a little smaller, and async_spi will use it too.

raspberrypi: move the SPI driver to peripherals/spi.c

4719ff9

busio.SPI's port code becomes rp2_spi_t and rp2_spi_*() in peripherals/spi.c, with common-hal/busio/SPI.c as a thin layer over it, so that another module can drive an SPI bus the same way. No change in behaviour.

busio: reuse async_spi's argument tables

4f18be7

busio.SPI takes the same arguments as async_spi.SPI, so where that module exists its tables are used. Saves 160 bytes on RP2040.

zephyr-cp: async_spi

8bbdf9b

Transfers use spi_transceive_cb() where the driver has an async path, and otherwise run on the system work queue. Zephyr cannot stop a transfer, so cancel waits for it. Enabled on boards with an SPI bus; tested on native_sim through the loopback device.

lynt-smitka force-pushed the async-spi branch from 5e39446 to 8bbdf9b Compare October 8, 2026 20:38

lynt-smitka added 2 commits October 8, 2026 21:10

busio: keep the SPI constructor's argument table under CIRCUITPY_BUSI…

9aaf7f5

…O_SPI Unused, so a build error, on boards without busio.SPI.

Navigation Menu

Repository navigation

async_spi: SPI transfers for asyncio - #11489

async_spi: SPI transfers for asyncio#11489
lynt-smitka wants to merge 9 commits into
adafruit:mainfrom
MakerClassCZ:async-spi

lynt-smitka commented Oct 2, 2026

Uh oh!

tannewt left a comment

Uh oh!

tannewt Oct 2, 2026

Uh oh!

tannewt Oct 2, 2026

Uh oh!

tannewt Oct 2, 2026

Uh oh!

lynt-smitka Oct 3, 2026

Uh oh!

lynt-smitka commented Oct 3, 2026

Uh oh!

tannewt commented Oct 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

lynt-smitka commented Oct 2, 2026

Uh oh!

tannewt left a comment

Choose a reason for hiding this comment

Uh oh!

tannewt Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

tannewt Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

tannewt Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

lynt-smitka Oct 3, 2026

Choose a reason for hiding this comment

Uh oh!

lynt-smitka commented Oct 3, 2026

Uh oh!

tannewt commented Oct 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants