Wasm

This is the wasm section of niso_runtime.h, owned by niso-wasm and kept in crates/niso-core/include/wasm.h. The build composes it with the other sections in the order crates/niso-compose/sections.txt gives.

Functions: niso_wasm_set_hooks, niso_wasm_queue_task, niso_wasm_validate, niso_wasm_compile, niso_wasm_module_release, niso_wasm_module_imports, niso_wasm_module_exports, niso_wasm_module_custom_sections, niso_wasm_instantiate, niso_wasm_func_new, niso_wasm_func_info, niso_wasm_call, niso_wasm_set_results, niso_wasm_take_moved, niso_wasm_memory_new, niso_wasm_memory_data, niso_wasm_memory_grow, niso_wasm_memory_type, niso_wasm_table_new, niso_wasm_table_type, niso_wasm_table_get, niso_wasm_table_set, niso_wasm_table_grow, niso_wasm_global_new, niso_wasm_global_type, niso_wasm_global_get, niso_wasm_global_set

WebAssembly: the surrounding agent’s store for the JS API, one per DOM, run by an interpreter (wasmi). Modules have ids, and functions, tables, memories and globals (“externs”) share one id space where each store address has exactly one id.

Values cross as doubles: an i32, f32, f64 or reference is one (a funcref is its function’s extern id, an externref an id the binding gives its host value, null is 0); an i64 is two, its low and high 32 bits as unsigned numbers. A function type is a string: one character per parameter type, a colon, one per result type, with i i32, I i64, f f32, F f64, v v128, r funcref and e externref. A global’s type is its value type, then m when it is mutable; a table’s is its element type, then I when it is 64-bit; a memory’s is i or I, its address type.

Failures are NISO_WASM_COMPILE_ERROR, NISO_WASM_LINK_ERROR, NISO_WASM_RUNTIME_ERROR (a trap), NISO_RANGE_ERROR (a failed allocation or a stack overflow), NISO_TYPE_ERROR, or NISO_CALLBACK_ERROR when a host function threw: then the binding rethrows what it threw.

Host functions call the call hook synchronously, with the callback id they were made with and their encoded arguments after one flag; the flag is 1 when niso_wasm_take_moved has memories. The hook returns 0 after setting the results with niso_wasm_set_results, or nonzero when the function threw. While it runs, any niso_wasm call works on the same store. A task queued with niso_wasm_queue_task runs the task hook with its job from the DOM’s task queue. Numbers handed out stay valid until the next call.

typedef int32_t (*niso_wasm_call_fn)(void* userdata, uint64_t callback, const double* args, size_t len);
typedef void (*niso_wasm_task_fn)(void* userdata, uint64_t job);
typedef struct niso_doubles {
    const double* ptr;
    size_t len;
} niso_doubles;

void niso_wasm_set_hooks(niso_dom* dom, niso_wasm_call_fn call, niso_wasm_task_fn task, void* userdata);
void niso_wasm_queue_task(niso_dom* dom, uint64_t job);
bool niso_wasm_validate(niso_dom* dom, const uint8_t* bytes, size_t len);
int32_t niso_wasm_compile(niso_dom* dom, const uint8_t* bytes, size_t len, uint32_t* module);
void niso_wasm_module_release(niso_dom* dom, uint32_t module);

Per import: module name, name, kind (function, table, memory, global) and type.

int32_t niso_wasm_module_imports(niso_dom* dom, uint32_t module, niso_strs* out);

Per export, in the binary’s order: name, kind and type.

int32_t niso_wasm_module_exports(niso_dom* dom, uint32_t module, niso_strs* out);

The contents of the custom sections named name: u32 count, then per section a u32 length and its bytes, little-endian.

int32_t niso_wasm_module_custom_sections(niso_dom* dom, uint32_t module, const char* name, size_t name_len, niso_bytes* out);

An extern id per import in; an extern id per export out, in export order.

int32_t niso_wasm_instantiate(niso_dom* dom, uint32_t module, const uint32_t* imports, size_t len, niso_doubles* exports);

A host function of type sig that runs the call hook with callback; name is its index among the imports it is made for, the JS API’s function name.

int32_t niso_wasm_func_new(niso_dom* dom, const char* sig, size_t sig_len, uint64_t callback, uint32_t name, uint32_t* id);
int32_t niso_wasm_func_info(niso_dom* dom, uint32_t id, niso_str* sig, uint32_t* name);

Results: one flag as for the call hook, then the encoded results.

int32_t niso_wasm_call(niso_dom* dom, uint32_t id, const double* args, size_t len, niso_doubles* results);
void niso_wasm_set_results(niso_dom* dom, const double* results, size_t len);

Memories whose data the binding took with niso_wasm_memory_data and that moved or changed length since: it must stop using that data before it runs script, as the JS API detaches their buffers.

void niso_wasm_take_moved(niso_dom* dom, niso_doubles* memories);

Sizes are in pages; a negative maximum is none.

int32_t niso_wasm_memory_new(niso_dom* dom, double initial, double maximum, bool is64, uint32_t* id);
int32_t niso_wasm_memory_data(niso_dom* dom, uint32_t id, uint8_t** ptr, size_t* len);
int32_t niso_wasm_memory_grow(niso_dom* dom, uint32_t id, double delta, double* old);
int32_t niso_wasm_memory_type(niso_dom* dom, uint32_t id, double* pages, double* maximum, bool* is64);
int32_t niso_wasm_table_new(niso_dom* dom, uint8_t element, double initial, double maximum, bool is64, const double* init,
                            size_t init_len, uint32_t* id);
int32_t niso_wasm_table_type(niso_dom* dom, uint32_t id, uint8_t* element, double* length, bool* is64);
int32_t niso_wasm_table_get(niso_dom* dom, uint32_t id, double index, niso_doubles* value);
int32_t niso_wasm_table_set(niso_dom* dom, uint32_t id, double index, const double* value, size_t len);
int32_t niso_wasm_table_grow(niso_dom* dom, uint32_t id, double delta, const double* value, size_t len, double* old);
int32_t niso_wasm_global_new(niso_dom* dom, uint8_t type, bool is_mutable, const double* value, size_t len, uint32_t* id);
int32_t niso_wasm_global_type(niso_dom* dom, uint32_t id, niso_str* type);
int32_t niso_wasm_global_get(niso_dom* dom, uint32_t id, niso_doubles* value);
int32_t niso_wasm_global_set(niso_dom* dom, uint32_t id, const double* value, size_t len);