Repository navigation
Safety Fuel and Traps
Running code you did not write on a microcontroller needs three guarantees: it cannot corrupt your firmware, it cannot run forever, and a fault does not take the device down. Eccles WASM gives all three.
- The guest only sees its own linear memory. Every load and store is bounds-checked. A wild pointer ends the call with a trap and the chip carries on.
- Function calls go through typed tables: calling through a wrong pointer type traps (
indirect call type mismatch). - The guest's value stack and call depth are bounded (
ECCLES_WASM_VALUE_STACK_SLOTS,ECCLES_WASM_CALL_DEPTH). Runaway recursion traps with a stack or call-depth error. - The guest cannot reach hardware except through the imports you permit (Permissions).
- The loader validates the module's structure before running a single instruction, and rejects malformed modules with a byte offset. A truncated or otherwise malformed file is refused, not executed. The conformance suite throws truncated and mutated modules at a real ESP32 and requires that the chip never crashes (Validation, phase F).
What the loader does not do: it checks structure, not operand types. Use toolchains you trust to emit valid wasm (clang, rustc, wasm-opt), and authenticate modules you download (hash or signature) before loading.
eccles_wasm_set_fuel(1000000); // every call gets a budget of 1,000,000 unitsA budget counts calls and backward branches, one unit each. When it runs out the call ends with TRAP_FUEL ("trap: instruction budget exhausted") and the instance stays usable. 0 means unlimited. The budget applies to each eccles_wasm_call, it is not shared across calls.
/* 05_fuel_and_traps.c - a bad guest cannot hurt the host: infinite loops, divide by zero, wild pointers. */
#include "eccles_wasm.h"
#include <stdio.h>
static void report(const char *what, eccles_wasm_status_t st) {
printf("%-28s -> status %d, error %s\n", what, (int)st, eccles_wasm_error_name(eccles_wasm_last_error()));
}
int main(int argc, char **argv) {
const char *dir = argc > 1 ? argv[1] : "build/wiki";
char path[256]; uint64_t a[2], r[1];
/* ---- fuel: stop endless loops ---- */
snprintf(path, sizeof path, "%s/forever.wasm", dir);
eccles_wasm_load(path);
eccles_wasm_set_fuel(100000); /* backward branches and calls cost 1 each, 0 = unlimited */
report("spin() with 100000 fuel", eccles_wasm_run("spin"));
report("quick() afterwards", eccles_wasm_call("quick", NULL, 0, r, 1));
printf("quick() = %d - the instance is still healthy\n", (int)eccles_wasm_to_i32(r[0]));
/* ---- traps ---- */
snprintf(path, sizeof path, "%s/crash.wasm", dir);
eccles_wasm_load(path);
a[0] = 10; a[1] = 0;
report("div(10, 0)", eccles_wasm_call("div", a, 2, r, 1));
a[0] = 100000;
report("oob(100000)", eccles_wasm_call("oob", a, 1, r, 1));
report("boom()", eccles_wasm_run("boom"));
a[0] = 10; a[1] = 2;
report("div(10, 2)", eccles_wasm_call("div", a, 2, r, 1));
printf("div(10, 2) = %d\n", (int)eccles_wasm_to_i32(r[0]));
/* ---- API misuse is an error code too ---- */
report("call a missing export", eccles_wasm_run("does_not_exist"));
report("wrong argument count", eccles_wasm_call("div", a, 1, r, 1));
eccles_wasm_unload();
report("call with nothing loaded", eccles_wasm_run("div"));
return 0;
}(file: examples/wiki/host/05_fuel_and_traps.c)
Output:
spin() with 100000 fuel -> status 1, error trap: instruction budget exhausted
quick() afterwards -> status 0, error ok
quick() = 42 - the instance is still healthy
div(10, 0) -> status 1, error trap: integer divide by zero
oob(100000) -> status 1, error trap: out-of-bounds memory access
boom() -> status 1, error trap: unreachable
div(10, 2) -> status 0, error ok
div(10, 2) = 5
call a missing export -> status 1, error no such export
wrong argument count -> status 1, error signature mismatch
call with nothing loaded -> status 1, error no module loaded
Choosing a number: run your real module once with a large budget and measure, then set the limit to a few times the normal need. A loop() that blinks and sleeps costs very little fuel because sleep is a single call. A busy computation (a CRC over a few KB) costs about one unit per loop iteration.
Fuel is compiled in by default (ECCLES_WASM_FUEL 1). For maximum speed on code you fully trust, build with -DECCLES_WASM_FUEL=0: the check disappears and set_fuel does nothing (Speed Tuning).
Every ECCLES_WASM_YIELD_INTERVAL back-branches and calls (4096 by default, a power of two) the runtime calls ECCLES_WASM_YIELD(), which you can define to feed a watchdog or let the scheduler run:
#define ECCLES_WASM_YIELD_INTERVAL 4096
#define ECCLES_WASM_YIELD() vTaskDelay(0)This is what keeps a long computation from tripping a task watchdog without fuel. The guest can also call ew_yield() or ew_sleep().
A trap ends the current call. The call returns ECCLES_WASM_FAILED, eccles_wasm_last_error() tells which trap, and the instance is still loaded and callable.
| Trap | Typical cause |
|---|---|
unreachable |
__builtin_trap(), a Rust panic, an abort()
|
out-of-bounds memory access |
wild or stale pointer; access beyond MEM_LIMIT_BYTES
|
integer divide by zero |
x / 0 |
integer overflow |
INT_MIN / -1 |
invalid conversion to integer |
float NaN or out of range to int (use the saturating forms) |
undefined table element |
calling an empty function-pointer slot |
indirect call type mismatch |
function pointer with the wrong signature |
value stack overflow |
too many locals or deep expressions: raise ECCLES_WASM_VALUE_STACK_SLOTS
|
call stack overflow |
recursion too deep: raise ECCLES_WASM_CALL_DEPTH
|
instruction budget exhausted |
fuel ran out |
host function failed |
one of your host functions returned something other than SUCCESSFUL |
out-of-bounds table access |
table.get / table.set / table.copy with a bad index |
unaligned atomic access ... |
see Atomics |
A guest overflowing its own C stack is not reported as a stack trap: it either corrupts the guest's own data or ends in an out-of-bounds trap. It cannot reach your firmware, but size -Wl,-z,stack-size generously for recursive code.
eccles_wasm_set_hal_privilege(ECCLES_WASM_ALLOW_SAFE); // no pins, no buses
eccles_wasm_set_fuel(500000); // no endless loops
// load it from an authenticated source, then:
if (eccles_wasm_call("run", NULL, 0, r, 1) != ECCLES_WASM_SUCCESSFUL) {
log_error(eccles_wasm_error_name(eccles_wasm_last_error()));
eccles_wasm_unload(); // drop it, carry on
}Arena exhaustion is also contained: loading a module that is too big fails with out of arena memory and leaves the device untouched.
Call again, or unload and load a fresh copy. The guest's own state (globals, memory) is whatever it was when the trap happened. If the module keeps its own invariants in memory, reload it after a trap to start clean.
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