1/* @ajax/mesh-rt-sim-mailbox: a mailbox in host memory, a program slot in it, and the host side
2 * of the ticket ring, for running mesh programs on @ajax/mesh-rt-sim in tests.
3 *
4 * It does what meshd does for one slot, minimally and by the contract: the
5 * header (magic, version, one system), the program table entry (written under
6 * its PT_GEN seqlock), the extension (param, scratch), publication of tickets
7 * (entry, then E_SEQ released, as meshd's publisher), completion by the marks,
8 * the request window and the input queue, and a halt (P_SHUTDOWN, then the ring
9 * rewound for a relaunch). Not a meshd: no policies, no blink, no snapshot. */
10#ifndef MESH_RT_SIM_MAILBOX_H
11#define MESH_RT_SIM_MAILBOX_H
12
13#if !defined(__NVPTX__)
14
15#include <stdbool.h>
16#include <stddef.h>
17#include <stdint.h>
18
19#include "mesh/rt/sim.h"
20
21typedef struct {
22    const char *name;      /* [a-z0-9-]{1,15} */
23    uint32_t view_off;     /* mailbox offset of the view; 0: VIEW_HEAP */
24    uint32_t view_bytes;
25    uint32_t nodes;        /* 0: 1 */
26    uint32_t warps;        /* 0: 1 */
27    uint32_t shared_bytes; /* the program's own, after RT_SHARED_BYTES */
28    uint32_t reads_mask;
29    uint32_t peer_mode;
30    uint32_t input_off, input_len;
31    uint32_t req_off, req_max;
32    uint32_t resp_off, resp_max;
33    uint32_t param;
34    uint8_t *scratch; /* device memory of its own (host memory here) */
35    uint32_t scratch_bytes;
36} mesh_sim_prog;
37
38/* A zeroed MAILBOX_BYTES mailbox (4 KiB aligned) with the header of a single
39 * system: magic, version, H_PEER = PEER_NONE, H_SYSTEMS = 1, H_SMS = 1. NULL
40 * when out of memory. */
41uint8_t *mesh_sim_mailbox(void);
42void mesh_sim_mailbox_free(uint8_t *mb);
43/* Writes slot's table entry (state RUNNING) and extension; returns the view's address. */
44uint8_t *mesh_sim_install(uint8_t *mb, uint32_t slot, const mesh_sim_prog *p);
45/* Changes the slot's table state (e.g. EMPTY to unload it), under its seqlock. */
46void mesh_sim_set_state(uint8_t *mb, uint32_t slot, uint32_t state);
47/* Launches the slot's kernel with the program's nodes, warps and shared bytes. */
48mesh_sim_launch *mesh_sim_launch_prog(uint8_t *mb, uint32_t slot, const mesh_sim_prog *p, mesh_sim_kernel kernel);
49/* Publishes one ticket (op, arg) and returns it; it waits while 64 are in flight. */
50uint32_t mesh_sim_publish(uint8_t *mb, uint32_t slot, uint32_t op, uint32_t arg);
51/* Waits for ticket t's completion: true with its result, false after timeout_ms. */
52bool mesh_sim_wait(uint8_t *mb, uint32_t slot, uint32_t t, uint32_t *result, uint32_t timeout_ms);
53/* publish + wait (60 s); aborts the test on a timeout (a hung node). */
54uint32_t mesh_sim_call(uint8_t *mb, uint32_t slot, uint32_t op, uint32_t arg);
55/* A byte request (OP_REQ): the request into the window, P_REQ_LEN, P_REQ_SEQ + 1,
56 * then the task; the response bytes (up to cap) into out. Returns the task's
57 * result; *out_len the response length (P_RESP_LEN), or UINT32_MAX when the
58 * program did not respond (P_RESP_SEQ != P_REQ_SEQ). */
59uint32_t mesh_sim_request(uint8_t *mb, uint32_t slot, const void *req, uint32_t len, void *out, uint32_t cap, uint32_t *out_len);
60/* Appends bytes to the slot's input queue (false when it lacks room). */
61bool mesh_sim_input(uint8_t *mb, uint32_t slot, const void *bytes, uint32_t n);
62/* Halts the launch at a task boundary (P_SHUTDOWN), joins it, and rewinds the
63 * ring as meshd does (P_RING_HEAD = the tail, P_ONLINE = P_HALTED = 0,
64 * P_SHUTDOWN = 0), so the slot can be launched again. */
65void mesh_sim_halt(uint8_t *mb, uint32_t slot, mesh_sim_launch *l);
66/* Gives slot an inbox (pipes, as the manifest's `inbox = "off:cap:rec"` and
67 * `inbox_type`): cap records of rec bytes at view offset off. */
68void mesh_sim_inbox(uint8_t *mb, uint32_t slot, uint32_t off, uint32_t cap, uint32_t rec, const char *type);
69/* Connects producer -> consumer (the producer's `feeds`). */
70void mesh_sim_feed(uint8_t *mb, uint32_t producer, uint32_t consumer);
71/* The slot's control block (P_* fields) and view. */
72uint8_t *mesh_sim_ctl(uint8_t *mb, uint32_t slot);
73uint8_t *mesh_sim_view(uint8_t *mb, uint32_t slot);
74/* Reads and writes of mailbox words (host side, little-endian, atomic where it matters). */
75uint32_t mesh_sim_u32(const uint8_t *p);
76uint64_t mesh_sim_u64(const uint8_t *p);
77float mesh_sim_f32(const uint8_t *p);
78void mesh_sim_set_u32(uint8_t *p, uint32_t v);
79void mesh_sim_set_u64(uint8_t *p, uint64_t v);
80void mesh_sim_set_f32(uint8_t *p, float v);
81
82#endif /* !__NVPTX__ */
83#endif