Repository navigation
Concepts
Eight ideas. Read this once and the rest of the wiki is easy.
- The host is your firmware: C code that includes
eccles_wasm.hand linkseccles_wasm.c. - The guest (also called module) is a
.wasmfile the host loads and runs. It is compiled from C, C++ or Rust on your PC.
The guest can only compute, and call functions the host allows. It cannot touch memory outside its own sandbox.
your PC your microcontroller
┌──────────┐ app.wasm ┌──────────────────────────────┐
│ clang │ ───────────► │ host firmware │
│ (guest.c)│ (file, OTA, │ eccles_wasm.c ◄── you call │
└──────────┘ flash) │ ┌────────────────────────┐ │
│ │ guest sandbox (arena) │ │
│ └─────────┬──────────────┘ │
│ ▼ imports │
│ GPIO · ADC · I2C · SPI ... │
└──────────────────────────────┘
All memory the runtime uses comes from one block, the arena (ECCLES_WASM_ARENA_SIZE): the module's metadata, the translated code, the stacks and the guest's linear memory. There is no malloc inside the interpreter. When the arena is too small, loading fails with no memory and last_error_info() tells you how many bytes were needed. See Memory Sizing.
-
eccles_wasm_load*reads the module in small chunks (256 bytes by default), validates it, and translates it. A module is never held in RAM whole. -
eccles_wasm_call("name", ...)runs an exported function and returns the results.
Every hardware call returns one of four numbers. The same numbers are visible inside the guest.
| Value | Name | Meaning |
|---|---|---|
| 0 | SUCCESSFUL | it worked |
| 1 | FAILED | tried and failed (bad pin, bus error, a trap) |
| 2 | UNSUPPORTED | this chip or backend cannot do it |
| 3 | DENIED | the host did not grant this module that hardware |
For the reason behind a FAILED result use eccles_wasm_last_error(). See Error Reference.
A new module can compute and nothing else. You grant hardware with eccles_wasm_set_hal_privilege(bits), and you can limit it to specific pins, buses and I2C addresses. A refused call returns 3 to the guest and does not touch the hardware. See Permissions.
- Sandbox: every memory access is bounds-checked. A wild pointer traps, it does not corrupt your firmware.
- Fuel: an instruction budget stops endless loops.
- Traps: any fault ends the call with an error code. The instance stays usable.
setup and loop (the default). The module exports setup and loop. The host calls setup once, then calls loop over and over:
eccles_wasm_run("setup");
for (;;) { eccles_wasm_run("loop"); /* your firmware can do other work here */ }The host gets control back between iterations. It can feed a watchdog, service WiFi or BLE, check for a new module, swap modules, or stop the module whenever it likes. Each call is one bounded piece of work, so a fuel budget per call works naturally.
main (one call, the module loops inside). For a dedicated device where the module is the whole program, export a single main and loop inside it:
EW_EXPORT("main") void app_main(void) {
ew_enable(2); // setup
for (;;) { ew_toggle(2); ew_sleep(500); }
}eccles_wasm_run("main"); // one call; the module runsWhat you gain: no host-to-WebAssembly call per iteration, and state stays in local variables instead of globals. What to remember:
-
eccles_wasm_run("main")blocks while the module loops. Run it in its own task, or put it last in your start-up code. - Fuel is per call, so leave
eccles_wasm_set_fuel(0)(the default) for amainthat never returns. - Always sleep or wait inside the loop (
ew_sleep). A loop that never sleeps starves the idle task and the watchdog. - To stop it from the host, give the module a stop flag (Cookbook).
Rule of thumb: start with setup and loop. Move to main when the host has nothing else to do, or when the loop is so tight that the per-call overhead matters.
eccles_wasm_load() and friends use a built-in default instance. For several modules at once, create more instances with eccles_wasm_vm_create(). Each has its own arena, privileges and host functions. See Instances.
| Feature | Switch | You provide |
|---|---|---|
| Threads |
ECCLES_WASM_ATOMICS=1, ECCLES_WASM_THREADS=1
|
a spawner (creates the RTOS task) |
| Loading from your own file system | none | eccles_wasm_set_fs(open, read, close) |
| Another chip | none | eccles_wasm_hal_override(&ops) |
| Fastest loop |
ECCLES_WASM_EXEC_IRAM=1, ECCLES_WASM_FUEL=0
|
nothing |
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