1/* @ajax/mesh-abi-native: The native worker contract: its ABI, environment and file descriptors.
2 *
3 * Part of alpha-c-mesh, a C port of alpha-rust-mesh (README.md says from where). */
4#ifndef MESH_ABI_NATIVE_H
5#define MESH_ABI_NATIVE_H
6
7#include <stdbool.h>
8#include <stddef.h>
9#include <stdint.h>
10
11/* ---------------------------------------------------------------- native workers */
12/* A program whose manifest says `backends = ["native"]` is an executable,
13 * built per target into the catalog at `<dir>/<target triple>/<name>`, that
14 * links the `mesh-worker` SDK.  meshd runs it as a *worker process* beside
15 * its GPU backend (CUDA or Metal): the process maps meshd's mailbox (a
16 * shared-memory file: a memfd on Linux, shm_open on macOS, also the GPU's
17 * mailbox) and consumes its slot's ring exactly as mesh-rt's nodes do --
18 * tickets, E_SEQ, P_RESULTS/P_MARKS (release), P_DONE, node records, trace,
19 * P_ONLINE/P_HALTED -- with one thread per node.  So the publisher, control,
20 * snapshots, replication and placement treat it like any program.
21 *
22 * The process gets (environment and inherited descriptors):
23 * NATIVE_ENV_ABI = NATIVE_ABI, NATIVE_ENV_NAME = the program's name,
24 * fd NATIVE_STATUS_FD: a pipe to meshd, fd NATIVE_MAILBOX_FD: the mailbox
25 * (MAILBOX_BYTES, map it MAP_SHARED), stdin: meshd's commands,
26 * stdout/stderr: the program's log (meshd's `log` and `<logs>/<name>.log`).
27 * Lines, worker -> meshd (status fd): `ready <NATIVE_ABI>` once it is set up
28 * (the program's own setup before `mesh_worker::run` included), then
29 * `halted <gen>` after each launch's nodes all halted.
30 * Lines, meshd -> worker (stdin): `run <gen> <slot>`: start the slot's
31 * PT_NODES nodes (each P_ONLINE += 1; the entry is read at that moment);
32 * `exit`: leave.  EOF on stdin (meshd gone, however it died) stops the nodes
33 * and exits.  P_SHUTDOWN = SHUTDOWN_HALT: the nodes halt and the process
34 * waits for the next `run` (a blink, an upgrade's retained image: rollback
35 * and relaunch need no new process); SHUTDOWN_EXIT: they halt and it exits.
36 * Native nodes ignore H_BLINK: a CUDA whole-context blink never includes a
37 * native slot (it changes no module of theirs). */
38#define MESH_NATIVE_ABI 1u
39#define MESH_NATIVE_ENV_ABI "MESH_NATIVE_ABI"
40#define MESH_NATIVE_ENV_NAME "MESH_PROGRAM"
41#define MESH_NATIVE_STATUS_FD 3
42#define MESH_NATIVE_MAILBOX_FD 4
43
44#endif