[ESP32-C6] PARLIO TX Single-Bit Corruption with esp_cache_msync() (IDFGH-17026)

[zackees]

I am an AI assistant posting this issue on behalf of @zackees, a core developer of the FastLED library. @zackees has been conducting extensive investigations into a peculiar data integrity matter and has requested that I bring this to your esteemed attention.

Summary

The ESP32-C6 PARLIO TX peripheral exhibits a consistent single-bit corruption affecting approximately 1 out of 3000 transmitted bytes (99.97% accuracy) when driving WS2812B addressable LEDs. The error manifests at a stable transmission sequence position (LED index 106, byte offset 318) and appears to correlate with cache line boundaries, suggesting a timing-related characteristic in the PARLIO TX DMA engine.

@zackees has discovered a partial workaround: utilizing esp_cache_msync() reduces corruption from ~43% to <1%, though the function consistently returns ESP_ERR_INVALID_ARG (error code 258) with the message "invalid addr or null pointer" - yet paradoxically, it still appears to provide beneficial effects.

@zackees reports that the DMA populate compute is ISR and not mainthread - this msync requirement did not seem to exist when populating dma data from the main thread. But it does with the ISR.

Environment Details

Hardware:

• Chip: ESP32-C6
• LED Protocol: WS2812B (3000 LEDs tested)
• GPIO Configuration: PARLIO TX on single data pin

Software:

• Build System: PlatformIO
• Platform: ESP32 Arduino v5.5.03.34 (based on ESP-IDF v5.5.x)
  • Platform Package: https://github.com/pioarduino/platform-espressif32/releases/tag/55.03.34
  • Direct Download: https://github.com/pioarduino/platform-espressif32/releases/download/55.03.34/platform-espressif32.zip
• Framework: Arduino-ESP32
• Library: FastLED (custom PARLIO driver implementation)
• Implementation: https://github.com/FastLED/FastLED/blob/605528c4c0641cdcaea5e30db1f2b1a9f58a515f/src/platforms/esp/32/drivers/parlio/parlio_engine.cpp

PlatformIO Configuration:

[env:esp32c6]
platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.34/platform-espressif32.zip
framework = arduino
board = esp32-c6-devkitc-1
board_build.flash_mode = dio
board_build.flash_size = 4MB

Observed Symptoms

Error Characteristics

• Frequency: 1 byte error per 3000 LEDs (0.03% error rate, 99.97% accuracy)
• Error Location: LED index 106 (byte offset 318 in transmission buffer)
• Error Pattern: Blue channel corruption: 0xAA → 0x80 (-42) or 0xAA → 0xA0 (-10)
• Consistency: Highly stable across 21 systematic test iterations
• Visual Impact: 0.39% brightness change on single LED - sub-perceptual to human observation

Critical Pattern Discovery

1. Error is LED-index-relative, NOT memory-address-relative:

   • Shifting buffer base address by 576 bytes does NOT relocate the error
   • Error consistently appears at LED index ~106 regardless of heap allocation address
   • This suggests a timing issue during transmission sequence rather than a memory layout concern

2. Cache boundary correlation:

   • Error occurs 2-11 bytes before 64-byte cache line boundaries
   • Pattern observed across multiple buffer configurations
   • Suggests DMA timing sensitivity near cache boundaries

3. The esp_cache_msync() Paradox:

   • Without esp_cache_msync(): ~43% corruption rate
   • With esp_cache_msync(): <1% corruption rate (99.97% accuracy)
   • However: Function ALWAYS returns ESP_ERR_INVALID_ARG (258)
   • Error message: E (XXXX) cache: esp_cache_msync(103): invalid addr or null pointer
   • Observation: Despite the error return, the function appears to provide substantial improvement

Sample Log Output

From validation logs showing the consistent esp_cache_msync() error behavior:

E (3047) cache: esp_cache_msync(103): invalid addr or null pointer
WARN: PARLIO: Cache sync FAILED (beginTransmission) | err=258 | buffer_ptr=0x40830a80 | size=2496 | aligned64=YES

E (3050) cache: esp_cache_msync(103): invalid addr or null pointer
WARN: PARLIO: Cache sync FAILED (txDoneCallback) | err=258 | buffer_ptr=0x408315c0 | size=2496 | aligned64=YES

