==> include/mesh/manifest.h <==1/* @ajax/mesh-manifest: `program.toml`, a program's manifest (mesh-host
2 * manifest.rs; docs/plan-program-loading.md §3.3). A hand-rolled
3 * `key = value` format (mesh-toml): unknown and repeated keys are refused.
4 * `abi` is parsed but checked by the loader (its refusal reason is `abi`).
5 * Every refusal message is the Rust's, byte for byte. */
6#ifndef MESH_MANIFEST_H
7#define MESH_MANIFEST_H
8
9#include "mesh/needs.h"
10#include "mesh/text.h"
11
12#include "mesh/abi/control_block.h"
13
14#include <stdbool.h>
15#include <stddef.h>
16#include <stdint.h>
17
18typedef struct {
19 char *name;
20 uint32_t ty; /* FT_* */
21 uint32_t off;
22} mesh_manifest_field;
23
24/* The request window, view offsets: requests at req_off (req_max bytes), responses at resp_off. */
25typedef struct {
26 uint32_t req_off, req_max, resp_off, resp_max;
27} mesh_manifest_window;
28
29/* A view region (offset, bytes). */
30typedef struct {
31 uint32_t off, len;
32} mesh_manifest_region;
33
34/* The manifest's placement declaration (mesh-abi "placement"): which view
35 * regions meshd moves between the machines of a cluster. */
36typedef struct {
37 uint32_t cap; /* PLACE_CAP_PIN / PLACE_CAP_SPLIT */
38 mesh_manifest_region *state; /* the shared state, each 4-aligned */
39 size_t nstate;
40 uint32_t frame; /* the u32 frame number's view offset (inside a state region) */
41 mesh_manifest_region *out; /* part b (task arg b) is the b-th of fanout equal pieces of each */
42 size_t nout;
43 uint32_t show; /* the show region's view offset (SH_*) */
44 uint32_t fanout;
45} mesh_manifest_place;
46
47size_t mesh_manifest_place_state_bytes(const mesh_manifest_place *p);
48uint32_t mesh_manifest_place_out_bytes(const mesh_manifest_place *p);
49/* Part b's (view offset, bytes) in each output region: out[0..nout). */
50void mesh_manifest_place_part(const mesh_manifest_place *p, uint32_t b, mesh_manifest_region *out);
51/* Part b's (offset, bytes) pieces within a show buffer (the regions concatenated). */
52void mesh_manifest_place_part_in_buffer(const mesh_manifest_place *p, uint32_t b, mesh_manifest_region *out);
53size_t mesh_manifest_place_part_bytes(const mesh_manifest_place *p);
54/* Place::mask(lo..hi): bits lo..hi-1. */
55uint32_t mesh_manifest_place_mask(uint32_t lo, uint32_t hi);
56
57/* A consumer's inbox (mesh-abi pipe). */
58typedef struct {
59 uint32_t off, cap, rec;
60 char *ty;
61} mesh_manifest_inbox;
62
63/* `feeds = ["consumer:type", ..]`. */
64typedef struct {
65 char *consumer;
66 char *ty;
67} mesh_manifest_feed;
68
69typedef struct mesh_manifest {
70 char *name;
71 uint32_t abi;
72 uint32_t view_bytes;
73 uint32_t view_abi;
74 uint32_t snap_bytes;
75 uint32_t nodes;
76 /* `nodes = "fit"`: decided at load on each machine (PT_NODES has the number). */
77 bool nodes_fit;
78 /* `warps` (1..=MAX_WARPS, default 1): a node is a block of 32 x warps threads on a GPU. */
79 uint32_t warps;
80 /* `shared_bytes`: the program's shared memory per node, after RT_SHARED_BYTES. */
81 uint32_t shared_bytes;
82 /* `scratch_bytes`: the program's own device memory on a GPU, zeroed at load. */
83 uint32_t scratch_bytes;
84 uint32_t sms;
85 uint32_t policy; /* POLICY_* */
86 uint32_t hz;
87 uint32_t fanout;
88 /* in_flight = "batch" (default): publish the next batch only once the previous one completed. */
89 bool batch;
90 uint32_t arg_mode; /* ARG_* */
91 uint32_t arg_off;
92 /* Program names, or ["*"] (http only). */
93 char **reads;
94 size_t nreads;
95 /* The input queue (view offset, data bytes), 0/0 = none. */
96 uint32_t input_off;
97 uint32_t input_len;
98 bool has_request;
99 mesh_manifest_window request;
100 uint32_t peer; /* PEER_MODE_* */
101 char *counters[MESH_COUNTERS];
102 mesh_manifest_field *fields;
103 size_t nfields;
104 bool autostart;
105 /* `place`: NULL unless the program may be placed (pin / split). */
106 mesh_manifest_place *place;
107 /* `backends` (default ["cuda"]). */
108 char **backends;
109 size_t nbackends;
110 /* `param`: a u32 the program reads (PX_PARAM); part of the image's identity. */
111 uint32_t param;
112 /* `float`: "ftz" (default) or "ieee" (wasm only). */
113 bool ftz;
114 /* `mem_mb`: wasm: each lane's linear-memory cap in MiB, default 64; native: MemoryMax, 0 = none. */
115 uint32_t mem_mb;
116 /* `task_ms` (wasm): a task's time budget, default 50. */
117 uint32_t task_ms;
118 /* Native workers only: `cpu` as a percent of one core, `mem_mb` in bytes, `nice`, `background`. */
119 uint32_t cpu_pct;
120 uint64_t mem;
121 uint32_t nice;
122 bool background;
123 /* Native only: `device = "gpu"`. */
124 bool device_gpu;
125 /* `inbox = "off:cap:rec"`, `inbox_type`: NULL when none. */
126 mesh_manifest_inbox *inbox;
127 /* `feeds = ["consumer:type", ..]`. */
128 mesh_manifest_feed *feeds;
129 size_t nfeeds;
130 /* The fleet scheduler's keys. */
131 mesh_needs needs;
132 /* `job_base = <off>` (policy "job"). */
133 bool has_job_base;
134 uint32_t job_base;
135 /* `job_out = "off:rec"` (policy "job"). */
136 bool has_job_out;
137 uint32_t job_out_off, job_out_rec;
138 /* `job_payload = "off:len"` (policy "job"). */
139 bool has_job_payload;
140 uint32_t job_payload_off, job_payload_len;
141} mesh_manifest;
142
143/* A job item's result record past its u32 (`job_out`), at most. */
144#define MESH_JOB_OUT_MAX 256u
145
146/* Parses manifest text. False with *err, e.g. "line 3: unknown key \"bogus\"". */
147bool mesh_manifest_parse(const char *text, size_t n, mesh_manifest *out, char **err);
148/* A program dir (or its program.toml): the manifest and its `<name>.ptx`
149 * path (*ptx, malloc'd). Errors are "<path>: <why>". */
150bool mesh_manifest_load(const char *path, mesh_manifest *out, char **ptx, char **err);
151void mesh_manifest_free(mesh_manifest *m);
152void mesh_manifest_copy(mesh_manifest *dst, const mesh_manifest *src);
153
154/* Threads per node on a GPU (32 x warps). */
155uint32_t mesh_manifest_threads(const mesh_manifest *m);
156/* The dynamic shared memory a node's launch gets: the runtime's area and the program's. */
157uint32_t mesh_manifest_smem(const mesh_manifest *m);
158/* A native worker program (`backends = ["native"]`). */
159bool mesh_manifest_native(const mesh_manifest *m);
160
161/* Rust's derived `{:?}` of the Manifest (golden tests compare it with the Rust's). */
162void mesh_manifest_debug(mesh_text *t, const mesh_manifest *m);
163
164#endif