Migrate SPI controller operations to async

[floitsch]

Stacked on #3160. The required ESP-IDF patch head is already on master.

This migrates ESP32 SPI controller transfers and explicit bus reservation away from blocking primitives.

Highlights:

• controller transfers are split into start and finish primitives; start queues with zero timeout and finish polls for the completed descriptor
• an allocation-free post-transaction callback wakes the waiting Toit task through the resource event queue
• native DMA buffers are allocated and populated before dispatch, and every synchronous error or retryable OOM path cleans up fully
• operation cleanup remains protected across yields and cancellation, including deadline handling, so dispatched transactions are always finalized
• explicit bus reservation uses try-acquire plus a Toit yield loop; a failed try rolls back only its own pending lock request
• short transmit-only transfers use persistent inline transaction storage, and zero-length transfers avoid null pointer arithmetic
• two-board tests verify scheduler progress during a deliberately slow transfer and repeatedly exercise reservation contention
• full SPI target and buffer-target suites pass on classic ESP32 and ESP32-S3, covering modes, bit order, speeds, DMA and non-DMA lengths, partial classic DMA words, overflow, re-arm, and maximum-size transfers

The ESP-IDF patch head on master includes the narrow public nonblocking bus-acquire operation and the later I2C/SPI hardening. A recent upstream ESP-IDF checkout still has no public finite-time or nonblocking SPI bus acquisition, so the private-fork addition remains necessary and follows the existing ESP-IDF lock API.

This is a complete-transaction API. Half-buffer streaming and watermark callbacks are deliberately not included.

[floitsch]

@CodeRabbit review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Walkthrough

The SPI transfer implementation now separates transaction start and completion. ESP32 transfers use queued transactions, event-driven completion, managed buffers, and non-blocking bus acquisition. The Toit API serializes transfers and closes devices under a mutex.

Changes

SPI transfer flow

Layer / File(s)	Summary
Toit transfer flow lib/spi.toit, src/compiler/propagation/type_primitive_spi.cc, src/primitive.h	Device_ now coordinates start, completion state, and finish operations under a transfer mutex. The SPI primitive contract exposes transfer_start and transfer_finish.
ESP32 event resource wiring src/resources/spi_esp32.h, src/resources/spi_esp32.cc	SpiDevice now uses an event queue resource. ISR callbacks post completion events, and device creation supplies the queue and callback.
ESP32 transfer and bus primitives src/resources/spi_esp32.cc	The ESP32 backend queues transactions, retrieves results with timeout handling, manages transfer buffers, and uses try-acquire bus semantics.
Validation and configuration tests/hw/esp32/spi-buffer-target-shared.toit, toolchains/esp32/sdkconfig, toolchains/esp32/sdkconfig.defaults	Hardware tests cover asynchronous transfers and repeated bus-acquisition attempts. SPI ISR and related IRAM settings are disabled.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: 🟡 Moderate · up to 5e7af

The asynchronous SPI transfer and bus-reservation changes can leave a reservation unreleased if the device closes while a task is yielding, and certain completion errors may strand an in-flight transaction and its buffers. The associated interrupt configuration and required ESP-IDF change also need explicit validation, so this is not merge-ready until the lifecycle and error paths are addressed.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 26 functions across 4 files. (4 skipped: 4…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: migrating SPI controller operations to asynchronous behavior.
Description check	✅ Passed	The description directly explains the asynchronous SPI transfer migration, nonblocking bus reservation, cleanup behavior, tests, dependencies, and scope.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 26 functions across 4 files. (4 skipped: 4 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch floitsch/spi.30-async-controller

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}