ESP-IDF 6.1: new spi_bus_config_t::dma_burst_size left at 0xFFFFFFFF by memset(~0u), so SPI bus init panics in M5.begin()

[endaye]

Summary

On ESP-IDF v6.1, M5.begin() (or any M5GFX::init()) panics during SPI bus
initialisation and the board boot-loops. The cause is that IDF 6.1 added a new field to
spi_bus_config_t, and lgfx::v1::spi::init() fills that struct with memset(&buscfg, ~0u, ...),
so the new field is left as 0xFFFFFFFF.

IDF 6.0.x and 5.x do not have the field, which is why the existing build matrix does not show this.

Environment

ESP-IDF	v6.1 (commit fff9895c82d744c7237be8847347bdd1b07c6643)
M5GFX	0.2.28 (from the component registry)
M5Unified	0.2.21 (from the component registry)
Board	M5Stack Cardputer Adv (ESP32-S3FN8, no PSRAM)
Toolchain	xtensa-esp-elf-gcc 15.2.0 (crosstool-NG esp-15.2.0_20251204)
Project type	plain ESP-IDF component, no Arduino
Host	macOS arm64

Symptom

The project builds cleanly (0 errors, 0 warnings). At runtime it boot-loops — 282 resets in 15
seconds — with:

E (160) gdma: gdma_config_transfer(425): invalid max_data_burst_size: 4294967295
E (160) spi_common: alloc_dma_chan(319): config gdma tx transfer failed
Guru Meditation Error: Core  1 panic'ed (LoadProhibited). Exception was unhandled.
EXCVADDR: 0x00000004

Decoded backtrace:

m5::M5Unified::begin()                     M5Unified.hpp:363
lgfx::v1::LGFX_Device::init()              LGFXBase.hpp:1423
m5gfx::M5GFX::init_impl(bool, bool)        M5GFX.cpp:1111
m5gfx::M5GFX::autodetect(bool, board_t)    M5GFX.cpp:1826
lgfx::v1::Bus_SPI::init()                  Bus_SPI.cpp:418
lgfx::v1::spi::init(int, int, int, int, int)  lgfx/v1/platforms/esp32/common.cpp:859
spi_bus_initialize()                       esp-idf/components/esp_driver_spi/src/gpspi/spi_common.c:1016
spicommon_dma_chan_free()                  esp-idf/components/esp_driver_spi/src/gpspi/spi_common.c:489   <-- panic

Root cause

src/lgfx/v1/platforms/esp32/common.cpp:841:

spi_bus_config_t buscfg;
memset(&buscfg, ~0u, sizeof(spi_bus_config_t));   // sets every *_io_num to -1
buscfg.mosi_io_num = spi_mosi;
...
buscfg.intr_flags = 0;
#if (ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 4, 0))
buscfg.data_io_default_level = 0;
#endif

IDF 6.1 added:

uint32_t dma_burst_size; ///< DMA data burst size in bytes. Only used when DMA is enabled.
                         ///  Set to 0 to use driver default.

(components/esp_driver_spi/include/driver/spi_common.h)

After the memset it holds 0xFFFFFFFF, which is neither 0 nor a chip-supported burst size, so
resolve_dma_burst_size() rejects it, alloc_dma_chan() fails, and the unwind path panics.

Field presence, checked against the release tags:

ESP-IDF	dma_burst_size in spi_bus_config_t
v6.1	present
v6.0.3	absent
v6.0	absent
v5.5.5	absent

.github/workflows/IDFBuild.yml covers 6.0.2 (where the field does not exist) and is build-only, so
neither half of the matrix can surface this: adding a struct field needs no source change to compile.

Confirmation

Same binary, one line added after buscfg.intr_flags = 0;:

#if defined (ESP_IDF_VERSION_VAL)
  #if (ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 1, 0))
        buscfg.dma_burst_size = 0;
  #endif
#endif

	boots in 15 s	panics
unpatched	282	282
one line added	1	0

With the line added, everything works: getBoard() returns board_M5CardputerADV, the 240x135
display paints, and both speaker and mic report enabled.

Suggested fix

The minimal change is the version-guarded assignment above, next to the existing
data_io_default_level / isr_cpu_id guards.

More robustly, memset(&buscfg, ~0u, ...) is fragile against upstream struct growth: any new
non-pin field IDF adds silently arrives as 0xFFFFFFFF. Zero-initialising and then setting the
*_io_num fields to -1 explicitly would make future IDF releases default-correct instead of
default-wrong.

Related, on the ESP-IDF side

spi_bus_initialize() panics in its own error path rather than returning the error that
alloc_dma_chan() already produced — spicommon_dma_chan_free() dereferences a DMA context that was
never fully allocated (EXCVADDR: 0x00000004). An invalid dma_burst_size should surface as a
failed return, not a LoadProhibited. That is arguably a separate ESP-IDF issue; happy to file it
there as well if useful.

[ainyan03]

Thank you for the precise report — reproduced on StickS3 / CoreS3 (ESP32-S3), ToughC5 (ESP32-C5) and Tab5 (ESP32-P4) with ESP-IDF v6.1, and the one-line fix you suggested is exactly what was needed. #280 adds it (guarded for v6.1 and later) and is verified A/B on those four boards.

On the zero-initialisation idea: I agree it would be more future-proof, but the memset(~0u) is what keeps every *_io_num (including data4..7_io_num on octal-capable targets) at -1 across all IDF versions the library supports, so switching to zero-init needs a per-version audit of the pin fields. Left for a separate change.

Filing the spicommon_dma_chan_free() panic on the ESP-IDF side would be welcome if you have the time; an invalid dma_burst_size should surface as an error return rather than a LoadProhibited.

[ainyan03]

Follow-up: both fixes are now merged into develop.

• Bus_SPI: initialize spi_bus_config_t::dma_burst_size for ESP-IDF 6.1 #280 — the minimal, version-guarded dma_burst_size = 0 (what I described above).
• Bus_SPI: zero-initialize spi_bus_config_t instead of memset(~0u) #281 — your second suggestion, which I initially deferred: spi::init() no longer uses memset(~0u). The struct is now zero-initialized, following ESP-IDF's own aggregate-initializer convention, and only the unused pin fields are set to -1 explicitly (quadwp/quadhd always, data4..7 under a v4.4+ guard where they exist, since 0 would denote GPIO0). With that, every non-pin field present in IDF 3.2 through 6.1 gets a valid value, and the v6.1-specific assignment from Bus_SPI: initialize spi_bus_config_t::dma_burst_size for ESP-IDF 6.1 #280 was removed again. initQuad() was already written that way, so both paths are consistent now.

Verified A/B with ESP-IDF v6.1 on ESP32-S3 (two boards), ESP32-C5 and ESP32-P4, plus an ESP32 (no GDMA) smoke test on v6.0; builds checked on Arduino-ESP32 2.0.3 / 2.0.17 (IDF 4.4) and 3.x (IDF 5.5).

Thanks again for the precise analysis and for the zero-init suggestion — it was the right call.

[ainyan03]

Thank you for your patience — an update containing both fixes (#280 / #281) has just been released as M5GFX 0.2.29. Please update to 0.2.29 (or later) and M5.begin() should initialize the SPI bus normally on ESP-IDF 6.1 without the dma_burst_size workaround.

I believe this issue can be closed once you have confirmed it on your side.