ObjectFLEDDmaManager.h

Go to the documentation of this file.

#pragma once
 
#include "platforms/arm/teensy/is_teensy.h"
 
#if defined(FL_IS_TEENSY_4X)  // Teensy 4.0/4.1 only
 
#include <Arduino.h>
#include "DMAChannel.h"
#include "platforms/arm/teensy/teensy4_common/dmamem.h"
#include "ObjectFLEDBitdataSize.h"
 
namespace fl {
 
// Forward declarations
// BYTES_PER_DMA controls the dma2 ESG-chained refill chunk size. The ISR
// runs on each major-loop completion and has only one WS2812 bit period
// (~1.25 us) of slack before the next TMR4 trigger reads from the refilled
// half. The ISR's memset + fillbits + dcache_flush takes ~10 us at 600 MHz
// CPU; at BYTES_PER_DMA=60 (480 bits = 600 us per chunk) the race produced
// the residual 0->1 phantom bit flips clustered at 20-LED boundaries
// observed in #3406. At BYTES_PER_DMA=120 the major loop runs 1200 us, so
// the ISR has plenty of margin to refill before the next chunk starts.
// Memory cost: bitdata is at most BYTES_PER_DMA*256 bytes (38,400 B at
// 150), heap-allocated in OCRAM2 and sized to the frame (#4711).
#ifndef BYTES_PER_DMA
// EXPERIMENT: 150 makes our 100-LED test fit in a single major loop
// (numbytes=300 <= BYTES_PER_DMA*2=300) so the ESG/ISR refill path is
// completely bypassed. If the residual #3406 byte corruption disappears
// with this setting, the bug IS in the refill chain.
#define BYTES_PER_DMA 150
#endif
 
// #3416 OF-HIGH-3: at BYTES_PER_DMA < 90 the ISR refill margin
// (~10 us memset+fillbits+dcache_flush) approaches the major-loop
// duration (BYTES_PER_DMA * 10 us / 8 bits-per-byte = X us), reintroducing
// the race that Round 2 of #3406 fixed. Compile-time guard so a
// user override below the safe threshold fails loudly.
static_assert(BYTES_PER_DMA >= 90,
              "BYTES_PER_DMA must be >= 90 to keep the ISR refill margin "
              "ahead of the DMA major-loop tick. See #3406 round-2 race.");
 
// The ISR refills one BYTES_PER_DMA*32-word half of bitdata, which needs
// the >2*BYTES_PER_DMA path to own the full double buffer.
static_assert(objectfled::bitdataWordsFor(2 * BYTES_PER_DMA + 1, BYTES_PER_DMA) ==
                  2 * BYTES_PER_DMA * 32,
              "ObjectFLED ISR half-buffer refill needs a full double buffer");

class ObjectFLEDDmaManager {
  public:
    static ObjectFLEDDmaManager& getInstance() {
        static ObjectFLEDDmaManager instance;
        return instance;
    }
 
    void acquire(void* owner);
    void release(void* owner);
    void waitForCompletion();
    bool isBusy();
    void* getCurrentOwner() const { return mCurrentOwner; }
 
    // Shared DMA resources
    DMAChannel dma1;
    DMAChannel dma2;
    DMAChannel dma3;
    DMASetting dma2next;

    bool ensureBitdata(uint32_t numbytes);
 
    // DMA bit buffer, heap-allocated on first show() and sized to the
    // largest frame seen instead of a fixed 38,400 B DMAMEM array (#4711).
    // Teensy 4 malloc serves OCRAM2 (_heap_start = end of .bss.dma up to
    // the end of RAM in imxrt1062*.ld), the same DMA-capable region as
    // DMAMEM. The buffer is 32-byte aligned for arm_dcache_flush_delete.
    //
    // Raw owning pointer by design (cpp-standards "Long-Lived Pointers"):
    // its only owner is this process-lifetime singleton, it is replaced
    // only in ensureBitdata() while no DMA/ISR is running, and neither the
    // ISR nor the DMA engine can hold a shared_ptr reference.
    uint32_t* bitdata = nullptr;
    uint32_t bitdataWords = 0;
    // DMAMEM buffers must be static to work with section attributes
    static FL_DMAMEM uint32_t bitmask[4] __attribute__((aligned(32)));
 
    // Shared state for ISR. These are written once in showInternal()
    // before DMA arms and then read by the ISR refill path. The ARM Cortex-M7
    // strongly-ordered memory model + the explicit dma.enable() that follows
    // every showInternal write ensures the ISR sees coherent values without
    // requiring volatile qualifiers (volatile would break memcpy of the
    // array source/destinations). Kept non-volatile; #3406 audit Agent 5
    // was conservative.
    volatile uint32_t framebuffer_index = 0;
    uint8_t* frameBuffer = nullptr;
    uint32_t numbytes = 0;
    uint8_t numpins = 0;
    uint8_t pin_bitnum[NUM_DIGITAL_PINS];
    uint8_t pin_offset[NUM_DIGITAL_PINS];
 
  private:
    ObjectFLEDDmaManager() = default;
    ~ObjectFLEDDmaManager() = default;
    ObjectFLEDDmaManager(const ObjectFLEDDmaManager&) = delete;
    ObjectFLEDDmaManager& operator=(const ObjectFLEDDmaManager&) = delete;
 
    void* mCurrentOwner = nullptr;
    void* mBitdataAlloc = nullptr;  // unaligned malloc() block behind bitdata
};
 
} // namespace fl
 
#endif // FL_IS_TEENSY_4X