1/* @ajax/mesh-exec-wasm: the wasm executor (mesh-abi BACKEND_WASM), ported from alpha-rust-mesh
2 * mesh-host/src/wasm.rs: CPU programs as WebAssembly modules run inside meshd, beside the GPU
3 * backend, on every platform.
4 *
5 * - Images. `<name>.wasm` beside program.toml. The compile -- here @ajax/wasm-interp's decode,
6 *   validate and lower; in the Rust, Cranelift -- runs on the driver's JIT thread; with --wasm-cache
7 *   DIR the module is kept there (@ajax/mesh-exec-wasm-cache). The image hash is the PTX's when the
8 *   catalog has one, else the wasm's, with `param` folded in.
9 * - One engine: NaN canonicalisation, no signal handlers (explicit bounds checks), epoch
10 *   interruption, no threads.
11 * - The float guard (@ajax/wasm-float-guard), at load.
12 * - Lanes. A running slot is `nodes` lease lanes (@ajax/mesh-lease): one thread per node, each with
13 *   its own instance, taking the slot's tickets one at a time and running mesh_init /
14 *   mesh_task(op, arg). Linear memory is scratch; program state lives in the view, reached through
15 *   the mesh::* imports (@ajax/mesh-exec-wasm-imports).
16 * - Isolation. Each lane's memory is capped at the manifest's mem_mb; each task has an epoch
17 *   deadline of task_ms (an epoch thread ticks every ms while lanes run; the wait in a lockstep
18 *   exchange re-arms it): an overrun traps (FAULT_TIME), any other trap is FAULT_TRAP, and the lane
19 *   re-instantiates while the driver fails the slot -- meshd and every other slot run on.
20 * - Lifecycle. A wasm slot is isolated and not resident: its load, upgrade, rollback and unload
21 *   halt only itself, and a GPU whole-context blink never halts it (its lanes ignore H_BLINK). */
22#ifndef MESH_EXEC_WASM_H
23#define MESH_EXEC_WASM_H
24
25#include "mesh/backend.h"
26#include "mesh/exec_wasm_imports.h"
27#include "wasm/float_guard.h"
28#include "wasm/interp.h"
29
30#include <stdatomic.h>
31#include <stdbool.h>
32#include <stddef.h>
33#include <stdint.h>
34
35/* The engine's tick while lanes run (a task's budget is task_ms ticks). */
36#define MESH_WASM_TICK_NS 1000000ull
37
38typedef struct mesh_wasm_rt mesh_wasm_rt;
39
40/* What meshd shares with every lane and compile: the cache dir and the epoch thread. NULL with
41 * *err ("--wasm-cache DIR: ..."). */
42mesh_wasm_rt *mesh_wasm_rt_new(const char *cache, char **err);
43void mesh_wasm_rt_free(mesh_wasm_rt *rt);
44/* The engine's identity for cached modules. */
45uint64_t mesh_wasm_engine_hash(void);
46/* The module for wasm (from the cache when it holds it): *how is "compiled" or "cached". */
47wasm_compiled *mesh_wasm_rt_module(mesh_wasm_rt *rt, const char *name, const uint8_t *wasm, size_t n, double *ms,
48                                   const char **how, char **err);
49
50/* A compiled wasm image (the Kernel of a wasm slot). */
51typedef struct {
52    char *name;
53    wasm_compiled *module;
54    mesh_wasm_rt *rt;
55    uint32_t rt_abi;
56    uint64_t wasm_hash; /* fnv1a64 of the .wasm (the image hash is the PTX's when the catalog has one) */
57    uint64_t mem_bytes;
58    uint32_t task_ms;
59    wasm_float_report float_report;
60    _Atomic int refs; /* the kernel and each running lane (the Rust's InstancePre clones) */
61} mesh_wasm_program;
62
63/* A fresh instance of p for (slot, node of nodes) on mailbox base, its lane data in *data (which
64 * must outlive the instance). NULL with *err ("load: <name>: instantiate: ..."). */
65wasm_instance *mesh_wasm_instantiate(const mesh_wasm_program *p, mesh_mailbox mb, uint32_t slot, uint32_t node,
66                                     uint32_t nodes, mesh_wasm_lane_data *data, char **err);
67
68/* The executor: mailbox is the shared mailbox (the GPU backend's when beside it; its own for a
69 * CPU-only meshd, `--backend wasm`, and kcheck); cache: --wasm-cache or NULL. */
70bool mesh_wasm_backend_open(uint8_t *mailbox, const char *cache, mesh_backend **out, char **err);
71/* The program behind a wasm kernel (tests, tools). */
72const mesh_wasm_program *mesh_wasm_kernel_program(const mesh_kernel *k);
73
74/* The P_FAULT word for a failed call: an interrupt is the epoch deadline (FAULT_TIME); any other
75 * trap FAULT_TRAP | (wasmtime's trap code + 1) << 8. */
76uint32_t mesh_wasm_trap_fault(int trap);
77
78#endif