1/* @ajax/mesh-abi-host-load: This machine's load (S_LOAD..): GPU share, CPU, PSI, memory, meshd, disk, thermal, cores.
2 *
3 * Part of alpha-c-mesh, a C port of alpha-rust-mesh (README.md says from where). */
4#ifndef MESH_ABI_HOST_LOAD_H
5#define MESH_ABI_HOST_LOAD_H
67#include <stdbool.h>
8#include <stddef.h>
9#include <stdint.h>
1011/* ---------------------------------------------------------------- load (snapshot v3) */
12/* Live load, sampled by meshd about once a second (timed by S_LOAD_AT_MS): */
13/* how much GPU its work obtained (from the node load records NL_*), the */
14/* host's CPU, memory and disk pressure, meshd's own cost, every member's */
15/* summary (F_LOADREP), and per program the GPU share, task latency and */
16/* throughput the scheduler will use. 0x1000..0x2800, mirrored into the */
17/* mailbox's LOAD_PAGE. Rates and fractions are f32 over the last sample */
18/* interval ("1 s") or the last LOAD_WINDOW samples ("10 s"). A value whose */
19/* LF_* flag is clear was not measured (not 0). */
20/* 0x1000..0x1100 this machine (S_LOAD_*, S_GPU_*, S_CPU_*, S_PSI_*, S_MEM_*, S_MESHD_*, ...) */
21/* 0x1100..0x1200 per logical CPU: utilisation and core class (S_CORE_UTIL, S_CORE_CLASS) */
22/* 0x1200..0x1400 per member: its F_LOADREP summary (ML_*) */
23/* 0x1400..0x1800 the fleet: leader, term, versions, the view, per-member reconcile, the group (S_FLEET..) */
24/* 0x1800..0x2800 per program slot: PL_* (0x00..0x40 GPU and task stats; 0x40..0x80 */
25/* PL_HOST: reserved for the CPU executors' per-program CPU time and RSS) */
26/* 0x2800..0x3000 reserved */
27#define MESH_S_LOAD 0x1000
28/* The end of the mirrored load regions (S_LOAD..S_LOAD_END -> LOAD_PAGE). */
29#define MESH_S_LOAD_END 0x2800
30/* Samples the "10 s" figures span. */
31#define MESH_LOAD_WINDOW 10
32#define MESH_S_LOAD_AT_MS 0x1000 /* u64 uptime ms of the last sample (0: none yet) */
33#define MESH_S_LOAD_SAMPLES 0x1008 /* u32 samples taken */
34#define MESH_S_LOAD_FLAGS 0x100c /* u32 LF_*: what this machine measures */
35/* f32 the fraction of wall time meshd's GPU work could run (1 - lost / observed
36 * over every node of every program, NL_*), last second and last LOAD_WINDOW. */
37#define MESH_S_GPU_SHARE 0x1010
38#define MESH_S_GPU_SHARE10 0x1014
39/* f32 (10 s): the mean run on the GPU between two gaps (the time slice we get), us. */
40#define MESH_S_GPU_SLICE_US 0x1018
41/* f32 (10 s): the mean gap, us (CUDA: a time slice someone else got; Metal: per command buffer). */
42#define MESH_S_GPU_GAP_US 0x101c
43/* f32 the longest gap of the last window (1 s), us: the worst stall a task saw. */
44#define MESH_S_GPU_MAX_GAP_US 0x1020
45#define MESH_S_GPU_GAPS_S 0x1024 /* f32 gaps per second (1 s) */
46/* f32 node-seconds observed per second (1 s): the evidence behind the share
47 * (0: no idle node, no lease command buffer: nothing observed, LF_GPU clear). */
48#define MESH_S_GPU_OBS 0x1028
49/* f32 the OS's own device utilisation, 0..1 (Metal: IORegistry AGXAccelerator
50 * "Device Utilization %"; LF_GPU_EXT). Informational: busy is not ours. */
51#define MESH_S_GPU_UTIL_EXT 0x102c
52#define MESH_S_GPU_QUEUE_US 0x1030 /* f32 (10 s) Metal: mean commit -> GPU start per command buffer */
53/* f32 (10 s): wall time per unit of GPU time our work got (1 / share): the latency inflation. */
54#define MESH_S_GPU_INFLATE 0x1034
55/* f32 0..1 (1 s): busy fraction of every logical CPU, and of the big and little classes. */
56#define MESH_S_CPU_UTIL 0x1038
57#define MESH_S_CPU_BIG 0x103c
58#define MESH_S_CPU_LITTLE 0x1040
59#define MESH_S_CPU_IOWAIT 0x1044 /* f32 0..1 (1 s) Linux iowait */
60#define MESH_S_LOADAVG 0x1048 /* f32 x 3: 1, 5, 15 minutes */
61#define MESH_S_CPUS 0x1054 /* u32 logical CPUs sampled (<= MAX_CPUS) */
62#define MESH_S_CPUS_BIG 0x1058 /* u32 */
63#define MESH_S_CPUS_LITTLE 0x105c /* u32 (0: one core class) */
64/* f32 0..1: Linux PSI, the share of the last interval some (full) task
65 * stalled on CPU, memory, IO, from the `total` counters; and the kernel's
66 * avg10 (LF_PSI). */
67#define MESH_S_PSI_CPU 0x1060
68#define MESH_S_PSI_MEM 0x1064
69#define MESH_S_PSI_MEM_FULL 0x1068
70#define MESH_S_PSI_IO 0x106c
71#define MESH_S_PSI_IO_FULL 0x1070
72#define MESH_S_PSI_CPU10 0x1074
73#define MESH_S_PSI_MEM10 0x1078
74#define MESH_S_PSI_IO10 0x107c
75#define MESH_S_MEM_TOTAL_MB 0x1080 /* u32 */
76/* u32 Linux MemAvailable; macOS free + inactive + speculative pages. */
77#define MESH_S_MEM_AVAIL_MB 0x1084
78#define MESH_S_SWAP_TOTAL_MB 0x1088 /* u32 */
79#define MESH_S_SWAP_USED_MB 0x108c /* u32 */
80#define MESH_S_MEM_COMPRESSED_MB 0x1090 /* u32 macOS: the compressor's pages */
81/* u32 macOS kern.memorystatus_vm_pressure_level: 1 normal, 2 warn, 4 critical (LF_MEM_LEVEL). */
82#define MESH_S_MEM_LEVEL 0x1094
83/* f32 0..1 memory free: macOS kern.memorystatus_level (memory_pressure's
84 * "free percentage"); Linux MemAvailable / MemTotal. */
85#define MESH_S_MEM_FREE 0x1098
86#define MESH_S_SWAP_OUT_S 0x109c /* f32 pages swapped out per second (1 s) */
87/* f32 meshd's CPU seconds per second (1.27: 127 %; its lease lanes included). */
88#define MESH_S_MESHD_CPU 0x10a0
89#define MESH_S_MESHD_RSS_MB 0x10a4 /* f32 */
90#define MESH_S_MESHD_THREADS 0x10a8 /* u32 */
91/* u32 free and total MB of the file system holding --programs (the catalog). */
92#define MESH_S_DISK_FREE_MB 0x10ac
93#define MESH_S_DISK_TOTAL_MB 0x10b0
94/* u32 macOS NSProcessInfo.thermalState: 0 nominal, 1 fair, 2 serious, 3 critical (LF_THERMAL). */
95#define MESH_S_THERMAL 0x10b4
96#define MESH_S_TEMP_C 0x10b8 /* f32 Linux: the hottest thermal zone (LF_TEMP) */
97#define MESH_S_SAMPLE_US 0x10bc /* u32 the last sample's own cost, us */
98/* The CPU executors, machine-wide (the sums of PL_HOST over the slots, and the native workers' counts): */
99#define MESH_S_EXEC_CPU 0x10c0 /* f32 (1 s) CPU seconds per second of every wasm lane and native worker */
100#define MESH_S_WASM_LANES 0x10c4 /* u32 wasm lanes running */
101#define MESH_S_EXEC_RSS 0x10c8 /* u64 their resident bytes */
102#define MESH_S_WORKERS 0x10d0 /* u32 live native worker processes (gated and running) */
103#define MESH_S_WORKER_SPAWNS 0x10d4 /* u32 processes started since meshd started */
104#define MESH_S_WORKER_CRASHES 0x10d8 /* u32 of those, died while running */
105/* u32 meshd's log lines not written to stderr (its bounded queue was full: a
106 * stderr nobody reads; or the write failed). Kept in the `log` request's memory. */
107#define MESH_S_LOG_DROPPED 0x10dc
108#define MESH_THERMAL_STATES_LEN 4
109extern const char *const MESH_THERMAL_STATES[4];
110#define MESH_LF_GPU 1u /* S_GPU_SHARE* observed (some node idled / some command buffer ran) */
111#define MESH_LF_PSI 2u /* S_PSI_* */
112#define MESH_LF_CLASSES 4u /* big/little core classes known */
113#define MESH_LF_GPU_EXT 8u /* S_GPU_UTIL_EXT */
114#define MESH_LF_THERMAL 0x10u
115#define MESH_LF_TEMP 0x20u
116#define MESH_LF_MEM_LEVEL 0x40u
117/* Per logical CPU i < S_CPUS: u8 busy percent (1 s) at S_CORE_UTIL + i, u8 CORE_* at S_CORE_CLASS + i. */
118#define MESH_MAX_CPUS 128
119#define MESH_S_CORE_UTIL 0x1100
120#define MESH_S_CORE_CLASS 0x1180
121#define MESH_CORE_UNKNOWN 0
122#define MESH_CORE_BIG 1
123#define MESH_CORE_LITTLE 2
124125/* The Rust const asserts that only involve this package. */
126_Static_assert(MESH_S_LOAD_AT_MS == MESH_S_LOAD, "S_LOAD_AT_MS == S_LOAD");
127_Static_assert(MESH_S_SAMPLE_US + 4 <= MESH_S_EXEC_CPU, "S_SAMPLE_US + 4 <= S_EXEC_CPU");
128_Static_assert(MESH_S_LOG_DROPPED + 4 <= MESH_S_CORE_UTIL, "S_LOG_DROPPED + 4 <= S_CORE_UTIL");
129_Static_assert((MESH_S_EXEC_RSS % 8 == 0), "S_EXEC_RSS.is_multiple_of(8)");
130_Static_assert(MESH_S_CORE_UTIL + MESH_MAX_CPUS <= MESH_S_CORE_CLASS, "S_CORE_UTIL + MAX_CPUS <= S_CORE_CLASS");
131_Static_assert(MESH_LOAD_WINDOW >= 2, "LOAD_WINDOW >= 2");
132133#endif