File syn_wasm.h¶

FileList > src > syntropic > vm > syn_wasm.h

[EXPERIMENTAL] Zero-heap, 32-bit WebAssembly (Wasm MVP) cooperative interpreter. More...

#include "../common/syn_defs.h"
#include "../util/syn_qmath.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_WASM_CallFrame WebAssembly runtime call frame.
struct	SYN_WASM_Context_s WebAssembly virtual machine execution context.
struct	SYN_WASM_FuncDef WebAssembly function definition metadata.
struct	SYN_WASM_Label WebAssembly control flow label stack entry.
struct	SYN_WASM_Module Parsed WebAssembly module header and export registry.

Public Types¶

Type	Name
typedef uint64_t(*	SYN_WASM_HostFunc Host function signature callable from Wasm bytecode.
enum	SYN_WASM_Status WebAssembly VM execution status codes and traps.

Public Functions¶

Type	Name
bool	syn_wasm_call (SYN_WASM_Context * ctx, uint16_t func_index) Prepare context to call a function index.
int32_t	syn_wasm_find_export (const SYN_WASM_Module * mod, const char * name) Find exported function index by name.
bool	syn_wasm_init (SYN_WASM_Context * ctx, const SYN_WASM_Module * mod, uint8_t * linear_mem, uint32_t mem_size) Initialize execution context for loaded module.
bool	syn_wasm_module_load (SYN_WASM_Module * mod, const uint8_t * bytes, uint32_t size) Parse Wasm binary module from flash buffer (zero memory allocation).
bool	syn_wasm_register_host (SYN_WASM_Context * ctx, uint16_t import_index, SYN_WASM_HostFunc func) Register C host function for imported Wasm functions.
uint64_t	syn_wasm_result (const SYN_WASM_Context * ctx) Read top of evaluation stack result after HALTED.
SYN_WASM_Status	syn_wasm_step (SYN_WASM_Context * ctx, uint16_t max_instructions) Execute instruction slice non-blockingly.

Macros¶

Type	Name
define	SYN_WASM_MAX_CALL_DEPTH `32`
define	SYN_WASM_MAX_FUNCTIONS `32`
define	SYN_WASM_MAX_GLOBALS `16`
define	SYN_WASM_MAX_HOST_FUNCS `16`
define	SYN_WASM_MAX_LABELS `16`
define	SYN_WASM_MAX_LOCALS `256`
define	SYN_WASM_MAX_STACK `64`

Detailed Description¶

Warning:

EXPERIMENTAL MODULE - API and bytecode execution semantics subject to change.

Implements a 100% zero-malloc, non-blocking 32-bit WebAssembly MVP interpreter designed for embedded microcontrollers. Supports static linear memory arrays, zero-copy parsing from flash, host function registration, and instruction-sliced cooperative execution with protothread (syn_pt) integration.

Recommended C-to-WASM compilation command for user applications: clang target=wasm32-unknown-unknown -O2 -nostdlib \ -mbulk-memory -msign-ext -mmultivalue -mnontrapping-fptoint \ -Wl,no-entry -Wl,export-all -Wl,allow-undefined \ -Wl,-z,stack-size=1024 app.c -o app.wasm

Public Types Documentation¶

typedef SYN_WASM_HostFunc¶

Host function signature callable from Wasm bytecode.

typedef uint64_t(* SYN_WASM_HostFunc) (SYN_WASM_Context *ctx, const uint64_t *args, uint8_t argc);

Parameters:

ctx Pointer to Wasm execution context.
args Array of 32-bit arguments passed from Wasm stack.
argc Number of arguments.

Returns:

32-bit return value (pushed onto Wasm stack).

enum SYN_WASM_Status¶

WebAssembly VM execution status codes and traps.

enum SYN_WASM_Status {
    SYN_WASM_OK = 0,
    SYN_WASM_YIELDED,
    SYN_WASM_HALTED,
    SYN_WASM_TRAP_STACK_OVERFLOW,
    SYN_WASM_TRAP_STACK_UNDERFLOW,
    SYN_WASM_TRAP_OUT_OF_BOUNDS,
    SYN_WASM_TRAP_BAD_OPCODE,
    SYN_WASM_TRAP_DIV_ZERO,
    SYN_WASM_TRAP_UNREACHABLE,
    SYN_WASM_TRAP_CALL_STACK_OVERFLOW,
    SYN_WASM_TRAP_TYPE_MISMATCH,
    SYN_WASM_TRAP_INVALID_MODULE,
    SYN_WASM_TRAP_UNREGISTERED_HOST
};

Public Functions Documentation¶

function syn_wasm_call¶

Prepare context to call a function index.

bool syn_wasm_call (
    SYN_WASM_Context * ctx,
    uint16_t func_index
)

Parameters:

ctx Pointer to context.
func_index Function index to invoke.

Returns:

true if call frame initialized successfully.

function syn_wasm_find_export¶

Find exported function index by name.

int32_t syn_wasm_find_export (
    const SYN_WASM_Module * mod,
    const char * name
)

Parameters:

mod Pointer to loaded module.
name Exported function name string.

Returns:

Function index if found, or -1 if not found.

function syn_wasm_init¶

Initialize execution context for loaded module.

bool syn_wasm_init (
    SYN_WASM_Context * ctx,
    const SYN_WASM_Module * mod,
    uint8_t * linear_mem,
    uint32_t mem_size
)

Parameters:

ctx Pointer to context structure.
mod Pointer to loaded module descriptor.
linear_mem Pointer to statically-allocated linear memory byte array.
mem_size Size of linear memory buffer in bytes.

Returns:

true if initialized successfully.

function syn_wasm_module_load¶

Parse Wasm binary module from flash buffer (zero memory allocation).

bool syn_wasm_module_load (
    SYN_WASM_Module * mod,
    const uint8_t * bytes,
    uint32_t size
)

Parameters:

mod Pointer to module descriptor to populate.
bytes Pointer to flash buffer containing .wasm binary.
size Length of wasm binary buffer.

Returns:

true if valid Wasm MVP binary module parsed successfully.

function syn_wasm_register_host¶

Register C host function for imported Wasm functions.

bool syn_wasm_register_host (
    SYN_WASM_Context * ctx,
    uint16_t import_index,
    SYN_WASM_HostFunc func
)

Parameters:

ctx Pointer to context.
import_index Index of import function slot (0 .. import_func_count - 1).
func Function pointer to host C handler.

Returns:

true if registered successfully.

function syn_wasm_result¶

Read top of evaluation stack result after HALTED.

uint64_t syn_wasm_result (
    const SYN_WASM_Context * ctx
)

Parameters:

ctx Pointer to context.

Returns:

32-bit return value.

function syn_wasm_step¶

Execute instruction slice non-blockingly.

SYN_WASM_Status syn_wasm_step (
    SYN_WASM_Context * ctx,
    uint16_t max_instructions
)

Parameters:

ctx Pointer to context.
max_instructions Maximum opcodes to process before yielding.

Returns:

SYN_WASM_OK (completed), SYN_WASM_YIELDED (time slice expired), SYN_WASM_HALTED (finished), or TRAP.

Macro Definition Documentation¶

define SYN_WASM_MAX_CALL_DEPTH¶

#define SYN_WASM_MAX_CALL_DEPTH `32`

Maximum call frame stack depth

define SYN_WASM_MAX_FUNCTIONS¶

#define SYN_WASM_MAX_FUNCTIONS `32`

Maximum internal function defs

define SYN_WASM_MAX_GLOBALS¶

#define SYN_WASM_MAX_GLOBALS `16`

Maximum global variables

define SYN_WASM_MAX_HOST_FUNCS¶

#define SYN_WASM_MAX_HOST_FUNCS `16`

Maximum registered host functions

define SYN_WASM_MAX_LABELS¶

#define SYN_WASM_MAX_LABELS `16`

Maximum block/loop control labels

define SYN_WASM_MAX_LOCALS¶

#define SYN_WASM_MAX_LOCALS `256`

Maximum local variable count per frame

define SYN_WASM_MAX_STACK¶

#define SYN_WASM_MAX_STACK `64`

Maximum operand stack depth

The documentation for this class was generated from the following file src/syntropic/vm/syn_wasm.h