Robert Allan JamesandClaude Opus 5.5
6a313c7bf2
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>
98 lines
4.0 KiB
C
98 lines
4.0 KiB
C
/*
|
||
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 */
|