Repository navigation
Bring Up Checklist
A procedure that gets Eccles WASM running on any microcontroller, in small steps. Every step has one clear pass signal. If a step fails, fix only that step before moving on. Most chips are running by step 4.
git clone https://github.com/igwe-starking/eccles-wasm && cd eccles-wasm
make examples && build/example_host examples/blink.wasmIf this fails, the problem is your PC toolchain, not your chip.
Build and flash a plain "blink and print" program using your normal SDK. If you cannot see output from the chip, nothing below can be diagnosed. Get a serial console working first.
Add eccles_wasm.c to the build and src/ to the include path (Install). Build. Pass signal: it compiles and links.
| Problem | Fix |
|---|---|
eccles_wasm.h: No such file |
include path is missing src/
|
undefined sqrt / sqrtf
|
link the math library (-lm), or define ECCLES_WASM_NO_FLOAT
|
| the wrong backend is picked | force it: -DECCLES_WASM_PLATFORM=ECCLES_WASM_PLAT_ESP_IDF (or _ARDUINO, _PICO, _STM32_HAL, _ZEPHYR, _NONE) |
.c file compiled as C++ |
name it .c; in Arduino it is already handled |
overflow of .bss or region 'RAM' overflowed
|
the arena is bigger than your RAM: set -DECCLES_WASM_ARENA_SIZE=... (Memory Sizing) |
Make the test module and its C array on your PC:
clang --target=wasm32 -O2 -nostdlib -ffreestanding -Wl,--no-entry -Wl,--export-all \
-Wl,-z,stack-size=4096 -Wl,--initial-memory=65536 -Isdk/c -o hello.wasm examples/wiki/guest/hello.c
python3 tools/wasm2c.py hello.wasm hello_wasm.h hello_wasmAdd hello_wasm.h and this file to your project, and call eccles_bringup() once from main():
/* bringup.c - the smoke test to run first on any new chip. Call eccles_bringup() from your main().
* It needs only hello_wasm.h (make it with: python3 tools/wasm2c.py hello.wasm hello_wasm.h hello_wasm).
* It prints one line per stage; the first stage that does not say OK is where to look (see the Bring-Up Checklist wiki page).
* On a chip without printf, define BRINGUP_PRINT(...) before this file, for example to Serial.printf or ESP_LOGI. */
#include "eccles_wasm.h"
#include "hello_wasm.h"
#ifndef BRINGUP_PRINT
#include <stdio.h>
#define BRINGUP_PRINT(...) printf(__VA_ARGS__)
#endif
int eccles_bringup(void) {
uint64_t args[2], res[1];
eccles_wasm_stats_t s;
BRINGUP_PRINT("eccles-wasm %s\n", ECCLES_WASM_VERSION_STRING);
/* 1. load (checks: arena size, runtime compiled in, module accepted) */
if (eccles_wasm_load_buffer(hello_wasm, hello_wasm_len) != ECCLES_WASM_SUCCESSFUL) {
BRINGUP_PRINT("stage 1 load: FAIL %s, info %u (see Error Reference)\n",
eccles_wasm_error_name(eccles_wasm_last_error()), (unsigned)eccles_wasm_last_error_info());
return 1;
}
BRINGUP_PRINT("stage 1 load: OK\n");
/* 2. compute (checks: the interpreter itself) */
args[0] = eccles_wasm_from_i32(20);
args[1] = eccles_wasm_from_i32(22);
if (eccles_wasm_call("add", args, 2, res, 1) != ECCLES_WASM_SUCCESSFUL || eccles_wasm_to_i32(res[0]) != 42) {
BRINGUP_PRINT("stage 2 compute: FAIL %s\n", eccles_wasm_error_name(eccles_wasm_last_error()));
return 2;
}
BRINGUP_PRINT("stage 2 compute: OK add(20, 22) = 42\n");
/* 3. memory report (checks: the arena and the guest memory exist; eccles_wasm_get_stats() also has arena_used) */
s = eccles_wasm_get_stats();
BRINGUP_PRINT("stage 3 memory: OK arena %u bytes, guest memory %u bytes\n",
(unsigned)s.arena_size, (unsigned)s.memory_bytes);
/* 4. privileges (checks: deny-by-default works) */
eccles_wasm_set_hal_privilege(ECCLES_WASM_ALLOW_NONE);
eccles_wasm_run("hello"); /* hello() wants the console and the clock */
if (eccles_wasm_denied_count() == 0) {
BRINGUP_PRINT("stage 4 denied: FAIL the module was not refused\n");
return 4;
}
BRINGUP_PRINT("stage 4 denied: OK refused calls: %u (last: %s)\n", (unsigned)eccles_wasm_denied_count(), eccles_wasm_last_denied());
/* 5. console from the guest (checks: the log backend) */
eccles_wasm_set_hal_privilege(ECCLES_WASM_ALLOW_SAFE);
BRINGUP_PRINT("stage 5 console: the next line comes from inside the module:\n");
if (eccles_wasm_run("hello") != ECCLES_WASM_SUCCESSFUL) {
BRINGUP_PRINT("stage 5 console: FAIL %s\n", eccles_wasm_error_name(eccles_wasm_last_error()));
return 5;
}
BRINGUP_PRINT("bring-up complete: PASS\n");
return 0;
}
#ifdef BRINGUP_MAIN
int main(void) { return eccles_bringup(); }
#endif(file: examples/wiki/host/bringup.c)
Expected output (on a chip the time and sizes differ):
eccles-wasm 2.0.0
stage 1 load: OK
stage 2 compute: OK add(20, 22) = 42
stage 3 memory: OK arena 1046784 bytes, guest memory 65536 bytes
stage 4 denied: OK refused calls: 2 (last: log)
stage 5 console: the next line comes from inside the module:
hello from wasm, running for 0 ms
bring-up complete: PASS
Where it stops tells you what to fix:
| Stops at | Meaning | Go to |
|---|---|---|
stage 1 no memory
|
arena too small (the number printed is the bytes needed) | Memory Sizing |
stage 1 module exceeds a configured limit
|
module bigger than a configured limit | Troubleshooting |
stage 1 malformed module
|
the array is corrupt or truncated | regenerate it with tools/wasm2c.py
|
| stage 2 fails | a build option mismatch between your code and eccles_wasm.c
|
Troubleshooting |
| stage 4 does not refuse |
ECCLES_WASM_DEFAULT_PRIVILEGE was changed |
Configuration |
| stage 5 prints nothing | no console backend: Arduino needs eccles_wasm_use_serial(Serial), STM32 and others need a HAL override for log
|
your platform page |
| the chip resets or hangs | stack too small or a watchdog | Troubleshooting |
Pass signal: bring-up complete: PASS.
Compile the LED module, embed it, grant pins, run it:
eccles_wasm_set_hal_privilege(ECCLES_WASM_ALLOW_PIN_ALL | ECCLES_WASM_ALLOW_SAFE);
eccles_wasm_load_buffer(led_wasm, led_wasm_len);
uint64_t a[1] = { eccles_wasm_from_i32(5) };
eccles_wasm_call("blink", a, 1, NULL, 0); // blinks pin 2 five timesThe module is examples/wiki/guest/led.c; it uses pin 2. Change #define LED 2 to your board's LED pin number (see Platforms Overview for numbering). Pass signal: the LED blinks and the console says blink finished with status 0 (ok).
If it prints status 3 (denied), you skipped the grant. If 2 (unsupported), the backend lacks that function on your chip (capability table). If 1 (failed), the pin number is invalid for the chip.
Run eccles_wasm_get_stats() after loading your real module. Set ECCLES_WASM_ARENA_SIZE a little above arena_used, and ECCLES_WASM_MEM_LIMIT_BYTES to what the guest really uses (Memory Sizing). Set a fuel limit: eccles_wasm_set_fuel(...) (Safety).
- Arduino, ESP-IDF:
eccles_wasm_load("/littlefs/app.wasm"), see Loading Modules. - Your own storage: Custom Filesystems.
- OTA or a socket:
eccles_wasm_load_stream.
Only if the guest spawns threads. Add ECCLES_WASM_ATOMICS=1, ECCLES_WASM_THREADS=1, a spawner and a hardware lock: Threads and the Spawner.
- Enable
-DECCLES_WASM_DEBUGand defineECCLES_WASM_LOG_LINE(msg)to print: load failures are then logged. - Print
eccles_wasm_error_name(eccles_wasm_last_error()),eccles_wasm_last_error_info()andeccles_wasm_last_error_str()after every failed call. - Find your message in Troubleshooting.
- Open an issue with the chip, SDK version, your config, and that output.
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