admin/LithosAnanake
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

FABRIC-3.8.md Stage FR: VM frame stacks, each frame with an ID

Browse Source 
Captain Bob: "give frames IDs and call by ID" -- frames stack per VM, each
with an ID. New vm_frame.h/.c: VMFrameEntry { VMFrameID id; VMUuid vm_id;
kind (INTERPRET/DRAIN/IDLE) }, a growable VMFrameStack embedded as VM.frames
(reserved at birth, freed in vm_cleanup, grown by allocate-copy-free).
vm_interpret() -> vm_interpret_kind() pushes a frame onto the running stack's
owner, holds only its ID, fails closed if it cannot grow, and pops by ID
(mismatch reported as VM FRAME CORRUPTION).

The Stage A/B loose fields are gone and everything is derived from the stack:
- ownership gate: one frame, and it is vm's own
- drain guard: a DRAIN frame for vm already on the running stack
- parked-idle: an IDLE frame the trampoline pushes around its yield
- log attribution: the top frame's vm_id, resolved by ID through the registry
The single saved-and-restored attribution global is removed.

Evidence: the probe baseline on the pre-frame code read HSSAS (the global
named Hestia while Hera resumed). With frames it reads HSHAS on all three
ISAs, with Hestia's top frame IDLE and Hera's frames back to 0; the probe is
reverted. Formal acceptance on all three ISAs: dict_hash identical and
unchanged, zero UNKNOWN WORD, faults, frame corruption or refused interprets,
and the WIREBIND relay 1 2 + . -> 3 works.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-09-23 15:47:07 -04:00
co-authored by Claude Opus 5.5
parent 56da55aba9
commit 6a313c7bf2
26 changed files with 64522 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/starkernel/log_attrib.h
+6 -1
View File
@@ -54,7 +54,12 @@ extern "C" {
struct VM;
/* vm_log_attributed_vm - The VM whose dictionary context is currently
* executing, or NULL if none (see this header's own doc comment). */
* executing, or NULL if none (see this header's own doc comment).
* FABRIC-3.8.md §3.12 (Stage FR, 2026-09-23): stack-scoped -- the innermost
* VM interpreting on the stack owned by sk_vm_switch_current_vm(), kept in
* that owner's VMFrame, so it stays correct across context switches. NULL
* means nothing is interpreting on the current stack; callers map that to
* the unattributed "HADES" source, never to the current VM itself. */
struct VM *vm_log_attributed_vm(void);
#ifdef __cplusplus
include/starkernel/vm/vm_frame.h
+97
View File
@@ -0,0 +1,97 @@
/*
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.
*/
/**
* vm_frame.h - per-VM execution frame stack (FABRIC-3.8.md §3.12, Stage FR).
*
* Captain Bob, 2026-09-23: "give frames IDs and call by ID" -- frames stack
* per VM, each with an ID. Each VM owns one VMFrameStack describing the
* nested execution levels running on ITS OWN native stack: an interpret of
* its own dictionary, a nested VM-EXEC into another VM's dictionary (a
* frame on the caller's stack whose vm_id is the target), a drain of one of
* its messages, or its parked idle point. Every frame carries a system-wide
* unique VMFrameID and names the executing VM by VMUuid -- by ID, never by
* pointer, so nothing here can dangle after a VM dies.
*
* What used to be loose per-VM flags is now derived from this stack
* (vm_core.c / kernel_hermes.c / switch.c): the ownership gate, the drain
* guard, parked-idle, and log attribution.
*
* Embedded in `struct VM` as `VM.frames` (own header per
* feedback_dedicated_headers_not_inline_fields). `vm.h` is shared with the
* hosted build, so this header must not typedef `VM`; it uses `struct VM *`.
*/
#ifndef STARKERNEL_VM_FRAME_H
#define STARKERNEL_VM_FRAME_H
#include <stdint.h>
#include "starkernel/vm_uuid.h" /* VMUuid */
struct VM;
/** System-wide unique, monotonic, never reused. 0 = no frame. */
typedef uint64_t VMFrameID;
typedef enum {
VM_FRAME_INTERPRET = 1, /**< vm_interpret() of vm_id's dictionary */
VM_FRAME_DRAIN = 2, /**< interpreting one of vm_id's own kernel-Hermes messages */
VM_FRAME_IDLE = 3 /**< vm_id parked at its switch trampoline's idle point */
} VMFrameKind;
typedef struct VMFrameEntry {
VMFrameID id;
VMUuid vm_id; /**< the VM executing at this level (held by ID) */
uint32_t kind; /**< VMFrameKind */
} VMFrameEntry;
typedef struct VMFrameStack {
VMFrameEntry *entries; /**< growable; grown by allocate-copy-free */
int count;
int cap;
int max; /**< high-water mark (DoE-observable) */
} VMFrameStack;
#ifdef __STARKERNEL__
/** Reserve initial capacity (called at birth so the hot path rarely grows). 0 ok, -1 fail. */
int vm_frame_reserve(VMFrameStack *s, int cap);
/** Push a frame; returns its new ID, or 0 if the stack could not grow (caller fails closed). */
VMFrameID vm_frame_push(VMFrameStack *s, VMUuid vm_id, uint32_t kind);
/** Pop by ID. A top that isn't `id` is corruption: logged, and `id` is removed wherever it is. */
void vm_frame_pop(VMFrameStack *s, VMFrameID id);
/** Nonzero if the top frame exists and has this kind and vm_id. */
int vm_frame_top_is(const VMFrameStack *s, VMUuid vm_id, uint32_t kind);
/** Nonzero if any frame on the stack has this kind and vm_id. */
int vm_frame_has(const VMFrameStack *s, VMUuid vm_id, uint32_t kind);
/** Release the stack's storage (vm_cleanup). */
void vm_frame_free(VMFrameStack *s);
/** The frame stack of the VM physically owning the running native stack
* (sk_vm_switch_current_vm()), or the boot stack before the switch
* mechanism is seeded. Defined in vm_core.c. */
VMFrameStack *vm_frame_current_stack(void);
/** vm_interpret() with an explicit frame kind (VM_FRAME_INTERPRET for plain
* interpretation; the drain uses VM_FRAME_DRAIN). Defined in vm_core.c. */
void vm_interpret_kind(struct VM *vm, const char *input, uint32_t kind);
#endif
#endif /* STARKERNEL_VM_FRAME_H */
include/vm.h
+8 -21
View File
@@ -442,6 +442,7 @@ typedef struct {
#ifdef __STARKERNEL__
#include "starkernel/vm_uuid.h" /* VMUuid -- item 4.2, VM.stadium_vm_id */
#include "starkernel/vm_identity.h" /* VMIdentity -- FABRIC-2.md §F.2/§F.16 */
#include "starkernel/vm/vm_frame.h" /* VMFrame -- FABRIC-3.8.md §3.12 */
/* Saved interpreter state for VM lifecycle calls (BIRTH, VM-EXEC, START).
* Dynamically allocated; grows on demand via sf_realloc. */
@@ -669,27 +670,13 @@ typedef struct VM
* let a later switch-in from a different VM get
* silently bounced to the original caller instead
* of itself. */
int interpret_depth; /**< FABRIC-3.8.md §3.1 (Stage A, 2026-09-23): THIS
* VM's own vm_interpret() nesting depth. Replaces
* the single global g_vm_interpret_depth as the
* ownership gate's depth test -- once VMs genuinely
* interleave on their own native stacks, a global
* count across all VMs stops meaning "this VM is
* at its own outermost frame." 0 = not
* interpreting; 1 = outermost frame. */
int hermes_draining; /**< FABRIC-3.8.md §3.3 (Stage B): nonzero while
* sk_hermes_drain_checkpoint() is interpreting one
* of this VM's own messages. No drain site drains
* again while it is set -- a payload running at the
* VM's depth 1 would otherwise let its own in-word
* checkpoint drain a SECOND message inside the
* first one's execution. */
int parked_idle; /**< FABRIC-3.8.md §3.5 (Stage B): nonzero only while
* this VM is parked in its switch trampoline's idle
* branch -- nothing borrowed on its stack, no work
* in progress. Distinct from VM_STATE_SWITCHED_OUT,
* which is also true of a VM parked mid-work.
* Consumed by the kill path in Stage D. */
VMFrameStack frames; /**< FABRIC-3.8.md §3.12 (Stage FR, 2026-09-23):
* this VM's execution frame stack -- the nested
* levels running on its own native stack, each
* with a frame ID and the executing VM's ID. The
* ownership gate, drain guard, parked-idle and log
* attribution are all derived from it. See
* starkernel/vm/vm_frame.h. */
/** @} */
/** @name Stadium Identity (item 4.2, FABRIC-0.md §25.5)