Reorganize source tree: kernel/, v3/, v4/ split and board infrastructure

Source tree reorganization: - Move StarForth v3 engine to v3/ (src/, include/, Makefile) - Move kernel to kernel/ (src/, include/, linker/, Makefile) - Create v4/ skeleton for F18-ISA golden model (DECOMPOSITION.md, JUSTIFICATION.md) - Move FABRIC-0..4.md to docs/fabric/ - Move ONTOLOGY.md and ROADMAP.md to docs/ Board infrastructure: - Add boards/ser5/, boards/raspi/, boards/milkv/, boards/zynq7020/ - Each board has board.mk (ISA, CPU flags, boot recipe) and README.md - Root Makefile becomes thin dispatcher: boot_image, all, clean, docs take TARGET - make boot_image TARGET=SER5|RASPI|MILKV builds one GPT/MBR image per board - ZYNQ7020 target exists but stops with clear error (ARMv7 port not built yet) - scripts/mkdiskimage.sh builds disk images for all boards Docs pipeline: - docs/book/ with LaTeX master (main.tex) and Makefile - pandoc converts Markdown to LaTeX at build time - Two Lua filters: table-widths.lua (wide tables wrap), code-breaks.lua (inline code breaks) - make docs builds single PDF (754 pages, 0 missing characters) - make docs TARGET=<board> adds board appendix - build/docs/<book|board>/meta.tex stamps git commit into PDF Bug fixes: - 42 include paths that only worked by accident now use correct relative paths - clang-18 hardcode replaced with configurable CC variable (fixed aarch64 build) - Pi 5: kernel_2712.img linked at 0x80000, .bss zeroed, memory reserved - Doxyfile, .clang-tidy, README.md, Kconfig paths updated Verified: - Hosted v3 build passes 1012 tests, 0 failures - SER5 image boots in QEMU (OVMF), POST passes, K exact (65536 = Q48_ONE) - Milk-V image boots in QEMU (OpenSBI + U-Boot + bootefi), POST passes - make clean TARGET=<board> removes only that board and its ISA objects - make all builds all boards, hosted v3, and docs in one run Co-authored-by: Junie <junie@jetbrains.com>
2026-10-01 15:40:09 -04:00
parent 3c709c115b
commit a8b70e88d3
630 changed files with 2646 additions and 2036 deletions
@@ -0,0 +1,141 @@
+/*
+  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.
+*/
+
+/**
+ * switch.c - Cooperative VM context switch glue (FABRIC-3.md §XXVIII,
+ * Stage 2, 2026-09-13). See switch.h for the contract.
+ */
+
+#ifdef __STARKERNEL__
+
+#include "starkernel/vm/switch.h"
+#include "vm.h"
+#include "starkernel/capsule_birth.h" /* capsule_vm_set_state */
+#include <stdint.h>
+
+/* Arch-specific (switch.S in each arch dir). sk_vm_switch_prime() builds
+ * the exact synthetic first-entry frame sk_vm_switch_to() expects -- kept
+ * in assembly, not duplicated here, so the layout can never drift out of
+ * sync between the two. */
+extern void     sk_vm_switch_to(uint64_t *save_sp_out, uint64_t new_sp);
+extern uint64_t sk_vm_switch_prime(uint64_t stack_top, void *entry);
+
+/* Single-writer-mainline global, safe under this stage's cooperative-only,
+ * one-VM-runs-at-a-time-on-one-hart discipline (same class of bookkeeping
+ * as vm_core.c's g_log_attrib_vm) -- identifies which VM a freshly-primed
+ * native stack belongs to. Read exactly once, synchronously, at the very
+ * top of sk_vm_switch_entry() before any other first-entry could occur.
+ * Safe to keep as a plain global (unlike the old g_switch_back_to this
+ * file used to also carry -- see native_switch_back_to's own doc comment
+ * in vm.h for why that one had to move to per-VM state): a VM's identity
+ * never changes across the lifetime of its own trampoline instance, only
+ * who most recently switched into it does. */
+static VM *g_switch_entry_vm;
+
+/* FABRIC-3.md §XXVIII Stage 3 follow-on (2026-09-14): which VM is
+ * currently running, from the switch mechanism's own point of view --
+ * independent of vm_log_attributed_vm() (vm_core.c), which is scoped to
+ * nested vm_interpret() calls for log-source attribution and has no way
+ * to know a VM is "running" while parked inside this file's own raw C
+ * trampoline (sk_vm_switch_entry()), never itself calling vm_interpret().
+ * sk_vm_switch_signal_tick() (capsule_vm_switch_signal.c) consults this
+ * instead of vm_log_attributed_vm() for exactly that reason -- see its
+ * own updated comment. Single-writer-mainline, same discipline as
+ * g_switch_entry_vm above: set unconditionally on every switch, by the
+ * only code path that can ever change who is physically running.
+ * Seeded once at boot via sk_vm_switch_set_current() for whichever VM is
+ * running before any switch has ever happened (Hera, at Stage 3
+ * registration time -- kernel_main.c). */
+static VM *g_switch_current_vm;
+
+VM *sk_vm_switch_current_vm(void) { return g_switch_current_vm; }
+
+void sk_vm_switch_set_current(VM *vm) { g_switch_current_vm = vm; }
+
+/**
+ * sk_vm_switch_entry - trampoline for a VM's first-ever entry.
+ *
+ * A freshly-entered VM has no production behavior defined yet -- what a
+ * switched-to VM should actually DO once running is later-stage work
+ * (message dispatch, an idle loop, whatever Stage 3+ needs). For now this
+ * is a minimal, permanent placeholder: immediately yield back to whoever
+ * most recently switched to it, forever. Reads self->native_switch_back_to
+ * fresh every iteration (not a value captured once) so a later switch-in
+ * from a different VM is honored, not silently bounced to whoever entered
+ * first. Must never fall off the end -- there is no legitimate return
+ * address below a synthetic first-entry frame, unlike an ordinary
+ * function.
+ *
+ * FABRIC-3.md §XXVIII Stage 3 follow-on (2026-09-14): an attempt to make
+ * this attributable by calling vm_interpret(self, "MSG-TICK") here was
+ * tried and reverted -- it introduced a second, distinct hang (a stall in
+ * sk_repl_headless_wait()'s WIREBIND-attachment wait, not root-caused) in
+ * place of the switch-storm it was meant to fix. The switch-storm's real
+ * cause (sk_vm_switch_signal_tick()'s "who is current" check via
+ * vm_log_attributed_vm() never seeing a VM that only ever runs this raw
+ * C trampoline) is instead fixed at the source in switch.c/
+ * capsule_vm_switch_signal.c: sk_vm_context_switch() now tracks "current"
+ * itself, independent of vm_interpret()'s own attribution bookkeeping.
+ * This placeholder's behavior is therefore unchanged from Stage 2.
+ */
+void sk_vm_switch_entry(void) {
+    VM *self = g_switch_entry_vm;
+    for (;;) {
+        sk_vm_context_switch(self, self->native_switch_back_to);
+    }
+}
+
+int sk_vm_context_switch(VM *from, VM *to) {
+    uint64_t new_sp;
+
+    if (!from || !to || to->native_stack_top == 0) {
+        return -1;
+    }
+
+    /* Recorded unconditionally (first-ever entry or a resume) so whoever
+     * is parked at `to`'s native stack -- most often this placeholder
+     * trampoline -- always knows who most recently switched into it. */
+    to->native_switch_back_to = from;
+
+    if (to->native_stack_saved_sp == 0) {
+        /* First-ever entry: synthesize the initial frame. */
+        g_switch_entry_vm = to;
+        new_sp = sk_vm_switch_prime(to->native_stack_top, (void *)&sk_vm_switch_entry);
+    } else {
+        new_sp = to->native_stack_saved_sp;
+        to->native_stack_saved_sp = 0; /* about to be running, not parked */
+    }
+
+    capsule_vm_set_state(to->stadium_vm_id, VM_STATE_LIVE);
+    capsule_vm_set_state(from->stadium_vm_id, VM_STATE_SWITCHED_OUT);
+    g_switch_current_vm = to;
+
+    sk_vm_switch_to(&from->native_stack_saved_sp, new_sp);
+
+    /* Resumes here only once something later switches back to `from` --
+     * from `from`'s own point of view, this call simply took a while. */
+    capsule_vm_set_state(from->stadium_vm_id, VM_STATE_LIVE);
+    g_switch_current_vm = from;
+    return 0;
+}
+
+#endif /* __STARKERNEL__ */