Esp32 Heap Discipline

ESP32 Heap Discipline

Memory rules for esp32/ firmware. Adapted from crosspoint-reader's heap-discipline skill to AgentDeck's multi-board reality. This is the procedure you run while writing firmware and the gate before handing it back.

The board split — know which world you're in

AgentDeck firmware targets two memory regimes. Check the board macros first.

• PSRAM boards — BOARD_BOX_86, BOARD_IPS35, BOARD_AMOLED, BOARD_IPS10 (ESP32-S3 / -P4, 8–32MB PSRAM). Large canvases/caches go in PSRAM (ps_malloc / MALLOC_CAP_SPIRAM). But per-pixel / LVGL draw buffers and PPA rotation buffers must stay in internal SRAM (MALLOC_CAP_INTERNAL): PSRAM writes are ~30× slower, so a PSRAM draw buffer makes every widget render crawl (see the IPS10 rationale in esp32/src/ui/display.cpp). Plenty of total RAM here; the constraint is write latency and internal-SRAM headroom, not bytes.
• No-PSRAM boards — BOARD_TTGO (classic ESP32, ~160KB heap), BOARD_ESP32_C6_147 (single-core RISC-V), BOARD_LED8X32 (TC001). This is crosspoint's world: every allocation matters and fragmentation, not total usage, is what kills the device. Free heap can read fine while the largest free block is too small for the next alloc. Optimize for not leaving holes.

The canvas/buffer code already encodes this split (renderer.cpp::init uses static pre-allocated buffers on TTGO/C6 and ps_malloc+SRAM fallback elsewhere). Match the existing pattern; don't invent a third path.

Allocation decision procedure

Ask in order; stop at the first yes.

1. Stack? Local, bounded, under ~256 bytes: plain array/struct. The task stacks are sized per board in config.h (STACK_UI) — keep frames lean.
2. Compile-time constant? static constexpr lives in flash, costs zero DRAM. Lookup tables and string literals belong here.
3. Allocated once and reused for the screen/activity lifetime? Allocate at init, hold in a static/member, reuse every frame. Never per-frame, never per-iteration, never in the render/flush path.
4. Dynamic and fallible? makeUniqueNoThrow<T>(...) / makeUniqueNoThrow<T[]>(n) from esp32/src/util/memory.h. Null-check, log, return. It frees on every exit path. Use makeScopedCleanup([&]{ … }) for non-owning teardown (the header is kept C++11-safe — led8x32 builds at gnu++11 — so construct the guard via the factory, not C++17 CTAD).
5. A C/SDK API takes ownership / the object lives for the device lifetime? Only then raw new / heap_caps_alloc / ps_malloc, with a null-check + Serial.printf error and a comment naming who owns it. The display driver objects in display.cpp are this case (one-time, device-lifetime).

Bare new/new[] whose result you don't null-check is never acceptable: with exceptions disabled it abort()s on OOM; even with them on, an unchecked deref crashes. (We had a one-time new (uint8_t[]){…} leak in jd9365_lcd.cpp — fixed to a stack local.)