Release 0.9.4 dev.11

Release 0.9.4-dev.11

Release: 0.9.4
Build: 0.9.4-dev.11
Stable behavioral baseline: 0.9.3
Qualified optimization baseline: 0.9.4-dev.10

0.9.4-dev.11 is the third measured PSRAM optimization step for the Waveshare ESP32-S3-RGB-Matrix / WLED 17.0.0-devV5 target. It keeps the hardware-qualified dev.10 persistent whole-file GIF source cache and adds conservative one-item Carousel look-ahead prefetch.

Qualified dev.10 baseline

The tested seven-GIF Carousel reached:

gifStage=state:psram bytes:6386 peak:173821 attempts:7 ok:7 fallback:0
gifSourceCache=state:active entries:7 bytes:249267 hits:119 misses:7 stores:7 evict:0 invalid:0

Across the final 593-second observation window, cache hits increased by 117 while playback staging attempts remained 7. PSRAM free, minFree, largest and minLargest remained unchanged byte-for-byte. The tested Carousel therefore reached a 100% warm-cache source hit rate after the seven compulsory first-load misses.

What dev.11 changes

After the current Carousel item is visibly active, dev.11 waits 250 ms and examines only the immediately following playable item. If that item is a GIF, its source can be copied into the existing bounded PSRAM source cache before the transition.

The look-ahead depth is exactly one item. The implementation does not scan or warm the entire Carousel bank. If the next item is TEXT, no GIF is prefetched during the current dwell; the next decision is made after that TEXT item becomes visible.

IDotMatrixGifSourceStage::prefetch() never releases or replaces the active AnimatedGIF source pointer. It allocates a separate future-source buffer and admits it to the same dev.10 LRU cache. The active cache entry remains protected from eviction.

Unchanged limits and fallback

• 1 MiB total persistent source-cache bytes.
• 512 KiB maximum admitted persistent source.
• 12 metadata entries.
• LRU replacement.
• 2 MiB normal playback-stage maximum.
• 4 MiB free-PSRAM reserve before a new allocation.
• 4096-byte copy chunks with scheduler yield.
• App-upload/transient GIFs remain outside persistent reuse.
• Any prefetch failure is advisory only; normal dev.10 playback staging/cache/filesystem fallback remains authoritative.

Telemetry

Dev.11 adds:

gifPrefetch=attempts:<n> ok:<n> cached:<n> fail:<n> bytes:<n>

• attempts: look-ahead copies that needed filesystem I/O.
• ok: successful new source prefetches admitted to PSRAM cache.
• cached: look-ahead requests already satisfied by a resident source.
• fail: background prefetch failures; these are not playback failures.
• bytes: cumulative bytes copied successfully by look-ahead.

gifStage attempts/ok/fallback continues to describe real playback staging work only.

Qualification target

Use the same seven-GIF Carousel and firmware composition as dev.10. On a cold first traversal, gifPrefetch attempts/ok should rise and later GIFs should increasingly arrive as source-cache hits. The main success criterion is fewer than the dev.10 cold baseline of seven playback gifStage attempts, without visible timing/dwell regression.

After warm-up, gifPrefetch cached and gifSourceCache hits should rise while new prefetch copies flatten. gifPrefetch fail and gifStage fallback should remain zero in the normal test workload.

No BLE protocol, Carousel order/dwell, AnimatedGIF callback/frame timing, renderer/scaling, automation or external-buzzer semantics change in this build.