1/* @ajax/mesh-exec-wasm-testkit: wasm guest programs run through the real wasm executor
2 * (@ajax/mesh-exec-wasm) on a test mailbox, with what meshd's driver would otherwise do written out
3 * minimally: a catalog dir with program.toml and <name>.wasm, the program-table entry (name, state,
4 * view in the view heap, nodes, peer mode, reads mask, windows, param), the launch, tickets
5 * published on the slot's ring, and the shutdown. For tests; not meshd. */
6#ifndef MESH_EXEC_WASM_TESTKIT_H
7#define MESH_EXEC_WASM_TESTKIT_H
8
9#include "mesh/backend.h"
10#include "mesh/exec_wasm.h"
11#include "mesh/mailbox.h"
12
13#include <stdbool.h>
14#include <stddef.h>
15#include <stdint.h>
16
17typedef struct {
18    bool used;
19    mesh_kernel *k;
20    mesh_stream *st;
21    char *name;
22    uint32_t nodes;
23    uint32_t next;   /* the next ticket */
24    size_t view;     /* mailbox offset of the view */
25    uint32_t view_bytes;
26} mesh_kit_slot;
27
28typedef struct {
29    mesh_mailbox mb;
30    mesh_backend *b;
31    char root[128]; /* the catalog: a temp dir */
32    size_t heap;    /* the next free view-heap offset */
33    mesh_kit_slot slot[32];
34    char *cache;
35} mesh_kit;
36
37/* A fresh mailbox and executor (cache: --wasm-cache or NULL). */
38bool mesh_kit_open(mesh_kit *kit, const char *cache, char **err);
39void mesh_kit_close(mesh_kit *kit);
40
41/* Prepares (through the executor's compiler: manifest checks, float guard, compile), loads and
42 * launches the program of manifest text and wasm file at slot; nodes = the manifest's. */
43bool mesh_kit_load(mesh_kit *kit, uint32_t slot, const char *manifest, const char *wasm_path, char **err);
44/* As mesh_kit_load with the wasm bytes given. */
45bool mesh_kit_load_bytes(mesh_kit *kit, uint32_t slot, const char *manifest, const uint8_t *wasm, size_t n, char **err);
46/* Sets a slot's reads mask (PT_READS_MASK) under its PT_GEN seqlock. */
47void mesh_kit_reads(mesh_kit *kit, uint32_t slot, uint32_t mask);
48
49/* Connects a pipe: producer may push into consumer's inbox (PP_FEEDS_MASK, PP_FED_MASK). The
50 * consumer's inbox comes from its manifest (`inbox`) at load. */
51void mesh_kit_connect(mesh_kit *kit, uint32_t producer, uint32_t consumer);
52
53/* Publishes (op, arg) and waits for its completion (at most timeout_ms): true with *result; false
54 * on a fault (*fault holds P_FAULT) or a timeout (*fault 0). */
55bool mesh_kit_task(mesh_kit *kit, uint32_t slot, uint32_t op, uint32_t arg, uint32_t *result, uint32_t *fault,
56                   unsigned timeout_ms);
57/* Publishes n tickets of (op, arg) back to back and waits for them all (a throughput run). */
58bool mesh_kit_tasks(mesh_kit *kit, uint32_t slot, uint32_t op, uint32_t arg, uint32_t n, uint32_t *fault, unsigned timeout_ms);
59
60/* OP_REQ: writes req into the slot's request window (P_REQ_LEN, P_REQ_SEQ + 1), runs it, and copies
61 * the response (P_RESP_LEN bytes, at most cap) into out: its length, or -1 on a fault or timeout. */
62long mesh_kit_request(mesh_kit *kit, uint32_t slot, const void *req, uint32_t n, char *out, size_t cap, unsigned timeout_ms);
63
64/* P_SHUTDOWN, waits for the lanes to halt, unloads, clears the slot's entry and control block. */
65void mesh_kit_unload(mesh_kit *kit, uint32_t slot);
66
67/* The built module of a wasm package (its id, e.g. "ajax-mesh-prog-hello-wasm"), found beside the
68 * running test binary: <out>/<profile>/wasm/<id>.wasm, where the test is <out>/<profile>/test/... .
69 * NULL (and a message on stderr) when it isn't built: run `sexc build` first. malloc'd. */
70char *mesh_kit_artifact(const char *id);
71
72/* The slot's view at off. */
73size_t mesh_kit_view(const mesh_kit *kit, uint32_t slot, size_t off);
74
75#endif