1/* @ajax/mesh-abi-control-protocol: meshd's control port and HTTP port, and the reasons a load can fail.
2 *
3 * Part of alpha-c-mesh, a C port of alpha-rust-mesh (README.md says from where). */
4#ifndef MESH_ABI_CONTROL_PROTOCOL_H
5#define MESH_ABI_CONTROL_PROTOCOL_H
67#include <stdbool.h>
8#include <stddef.h>
9#include <stdint.h>
1011/* meshd's control port (127.0.0.1), HTTP port (8088: 8080 is held by other
12 * services on both DGX machines) and peer link port. */
13#define MESH_CONTROL_PORT 7700
14#define MESH_HTTP_PORT 8088
15/* ---------------------------------------------------------------- control protocol v2 */
16/* meshd's control port (CONTROL_PORT): one text line per request; replies are
17 * one line (`ok ...` / `err <reason>`) unless marked *framed* (u32 LE length,
18 * then that many bytes). `<name>` is a loaded program's name.
19 * snap -> framed: snapshot v2 (below)
20 * programs -> framed text, one line per non-empty slot:
21 * `slot name state nodes sms policy tasks/s ptx_hash regs view_off+view_bytes`
22 * then `fields <name> <field>...` and `counters <name> <c0>..<c3>` lines
23 * catalog -> framed text: the program dirs under --programs DIR, one per line
24 * load <dir|program.toml> -> ok slot <s> blink <us> | err <reason>
25 * reasons: manifest: .. | abi | name exists | no slot | view heap |
26 * occupancy | regs | jit: <log> | load: <cuda err>; paths are
27 * confined to --programs DIR
28 * upgrade <name> [dir] -> ok blink <us> view kept|reset
29 * rollback <name> -> ok blink <us>
30 * unload <name> [--now] -> ok (module and view freed at the next blink)
31 * start <name> / stop <name> -> ok (zero gap: no module change)
32 * task <name> <op> <arg> -> ok <result>
33 * req <name> <len>\n<bytes> -> framed bytes (the request window; OP_REQ)
34 * input <name> <bytes> -> ok (appends to the input queue)
35 * reset <name> -> ok (stop, zero the view, OP_INIT, restore run state)
36 * peek <name> <off> <len> -> framed bytes (read-only view access)
37 * log [n] -> framed text (the last n meshd log lines)
38 * trace -> framed: per non-empty slot, u32 slot, u32 P_TRACE_N, then its
39 * TRACE_PER_PROG x TRACE_BYTES records verbatim
40 * place <name> -> ok <mode> role <role> system <k> paused <b> shown <n> lat_n <n>
41 * lat_sum_us <n> lat_max_us <us> ignored <n> uptime_ms <ms>
42 * place <name> local|pin <k>|split [spec] -> ok version <v> ... (a fleet change; "placement" above)
43 * fleet -> framed text: the leader, term, version committed / accepted /
44 * applied, the up and suspect members, each member's reconcile
45 * status, the desired state's programs, groups, places
46 * groups -> framed text: each lockstep group, its epoch, members, state and
47 * every member's data-plane state
48 * group <name> reform | group <name> on_loss pause|reform [<ms>] -> ok version <v> ...
49 * leader -> ok system <k> term <t> | err peer: no leader ...
50 * cluster -> framed text: `cluster <N> system <k> state <up|no-leader> leader <k>
51 * up <mask> linked <mask>`, then per member `member <k> <absent|linked|up|suspect> rtt_us <f>
52 * wait_us <f> rounds <n> round <n> cc <c> sms <n>/<total>
53 * blocks_per_sm <n> arch <a> load_age_ms <ms|-> gpu_share <f|-> cpu <f>
54 * psi_cpu <f> psi_mem <f> meshd_cpu <f> mem_avail_mb <n> gpu <name...>`
55 * load -> framed text: this machine's load (S_LOAD..), `key value` lines:
56 * gpu, cpu, cores (per core), memory, meshd, disk, then one
57 * `program <name> ...` line per loaded program (PL_*)
58 * Sugar: `http <path>` = a GET through `req http`, `key <k>` = input doom <k>,
59 * `train-reset` = reset train. In a fleet, load/upgrade/rollback/unload/start/
60 * stop/reset/place, `group ...` and the lockstep program's task change the
61 * desired state: forwarded to the leader (F_CTL), committed on a majority,
62 * reconciled by every member, answered `ok version <v> peer ok: <what>
63 * (system 0 ok: ..; system 3 absent: reconcile on join)` / `err ... peer err (..)`;
64 * without a leader `err peer: no leader ...`. The lockstep program's
65 * upgrade/rollback/task are cycles of its group's epoch, its reset a new epoch.
66 * `unsupported`: the manifest's `backends` does not list this meshd's
67 * backend (a member reports it and is not a failure; a lockstep group is
68 * formed of the members that can run it).
69 * `float`: a wasm image whose manifest declares the cluster float mode
70 * (`float = "ftz"`, the default; required by `peer = "lockstep"`) has f32
71 * arithmetic outside the runtime's FTZ helpers, SIMD, threads or relaxed-SIMD
72 * opcodes (mesh-host wasm.rs `float_check`). `exec`: an upgrade or rollback
73 * would move the slot to another executor (cuda/metal <-> wasm). */
74#define MESH_LOAD_REASONS_LEN 13
75extern const char *const MESH_LOAD_REASONS[13];
7677#endif