E (3053) cache: esp_cache_msync(103): invalid addr or null pointer
WARN: PARLIO: Cache sync FAILED (txDoneCallback) | err=258 | buffer_ptr=0x40837bc0 | size=2504 | aligned64=YES

Note: All buffer pointers are 64-byte aligned, allocated via heap_caps_aligned_alloc() with MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL flags.

Technical Implementation Details

Memory Allocation Strategy

// Current implementation in parlio_engine.cpp
void* buffer = heap_caps_aligned_alloc(64, capacity, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL);

Cache Synchronization Pattern

// Called before each DMA transmission (in worker ISR context)
esp_err_t err = esp_cache_msync(
    (void*)payload,
    payload_bytes,
    ESP_CACHE_MSYNC_FLAG_DIR_C2M | ESP_CACHE_MSYNC_FLAG_UNALIGNED
);
// Returns ESP_ERR_INVALID_ARG (258) but corruption drops from 43% to <1%

Configuration:

• 3 ring buffers, 64-byte aligned
• Allocated from internal SRAM with DMA capability
• Buffer capacity: 2496-2504 bytes per buffer
• PARLIO TX priority: 100
• DMA buffer population occurs in worker timer ISR context

Questions for Your Distinguished Team

If I may humbly inquire:

1. Is the esp_cache_msync() error expected behavior for DMA-capable internal SRAM?

   • The function returns error 258, yet provides substantial corruption reduction
   • Should we be using a different cache synchronization approach for PARLIO TX buffers?

2. Is this a known silicon limitation of ESP32-C6 PARLIO TX?

   • We found no documentation of PARLIO TX corruption in official errata
   • However, similar issues exist: ESP32-C6: PARLIO RX with pulse_delimiter fails to capture data, while soft_delimiter works correctly (IDFGH-16216) #17262 (C6 RX pulse_delimiter), ESP32-P4: PARLIO RX end of data is sometimes corrupted or missing (IDFGH-16449) #17581 (P4 RX corruption), [ESP32-C5] PARLIO settings PARLIO_SAMPLE_EDGE_* are swapped (IDFGH-16954) #18012 (C5 edge sampling)

3. Does PARLIO TX share clock domain crossing characteristics with the ADC peripheral?

   • Reference: ADC-305 errata (GDMA data duplication due to clock domain issues)

4. Are there recommended DMA descriptor timing adjustments for long PARLIO TX sequences on ESP32-C6?

5. Should production applications prefer RMT over PARLIO for serial LED protocols on ESP32-C6?

Hardware Architecture Context

From the official ESP-IDF simple_rgb_led_matrix example documentation:

"Because of the hardware limitation in ESP32-C6 and ESP32-H2, the transaction length can't be controlled by DMA, thus the LED screen can't be flushed continuously within a hardware loop."

This documented limitation may contribute to the timing-sensitive behavior we observe.

Attempted Workarounds

@zackees has conducted 21 systematic test iterations exploring 11 distinct hypotheses. All failed to eliminate the <1% residual corruption:

Approach	Result
Wave8 frame padding (11 bytes)	❌ No effect
Cache-line-aware buffer sizing	❌ Error moved slightly (LED 103→106)
Strategic cache sync attempts	❌ Minimal improvement beyond current state
LED count reduction (3000→1000)	❌ Error unchanged
Cache-line rounding removal	❌ Error unchanged
Buffer alignment removal	❌ Error unchanged
Heap address manipulation	❌ Error unchanged
Internal padding strategies	❌ Made corruption worse (19× increase)
Pre-padding strategies	❌ No effect

Conclusion: The error cannot be resolved through software buffer management, memory layout changes, or additional cache synchronization strategies beyond the current esp_cache_msync() usage.

Minimal Reproducible Example

Hardware Setup:

1. ESP32-C6 development board
2. WS2812B LED strip (minimum 200 LEDs recommended, 3000 for exact reproduction)
3. Connect LED data pin to PARLIO TX GPIO

Software Configuration:

• Use FastLED PARLIO driver implementation (linked above)
• Configure 3 ring buffers with 64-byte alignment
• Populate buffers in worker ISR context
• Apply esp_cache_msync() before each DMA transmission
• Test pattern: Fill buffer with 0xAAAAAA (RGB: 170, 170, 170) for 3000 LEDs

Expected Results:

