Repository navigation
Platform Other MCUs
Any chip with a C99 compiler and enough RAM can run Eccles WASM. The interpreter is portable C; only the hardware functions are chip-specific, and you write only the ones your modules use.
- A 32-bit (or 64-bit) CPU and a C99 compiler. 16-bit and 8-bit parts (AVR, MSP430, PIC, 8051) are refused at compile time unless you set
ECCLES_WASM_ARENA_SIZEyourself, because a module needs tens of KB. - RAM for the arena (about 12 KB for a tiny module, about 100 KB for a stock module, see Memory Sizing).
- About 50 KB of flash.
- Add
eccles_wasm.cto your build, andsrc/to the include path. - Select no backend:
-DECCLES_WASM_PLATFORM=ECCLES_WASM_PLAT_NONE. (If your compiler defines nothing recognisable,PLAT_NONEis what you get anyway.) - Set the arena:
-DECCLES_WASM_ARENA_SIZE=(32ul*1024ul). It is a static array unless you defineECCLES_WASM_USE_HEAP=1. - Load the module from flash with
eccles_wasm_load_buffer(). Without a backend there is no file loading (eccles_wasm_load(path)returnsno filesystem backend) until you calleccles_wasm_set_fs, see Custom Filesystems. - Write the hardware functions you need (next section).
eccles_wasm_hal_override(&ops) replaces backend functions at run time. Fill only the fields you implement. The others keep their previous value, which on PLAT_NONE is "unsupported". A guest calling an unsupported function simply gets status 2.
The fields, one per guest import: gpio_mode, gpio_write, gpio_read, analog, pwm, adc, dac, millis, micros, sleep_ms, sleep_us, yield, deep_sleep, reset, random, wdt_feed, log, irq_attach, irq_count, irq_clear, irq_detach, uart_begin, uart_write, uart_read, uart_end, i2c_begin, i2c_write, i2c_read, i2c_write_read, spi_begin, spi_transfer, spi_end. Signatures are in Host API Reference.
Return values: ECCLES_WASM_SUCCESSFUL (0) when done, ECCLES_WASM_FAILED (1) for a bad argument or a hardware error, ECCLES_WASM_UNSUPPORTED (2) when the chip cannot do it.
A complete, runnable example (the "chip" is a few variables so it runs on a PC; replace the bodies with register accesses):
/* custom_hal.c - run Eccles WASM on a chip that has no built-in backend.
* You write only the hardware functions your guests use; every other function stays UNSUPPORTED (2).
* Here the "chip" is a few variables so the example runs on a PC; on your chip, replace the bodies with register writes. */
#include "eccles_wasm.h"
#include <stdio.h>
static uint32_t g_pins; /* stand-in for your GPIO output register */
static uint32_t g_ms; /* stand-in for your millisecond tick */
static eccles_wasm_status_t my_mode(uint32_t pin, uint32_t mode) {
if (pin > 31) return ECCLES_WASM_FAILED; /* FAILED: the pin does not exist on this chip */
(void)mode; /* set the pin's direction register here */
return ECCLES_WASM_SUCCESSFUL;
}
static eccles_wasm_status_t my_write(uint32_t pin, uint32_t level) {
if (pin > 31) return ECCLES_WASM_FAILED;
if (level) g_pins |= 1u << pin; else g_pins &= ~(1u << pin);
return ECCLES_WASM_SUCCESSFUL;
}
static eccles_wasm_status_t my_read(uint32_t pin, uint32_t *level) {
if (pin > 31) return ECCLES_WASM_FAILED;
*level = (g_pins >> pin) & 1u;
return ECCLES_WASM_SUCCESSFUL;
}
static eccles_wasm_status_t my_millis(uint32_t *ms) { *ms = g_ms; return ECCLES_WASM_SUCCESSFUL; }
static eccles_wasm_status_t my_sleep(uint32_t ms) { g_ms += ms; return ECCLES_WASM_SUCCESSFUL; } /* a real chip waits here */
static eccles_wasm_status_t my_log(const uint8_t *buf, uint32_t len) {
fwrite(buf, 1, len, stdout); /* a real chip writes to its UART here */
return ECCLES_WASM_SUCCESSFUL;
}
int main(int argc, char **argv) {
const char *path = argc > 1 ? argv[1] : "build/wiki/led.wasm";
uint64_t a[1] = { 3 }, r[1];
eccles_wasm_hal_t hal = {0}; /* every field you leave NULL stays as it was (UNSUPPORTED here) */
hal.gpio_mode = my_mode;
hal.gpio_write = my_write;
hal.gpio_read = my_read;
hal.millis = my_millis;
hal.sleep_ms = my_sleep;
hal.log = my_log;
eccles_wasm_hal_override(&hal);
eccles_wasm_set_hal_privilege(ECCLES_WASM_ALLOW_PIN_ALL | ECCLES_WASM_ALLOW_SAFE);
if (eccles_wasm_load(path) != ECCLES_WASM_SUCCESSFUL) return 1;
eccles_wasm_call("blink", a, 1, r, 1);
printf("pin register = 0x%08X, uptime = %u ms\n", (unsigned)g_pins, (unsigned)g_ms);
eccles_wasm_call("led_on", NULL, 0, r, 1);
printf("led_on() = %d, pin register = 0x%08X\n", (int)r[0], (unsigned)g_pins);
return 0;
}(file: examples/wiki/host/custom_hal.c)
Output:
blink finished with status 0 (ok)
pin register = 0x00000000, uptime = 600 ms
led_on() = 0, pin register = 0x00000004
The minimum for most guests is five functions: gpio_mode, gpio_write, millis, sleep_ms and log.
Compile the guest, then look at its imports: wasm-objdump -x app.wasm | grep Import (WABT), or run the module and print eccles_wasm_last_denied(). The Guest Import Reference lists which function each import uses.
The same function works on a supported platform. For example, give the STM32 backend an ADC:
static eccles_wasm_status_t my_adc(uint32_t pin, uint32_t *value) {
HAL_ADC_Start(&hadc1);
HAL_ADC_PollForConversion(&hadc1, 10);
*value = HAL_ADC_GetValue(&hadc1);
return ECCLES_WASM_SUCCESSFUL;
}
...
eccles_wasm_hal_t hal = {0};
hal.adc = my_adc;
eccles_wasm_hal_override(&hal);eccles_wasm_hal_reset() goes back to the built-in backend.
Place the arena where you want with eccles_wasm_init_with(mem, size), or per instance with eccles_wasm_vm_create(mem, size). Call it before the first load.
Because eccles_wasm_hal_override is portable, test the same guest on the desktop simulator, then switch to your chip.
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