Repository navigation
Memory Sizing
Everything lives in one arena. Size it once and loading can never fall over a surprise malloc.
┌────────────────────────────────────────────────────┐
│ instance struct (about 1.2 KB) │
│ value stack (VALUE_STACK_SLOTS x 8 bytes) │
│ call frames (CALL_DEPTH x frame size) │
│ module metadata + translated code │
│ tables, globals, data segments │
│ guest linear memory (declared size, or the cap) │
└────────────────────────────────────────────────────┘
Rule of thumb:
arena ≈ guest memory + 8 ×
VALUE_STACK_SLOTS+ about 1.4 KB + the module's translated code
Real modules from examples/wiki/guest, loaded on a 64-bit PC build (eccles_wasm_get_stats().arena_used). 32-bit chips use a little less because pointers are smaller. Default stack slots (256).
| Module |
.wasm bytes |
default memory (64 KiB) |
MEM_LIMIT_BYTES 8 KiB |
MEM_LIMIT_BYTES 2 KiB |
|---|---|---|---|---|
sensor.wasm (ADC average) |
674 | 69,164 | 11,820 | 5,676 |
hello.wasm (add, fib, printf) |
3,800 | 74,702 | 17,358 | 11,214 |
led.wasm (blink, printf) |
3,929 | 74,898 | 17,554 | 11,410 |
Notes:
- The fixed cost of using
ew_printfis about 5.5 KB of translated code. A module without it is far smaller. - Translated code is about 1.4 times the
.wasmsize for the same functions. - Guest memory dominates. That is why
MEM_LIMIT_BYTESis the most important setting on small chips.
- Start generous:
-DECCLES_WASM_ARENA_SIZE=(96ul*1024ul). - Load your real module and print the stats:
eccles_wasm_stats_t s = eccles_wasm_get_stats();
printf("arena %u, used %u, guest memory %u of %u pages, code %u bytes\n",
(unsigned)s.arena_size, (unsigned)s.arena_used, (unsigned)s.memory_bytes, (unsigned)s.memory_pages, (unsigned)s.code_bytes);- Set
ECCLES_WASM_ARENA_SIZEtoarena_usedplus the memory the module needs to grow, plus 10 percent margin. - If it does not fit your chip, set
ECCLES_WASM_MEM_LIMIT_BYTESto what the module truly touches (see below) and shrink the stack slots.
A stock clang module declares 64 KiB (one page) but usually touches a few hundred bytes plus its stack plus its globals. Run it with a small cap:
make ... -DECCLES_WASM_MEM_LIMIT_BYTES=2048ulIf it traps with out-of-bounds memory access, raise the cap. Also lower the guest's own stack: -Wl,-z,stack-size=1024. Data, bss and stack are all placed inside the capped range, so everything the guest owns must fit inside it.
load fails with out of arena memory and eccles_wasm_last_error_info() gives the bytes needed. Raise the arena by at least that much.
| Chip RAM | Suggestion |
|---|---|
| 20 to 32 KB | 12 to 16 KB arena, MEM_LIMIT_BYTES 2 KB, VALUE_STACK_SLOTS 128, CHUNK_SIZE 64, no ew_printf in the guest |
| 64 to 128 KB | 40 KB arena, MEM_LIMIT_BYTES 8 KB |
| 256 KB (nRF52840, RP2040) | 96 KB arena, defaults |
| 320 KB or more (ESP32) | 96 to 128 KB arena from the heap |
| with PSRAM | put the arena there with eccles_wasm_init_with(psram_ptr, size). The interpreter reads guest memory from it, so measure the speed |
Settings for the 20 to 32 KB row were measured to load and run a small module on the PC build (a 550-byte module with a 2 KB memory cap needs 5.5 KB with 256 stack slots, 4.4 KB with 128).
Each instance (and each thread child) has its own arena. Children of a threaded module share the parent's guest memory, so a child needs only its stacks and tables: 8 KB worked on an ESP32 (Threads).
-
Flash: about 50 KB for the runtime (
make size), plus the modules if you embed them. - C stack of your calling task: the interpreter and the loader use the stack of the task that calls them. Give that task at least 4 KB, and 8 to 16 KB on ESP32 while you measure.
Eccles WASM 2.0.0 · MIT · Repository · Report a problem · Support ♥
Start here
Platforms
Use it
- Writing Guests
- Guest Import Reference
- Loading Modules
- Custom Filesystems
- Host Functions
- Permissions
- Instances
- Threads and Spawner
- Atomics
- Safety, Fuel and Traps
Reference
Proof
More