/* StarForth — Steady-State Virtual Machine Runtime Copyright (c) 2023–2025 Robert A. James All rights reserved. This file is part of the StarForth project. Licensed under the StarForth License, Version 1.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: https://github.com/star.4th@proton.me/StarForth/LICENSE.txt This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. See the License for the specific language governing permissions and limitations under the License. */ /** * kernel_hermes.h - Kernel-resident Hermes: message and membership * structures (FABRIC-3.6.md task 2.1, item 28; design: FABRIC-3.5.md * SIII/SXXXIII/SXXXIV). * * Phase 2, task 2.1 ONLY: type definitions, wired to nothing, drawing no * heat. No allocator, no send/deliver/reap logic, no registration * anywhere -- those are tasks 2.2 onward, each its own commit. This file * existing and compiling changes no VM's dictionary and no runtime * behaviour; that is deliberate (FABRIC-3.5.md SXXII.4: Phase 2 structures * come first and prove nothing until the allocator is built on top, SXL.4 * item 41). * * SkHermesMessage mirrors capsules/common/messaging.4th's live MSG-CELLS * layout (9 cells: MSG-TYPE@/FROM@/TO@/PADDR@/PLEN@/STADIUM-CELL@/SEQ@/ * CH@/ORIG-TYPE@) field-for-field, per FABRIC-3.5.md SXXXIII.4 item 1 -- * "roughly half the file is accessors that become struct fields." The * Stadium-cell field is the heat coupling itself: a message's heat is not * a field of its own, it IS the Stadium cell it occupies (SXL.4's * consumption model, SXXXIX.4's per-VM invariant) -- there is deliberately * no separate heat field here to keep that single-source-of-truth. * * SkHermesMembership is the "one broadcast membership list" SXXXIII.4 * item 3 and SXXXIII.5 recommend in place of messaging.4th's 28-word * channel abstraction (CH-REQUEST/ACCEPT/CONFIRM/CLOSE/MINT-ID and the * CH-NEGOTIATING/OPEN/CLOSING state machine) -- traced to have exactly one * live caller, CH-ADD-MBR, everything else channel-shaped is unexercised. * Whether kernel-Hermes ever adds negotiation on top is item 27, an open * Phase 3 ruling (FABRIC-3.6.md B1) -- this structure does not answer * that question, it only holds a flat list, which is correct either way. */ #ifndef STARKERNEL_VM_KERNEL_HERMES_H #define STARKERNEL_VM_KERNEL_HERMES_H #ifdef __STARKERNEL__ #include #include #include "starkernel/vm_uuid.h" /* VMUuid */ #include "starkernel/q48_16.h" /* Q48_ONE */ /* * SK_HERMES_MSG_MAX / SK_HERMES_MEMBER_MAX - sizing. Mirrors * messaging.4th's own MSG-MAX (32) and MBR-MAX (64) as a starting point -- * kernel-Hermes is a single central pool rather than N per-VM arenas, so * these may need revisiting once real traffic exists to size against. Not * a ruling, just where the FORTH precedent already was. */ #define SK_HERMES_MSG_MAX 32 #define SK_HERMES_MEMBER_MAX 64 /* * SK_HERMES_Q_SLOT - per-message admission heat, task 2.2 (item 28). * messaging.4th:44-46 derives Q.SLOT as the reservoir remaining after * COMMON-CH's own Q.1/3 floor, split across MSG-MAX + (CH-MAX-1) slots -- * a floor that exists to reserve heat for the one live channel object * itself. Kernel-Hermes has no such object: SXXXIII.4 item 3 and * SXXXIII.5 replace the channel abstraction with a flat membership list * that carries no Stadium heat of its own, so there is nothing left for a * floor to protect. Deliberately simpler here rather than carrying the * old formula's now-unmotivated term forward: reservoir split evenly * across message slots only. */ #define SK_HERMES_Q_SLOT ((uint64_t)Q48_ONE / SK_HERMES_MSG_MAX) /* * SkHermesMessage - one message slot, field-for-field mirror of * messaging.4th's 9-cell MSG layout. * * @field type Message type code (SPAWN/PAUSE/RESUME/KILL-style * codes are Category A/dead per task 0.1/0.4; live * types today are CONSOLE-CMD-EVENT(7), * ELEVATE-REQUEST(8), BLK-ATTACH-EVENT(9), messaging.4th * reserved sentinels MSG-NACKED(253)/MSG-DELIVERED(255)). * @field from Sending VM (mirrors MSG-FROM@). * @field to Target VM (mirrors MSG-TO@). * @field payload_addr Out-of-line payload address (mirrors MSG-PADDR@). * FABRIC-3.5.md SXLIII.6.1 (item 44, still open): a * payload above INPUT_BUFFER_SIZE-1 (1024) bytes cannot * be drained in one interpret call -- bound or chunk it * before Phase 3, not here. * @field payload_len Payload length in bytes (mirrors MSG-PLEN@). * @field stadium_cell Index into the Stadium cell array this message's * heat currently occupies, or a sentinel meaning "none" * (mirrors MSG-STADIUM-CELL@) -- the heat coupling * itself; see this file's own top comment. * @field seq Monotonic send sequence (mirrors MSG-SEQ@). * @field channel Broadcast/channel marker; unused today (mirrors * MSG-CH@) -- item 27 territory, not decided here. * @field orig_type Original type before a NACK/redeliver rewrite * (mirrors MSG-ORIG-TYPE@). * @field in_use Free-list occupancy flag for task 2.2's allocator. * Not present in the FORTH layout (which uses * MSG-TYPE@ 0<> as its own live/free test) -- kept * explicit here rather than overloading `type == 0`, * since kernel-Hermes's held/pulled/returned/consumed * ledger (task 2.4, SXL.4) needs an unambiguous * occupancy bit independent of the type field's value. */ typedef struct { uint32_t type; VMUuid from; VMUuid to; void *payload_addr; uint32_t payload_len; int32_t stadium_cell; uint32_t seq; uint32_t channel; uint32_t orig_type; int in_use; } SkHermesMessage; /* * SkHermesMembership - one flat broadcast membership list: every VM that * has joined, no per-member state beyond identity. Replaces the 28-word * channel abstraction; see this file's own top comment for why. * * @field members Member VM identities, valid for indices < count. * @field count Number of valid entries in members[]. */ typedef struct { VMUuid members[SK_HERMES_MEMBER_MAX]; size_t count; } SkHermesMembership; /* * sk_hermes_alloc - Heat-coupled allocate (task 2.2, item 28): pull * SK_HERMES_Q_SLOT from vm_id's own Stadium reservoir, admit a real * Stadium-floor patron with that heat (behaviour DELIVER, matching * messaging.4th's own `SB-DELIVER STADIUM-ADMIT`), and claim a free * message slot recording the admitted cell. Refuses cleanly, rolling * back anything already pulled/admitted, if reservoir, arena, or the * Stadium floor itself refuses. * * CORRECTED in task 2.3 (see this file's .c counterpart's own top * comment): the first cut of this function never admitted a real * Stadium patron, which left held message heat invisible to SXL.4's * conservation invariant while allocated. It now does, which is what * makes sk_hermes_release()'s eviction meaningful. * * Wired to nothing outside this file's own self-test (kernel_main.c) as * of task 2.2/2.3 -- no FORTH word, no capsule interaction, no protocol * logic (send/deliver/reap are later tasks). Exercised only by a * synthetic-VM self-test; does not change any real VM's dictionary. * * @param vm_id Caller whose reservoir is charged. * @param out_msg On success, set to the claimed slot. Untouched on * refusal. * @return 0 on success, -1 on refusal (insufficient reservoir, no free * slot, or the Stadium floor itself refused admission -- this * function does not distinguish the three in the return value; * all three leave all state exactly as it was). */ int sk_hermes_alloc(VMUuid vm_id, SkHermesMessage **out_msg); /* * sk_hermes_release - Return a message's heat via the Stadium eviction * path (task 2.3, item 28), mirroring MSG-FREE-NODE * ("DUP 5 CELLS + @ STADIUM-EVICT DROP"). stadium_evict() itself returns * the departing patron's remaining heat to its owning VM's reservoir -- * this function does not touch the reservoir directly, matching the * FORTH shape exactly. Clears the slot (in_use = 0) whether or not * eviction succeeds, since a message this function was asked to release * should not remain allocated either way. * * @param msg A slot previously returned by sk_hermes_alloc(). Refused * (returns -1, no effect) if NULL or already released. * @return 0 on successful eviction, -1 if msg was invalid or eviction * itself was refused by the Stadium floor. */ int sk_hermes_release(SkHermesMessage *msg); #endif /* __STARKERNEL__ */ #endif /* STARKERNEL_VM_KERNEL_HERMES_H */