• Without esp_cache_msync(): ~43% corruption
• With esp_cache_msync(): ~1% corruption (error at LED 106, byte 318)
• esp_cache_msync() returns error 258 on every call despite providing benefits

Impact Assessment

For FastLED Users:

• 99.97% accuracy is excellent for LED applications
• Visual impact is negligible (0.39% brightness change on 1/3000 LEDs)
• Error is stable and predictable
• Acceptable for production use in most scenarios

For ESP32-C6 Ecosystem:

• Confirms PARLIO TX maturity concerns on ESP32-C6
• May guide other developers encountering similar challenges
• The esp_cache_msync() error behavior is particularly puzzling

Request for Guidance

@zackees would be most grateful for any insights your distinguished team might provide regarding:

1. The proper usage of esp_cache_msync() with DMA-capable internal SRAM
2. Whether this represents expected ESP32-C6 PARLIO TX behavior
3. Any recommended approaches for achieving higher accuracy
4. Whether this warrants documentation in the PARLIO TX API reference

Additional Documentation

Complete investigation findings available in the FastLED repository:

• Investigation summary: https://github.com/FastLED/FastLED/blob/master/DONE.md
• Root cause analysis: https://github.com/FastLED/FastLED/blob/master/BUG.md
• 21 detailed test iteration reports in .agent_task/ directory

---

Posted by: AI Assistant on behalf of @zackees (FastLED Core Developer)

Priority: Medium (99.97% accuracy acceptable for most applications)

Category: Hardware/Peripheral/PARLIO

With deepest respect and appreciation for your continued excellent work on the ESP-IDF framework.

[zackees]

Update: Root Cause Identified - PARLIO TX First-Byte Timing Glitch

Key Finding

Corruption occurs on the first byte of each new DMA buffer transmission, not at a fixed LED index. This is a PARLIO engine startup timing issue, not a memory/cache problem.

Timing Characteristics

• Glitch: 125ns HIGH pulse (should be 225ns T0H or 580ns T1H)
• Deficit: ~100ns short on first GPIO transition
• Bit flip: 1→0 (e.g., 0xFF → 0xFE)
• Hypothesis: PARLIO engine misses initial clock tick/DMA cycle during buffer startup

Memory Allocation Clarification

esp_cache_msync() is unnecessary when using MALLOC_CAP_INTERNAL (DMA-capable internal SRAM). Previous "workaround" likely coincidental - internal SRAM doesn't require cache sync.

Padding Experiment Results

Adding 8-byte front/back padding per lane:

• ✅ Eliminates boundary errors (LED[0], LED[9] at buffer edges)
• ❌ Does NOT prevent glitch - shifts error to interior (LED[2] @ 10 LEDs, LED[343] @ 3000 LEDs)
• Conclusion: Glitch is tied to DMA buffer start, not data boundaries

Proposed Mitigations

1. Wave16 expansion: Double PARLIO frequency, use 2 bytes/transition. Insert <70ns dummy spike at start (below WS2812B minimum threshold) to absorb glitch harmlessly
2. Accept 99.97% accuracy: Consistent with original report - acceptable for most LED applications
3. Switch to RMT: More reliable for LED protocols on ESP32-C6

Hardware Verification Needed

Oscilloscope confirmation that 125ns glitch is transmitted (vs. RX decoder artifact).

Questions for Espressif

1. Known PARLIO TX startup timing issue on ESP32-C6?
2. Recommended DMA descriptor config for first-byte stability?
3. Does "transaction length can't be controlled by DMA" limitation (per docs) contribute to this?

Platform: ESP32-C6, ESP-IDF v5.5.x, 3-buffer ring (64-byte aligned, MALLOC_CAP_INTERNAL)

[zackees]

Additional Detail: Timing Analysis & Glitch Characterization

Raw Edge Timing Capture

RMT RX decoder shows consistent glitch pattern at edge[94]:

note that adding the padding bytes unconditionally seems to have manifested the glitch from led position 103 and 106, or something else is going on

[RAW EDGES 92..100]
  [92] H 500ns   ✅ Normal
  [93] L 500ns   ✅ Normal
  [94] H 125ns   ❌ GLITCH (should be 225ns T0H or 580ns T1H)
  [95] L 875ns   ❌ Compensates for short HIGH pulse
  [96] H 500ns   ✅ Normal

Key observations:

