Zinc Next: the widgets demo on the ESP32 by AOT

Goal (owner, 2026-10-21): run examples/boards/esp32-2432s022 unchanged on the ESP32-2432S022C board with the Next engine, through zinc build --target esp32. The board has an ESP32-WROOM-32 (no PSRAM, 4 MB flash), an ST7789 240x320 panel on an 8-bit i80 bus and a CST820 touch controller on I2C. The demo is about 1,030 lines and uses zinc:ui/solid JSX, zinc:ui/kit, canvas drawing and zinc:device. The first generation (tag prototype-final) ran it this way. This report covers what Next has, what it lacks, the measured gap and a plan of one-session phases. The --engine mquickjs path is separate work and is not covered here. Nothing was built for the ESP32 and the board was not touched.

Numbers marked measured come from the develop build of zinc (main tree, 2026-10-21) run on this tree’s demo. Numbers marked estimate do not.

1. How the AOT works today

• Emitter. src/aot/aot.cpp turns each function of a verified ZBC module into a C++ function over the interpreter’s register window (aot.h:1-5). The C++ shares the Machine, the heap and the runtime calls of src/rt. Typed numeric functions take C parameters (ZN-144). Each object class with fields gets a struct Z_C<n>, a 16-byte header plus one 8-byte Slot per field (aot.cpp:416-422).
• Tables at start-up. The module is embedded with its code stripped, then run-length packed (aot.cpp:409-413, kModule at :453). main calls runProgramPacked (:483), which does the following on every launch (src/rt/program.cpp:62-80):
  1. unpacks the tables into a std::vector;
  2. copies that vector again;
  3. decodes it into zbc::Module;
  4. verifies it;
  5. builds Machine tables, including one dense vtable per concrete class sized to all selectors (src/rt/machine.cpp:259-264).
• Host build (zinc build <file> -o out, src/main.cpp:762-884). It compiles the units with the system c++ -O2 (several units of 48 functions for large programs). It links libzn_rt, mimalloc, zbc, ir, frontend, native and regexp. Programs that draw also get libzn_host_gfx: zrt, raster and gfx of runtime/, the HAL, libuv, llhttp, mbedTLS and codecs (:880-884). Yoga is linked only for the rn layout, HarfBuzz only for "text": "shaped" (:792-801).
• Cross build (zinc build --target <t> <file> -o out, src/main.cpp:2549-2628). It uses the pinned zig, and the targets come from src/tc/tc.cpp:163-189 (Linux, macOS, Windows). A console program gets crossBuild (tc.cpp:633-665), which compiles ten runtime sources per target into ~/.zinc/cache/<t>. A program that draws gets ensureCrossLibs (tc.cpp:668-704), which configures a whole CMake tree with zig wrappers and is Linux only (:672).
• No ESP32 target. findTarget("esp32") fails, so today zinc build --target esp32 ... prints unknown target 'esp32' (measured). zig has no Xtensa backend, so the ESP32 path cannot reuse zig. It needs ESP-IDF’s GCC: ~/.zinc/esp-tools/tools/xtensa-esp-elf/esp-14.2.0_20260121, with IDF v5.5.5 in ~/.zinc/esp-idf, both installed by tools/build-esp32-core.
• What exists for the ESP32. There is the interpreter core firmware (firmware/esp32, docs/reports/zinc-next-esp32.md). firmware/esp32/main/CMakeLists.txt already compiles src/rt/{alloc,machine,rtcalls,program,native,unicode}.cpp, src/zbc/zbc.cpp and libunicode.c as an IDF component. It uses ZN_NO_MIMALLOC and CONFIG_COMPILER_CXX_EXCEPTIONS=n. That is the base of an AOT component: the same list plus the generated units, without src/vm and src/dev.

What an ESP32 AOT build needs

C++ features:

• Exceptions. None. Zinc exceptions are status returns (st == 1, m.thrown), and src/rt already builds with exceptions off.
• RTTI. None: no dynamic_cast or typeid in src/rt, the hosts or runtime/.
• Threads. std::mutex in src/rt/native.cpp:59, which works through IDF pthreads. The std::thread band pool of render_bands.h is not used by the panel drivers.
• mimalloc. Off (alloc.cpp:5).
• mmap. Guarded (machine.cpp:4,237).
• 64-bit assumptions.
  • Slot = uint64_t everywhere (include/zn/value.h:7), and references are stored in Slots.
  • Obj is alignas(Slot), so its header is 16 bytes on 32 bits too (src/rt/rt.h:104-110).
  • The AOT asserts that object layout equals header plus n Slots (aot.cpp:422).
  • f64 is soft-float on the LX6. The esp32 profile makes number f32 (src/frontend/profile.cpp:15), so program numbers do not use f64.
• ZN-145 (parked). It makes references and typed locals 4 bytes on 32-bit targets. It was parked only because its criteria run armhf under qemu-user, which is Linux only. Its field half can be proven on the Mac instead: a host build with the compact layout switched on runs the corpus, and Espressif’s QEMU runs on macOS (phase 4).

