Repository navigation
feat(hal): opt-in DMA for ESP32 hardware SPI (Phase 1) - #142
Merged
Merged
Conversation
Add an opt-in DMA transport for the ESP32 SPI HAL, guarded by CONFIG_ESP32_SPI_DMA_ENABLE (undefined by default). With the macro off the SPI path is byte-for-byte identical to before: internal 64-byte buffer, max_transfer_sz=32, no DMA channel. When enabled, begin() allocates a DMA-capable, word-aligned flush buffer (heap_caps_malloc(MALLOC_CAP_DMA), size CONFIG_ESP32_SPI_DMA_BUFFER_SIZE, default 512) and initializes the bus with a DMA channel (SPI_DMA_CH_AUTO, falling back to channel 1 on pre-4.3 IDF). Bulk pixel writes are then buffered up to the larger capacity and flushed as large DMA transactions, which is where the throughput win comes from. Allocation failure falls back to the internal buffer with DMA disabled. Transfers remain blocking (spi_device_transmit), so the existing flush-before-DC-toggle ordering in setDataMode()/OnDcChange is preserved and the data/command line can never flip mid-transfer. Drivers are untouched - the change lives entirely in the SPI HAL behind the template interface. Note: the DMA path requires validation on ESP32 hardware; the default (non-DMA) build is unaffected and the full SDL test suite (484 tests) passes.
Add a CI step that rebuilds the ESP32 example with CONFIG_ESP32_SPI_DMA_ENABLE defined, so the opt-in DMA SPI path is compile/link-checked on every push. It runs in the existing job and reuses the already-cached ESP-IDF toolchain (no re-install). The macro is injected without touching tracked source via a new optional EXTRA_DEFS parameter in examples/Makefile.esp32, which emits a global add_compile_definitions(...) into the generated project CMakeLists. With EXTRA_DEFS unset the generated project is byte-identical to before.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft — do not merge until validated on ESP32 hardware.
Roadmap "DMA-accelerated SPI", Phase 1 (Tier A: hardware DMA under the existing blocking API). ESP32 only.
What
Opt-in DMA transport for the ESP32 SPI HAL, guarded by
CONFIG_ESP32_SPI_DMA_ENABLE(undefined by default).max_transfer_sz=32, no DMA channel).begin()allocates a DMA-capable, word-aligned flush buffer (heap_caps_malloc(MALLOC_CAP_DMA), sizeCONFIG_ESP32_SPI_DMA_BUFFER_SIZE, default 512) and inits the bus with a DMA channel (SPI_DMA_CH_AUTO, fallback ch 1 on pre-4.3 IDF). Bulk pixel writes flush as large DMA transactions. Alloc failure → falls back to the internal buffer with DMA off.Drivers are untouched — all logic lives in the SPI HAL behind the template interface.
Why it's safe
m_txbuf≡m_buffer,m_capacity≡64, DMA blocks compiled out).spi_device_transmit), so the existing flush-before-DC-toggle ordering (setDataMode()/OnDcChange, which runs in task context) is preserved — the data/command line can never flip mid-transfer.Verification
CONFIG_ESP32_SPI_DMA_ENABLEdefined (compile/link check), reusing the cached ESP-IDF.Commits
feat(hal): opt-in DMA for ESP32 hardware SPIci(esp32): verify build with SPI DMA enabledFollow-ups (later phases)
NanoCanvasflush) — DC transition becomes an explicit await barrier; adopt per-transaction DC callbacks rather than the GPIO-event hook.