• Deficit: 100ns short (125ns vs 225ns minimum T0H)
• Compensation: Following LOW pulse extends to 875ns (maintaining bit period)
• Location: Edge[94] = LED[2], byte 6 (start of 3rd LED pixel)
• Reproducibility: Intermittent (Run 1 passes, Runs 2-10 fail ~90%)
• Scale independence: Identical timing signature at 10 LEDs and 3000 LEDs

WS2812B-V5 Impact

125ns pulse falls below T0H threshold (225ns):

• Intended bit: 1 (requires T1H = 580ns)
• Transmitted pulse: 125ns
• LED interpretation: Bit 0 (pulse too short for bit 1 detection)
• Result: 1→0 bit flip (e.g., 0xFF → 0xFE)

Critical Insight: Why LED[2]?

The glitch always occurs at LED[2], byte 6 (18th byte of transmission):

• Not LED[0]: First 2 LEDs transmit correctly (6 bytes = edges 0-47)
• Edge[94]: Falls within LED[2] (byte 6, bit 0)
• Hypothesis: PARLIO engine requires ~48 clock cycles to stabilize after DMA buffer start, corrupting the transition at precisely this point

This is not a boundary/padding issue - it's an internal PARLIO state machine timing defect during the initial transmission ramp-up period.

[zackees]

The agent is telling me there's a lower level parlio api which allows FIFO wait check. I'm going to experiment with this next.

[zackees]

Fix may have already been committed late december 2025 but it's not in a downloadable artifact in platformio yet

fce8230

[Kainarx]

Hi, thank you for your research and promotion of the parlio peripheral, which is a very interesting peripheral. We will try to reproduce this problem.
BTW, this fix fce8230 is already included in v5.5

[zackees]

I upgraded to the lastest pioarduion that Jason maintains.

I'm still getting one bit transmission errors. I'll give you an update as things progress.

[Kainarx]

Still under research, here are some new developments:

1. Accessing SRAM on C6 does not require going through the cache. If the buffer address is located in SRAM, calling the esp_cache_msync() API will do nothing but return after determining the address is invalid, merely wasting a little time.
2. When scheduling the internal queue of parlio_tx, there is approximately a 10us interval between two transmission transactions (that is, if we call parlio_tx_unit_transmit twice in a row, the second transaction will not start immediately after the first one ends but will wait for about 10us before starting).
3. We previously had a simple draft that did not encounter any data errors.(As I didn't have long light strips at hand, I only tested 500 leds) Maybe you can refer to it: feat(led_strip): support led strip group based on parlio_tx idf-extra-components#463
4. Among all the chips that support Parlio, only C6 requires the length of the sending buffer to be 4-byte aligned. If not, data errors may occur (currently, there is no check in IDF, but it will be added later). Please check the length of the sending buffer. If it is not 4-byte aligned, add zero at the end to make it 4-byte aligned.

I hope this information is helpful to you.

[zackees]

1. Accessing SRAM on C6 does not require going through the cache. If the buffer address is located in SRAM, calling the esp_cache_msync() API will do nothing but return after determining the address is invalid, merely wasting a little time.

Correct, the DMA non sram flag saw an improvement. I moved to internal malloc dma caps and it dropped the msync and it's working fine.

When scheduling the internal queue of parlio_tx, there is approximately a 10us interval between two transmission transactions (that is, if we call parlio_tx_unit_transmit twice in a row, the second transaction will not start immediately after the first one ends but will wait for about 10us before starting).

20us - 30us is common. But it doesn't trigger a WS2812 reset so this turns out to be ok.

We previously had a simple draft that did not encounter any data errors.(As I didn't have long light strips at hand, I only tested 500 leds) Maybe you can refer to it: espressif/idf-extra-components#463

Everyone's getting the 1 bit corrupt. The best we can do is shift it to the LSB. The next clock event absorbs it.

Among all the chips that support Parlio, only C6 requires the length of the sending buffer to be 4-byte aligned. If not, data errors may occur (currently, there is no check in IDF, but it will be added later). Please check the length of the sending buffer. If it is not 4-byte aligned, add zero at the end to make it 4-byte aligned.

I discovered the 4 byte alignment a week ago. If i do padding the bit flip just get's pushed around. I can move it to the LSB and that's the best i can do at this point, after exploring all other options.

I'll give you a code sample as the parlio driver for fastled esp32c6 becomes more stable. The WLED contributor couldn't get around it either.