Machine defaults that break on the ESP32

• Register stack. kStackSlots is 10,000 frames x 256 registers, about 20 MB (machine.cpp:100). The frames array is 10,000 entries (:285-286). The core firmware sets 3,000 slots and 128 frames; an AOT build must set the same kind of values.
• C stack check. cStackLimit returns null when the OS is neither macOS nor Linux (machine.cpp:85-96), so stackLow never fires on the ESP32. It needs a FreeRTOS bound: the task stack start plus a 2 KB margin, not 256 KB. The demo needs at most 62 registers per function (median 6, measured), so a 24-32 KB main task stack is enough for its recursion.

2. What zinc:ui needs on the device, and how the prototype fitted

ZN-194 (compact scene plus RGB565 native raster) is not needed to run the demo: the prototype ran with the 32-bit raster and in-place RGB565. It would save about 15-20 KB of pools and band, so it stays an optimisation (phase 7).

3. Size and memory: the measured gap

Program tables (measured, zinc --profile esp32 --emit=cpp, ZINC_DEVICE_TARGET=esp32)

The demo’s dense vtables hold 408,457 words, but only 1,512 class-selector pairs are real. On the device, today’s start-up path would need:

• the unpacked bytes twice;
• the decoded Module;
• 620 concrete classes x 413 selectors x 4 B, about 1.0 MB of ClassRT vtables;
• 1,889 string constants as heap StrObj (31 KB of text);
• 955 Func records (about 23 KB).

That is roughly 4-5 MB on a chip with about 280 KB free. A UI program cannot start until these tables are const data in flash.

Objects (measured, zinc mem --profile esp32, interpreter on the Mac)

The object layout is the same as on the ESP32: a 16-byte header and 8-byte Slots.

Array storage comes on top of these figures. The prototype peaked at 123-127 KiB over the whole tour. With 4-byte refs, i32 and f32 fields and 1-byte booleans, a UiNode drops to about 600 B (estimate), which roughly halves the UI heap. The Controls page would still be at about 150-170 KB, so moving more cold fields of UiNode to the existing shared records (scroll, edit and min/max fields) may also be needed.

RAM budget for the demo (target)

The prototype had 93.5 KB of static DRAM and a 161 KiB Zinc heap, with 31 KiB left to IDF. Next must land in the same envelope.

Code and flash

There are no ESP32 numbers yet. The load average was 10 to 12 during this research, so no Xtensa compile was run. The proxy is x86-64 -O2 object text from the main build tree:

Not linked on the ESP32: sys_host 125 KB, Yoga 93 KB, mimalloc 87 KB and vm 91 KB. Generated code averages about 1.6 KB of x86-64 text per function (median of 41 cached 48-function units in ~/.zinc/cache/aot-obj), so the demo’s 955 functions are about 1.5 MB on x86-64.

Image estimate: generated code 0.8-1.2 MB + runtime 0.35-0.45 MB + IDF about 0.2 MB + fonts about 0.7 MB + tables about 0.15 MB, so 2.2-2.7 MB. That is more than the board’s appSize: "2M" (the prototype image was 1.2-1.65 MB, code 416 KB), so the partition should be one 3 MB factory app with no OTA. Measuring command once the target exists: xtensa-esp-elf-size -A build/esp32/idf/build/*.elf.

Main risks

1. Heap. Even with compact fields the Controls page is near 160 KiB. Fixing it needs shared-core work in lib/std/ui.ts and solid effects (backlog/later.md:215).
2. Tables to flash. This changes how every AOT program starts (src/aot, src/rt). Host goldens and tools/diff-matrix must stay identical.
3. Code size and speed. Next’s register-window C++ is several times the prototype’s code. Flash-cache misses (32 KB cache) may cost frame time. Choosing -O2 or -Os must be measured.
4. Two allocators. IDF malloc and zrt’s TLSF would split about 190 KB and fragment it.
5. No display under QEMU. Pixels, MADCTL/BGR, inversion and touch orientation are proven only on the board. The board is shared with the mquickjs session.
6. Build time. 6.7 MB of generated C++ (180,899 lines) compiled by GCC 14 for Xtensa. Use the multi-unit split (emitCppParts) and IDF’s ccache (IDF_CCACHE_ENABLE=1).

4. Phases (one session each)

Every phase builds with the local IDF 5.5.5 through idf.py (IDF_PATH=~/.zinc/esp-idf, IDF_TOOLS_PATH=~/.zinc/esp-tools). Builds run in the background. QEMU is the pinned Espressif build, with the command line of tc.cpp:629 pointed at the app image. The board is used only when the other session has released the port.

zinc device-sim --board esp32-2432s022 is the upload-protocol interpreter core: it reports the board’s module list but draws nothing (src/main.cpp:2376-2403). For pixels, the oracle is zinc run --profile esp32 on the Mac.

Open decisions and recommendations

Edit this page on GitHub ↗