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>
This commit is contained in:
rajames
2026-10-01 15:40:09 -04:00
co-authored by Junie
parent 3c709c115b
commit a8b70e88d3
630 changed files with 2646 additions and 2036 deletions
+92
View File
@@ -0,0 +1,92 @@
/*
StarForth — Steady-State Virtual Machine Runtime
Copyright (c) 2023–2025 Robert A. James
All rights reserved.
Licensed under the StarForth License, Version 1.0
*/
#ifndef __STARKERNEL__
#error "capsule_console.c is kernel-only"
#endif
#include "starkernel/capsule_console.h"
#include "starkernel/capsule.h"
#include "starkernel/capsule_birth.h"
#include "starkernel/xxhash64.h"
#include "starkernel/kmalloc.h"
#include <string.h>
/* FABRIC-3.6.md Phase 4 (Stage E), 2026-09-22: used to load
* common:messaging.4th + MSG-CD-INIT here -- "just enough vocabulary
* to send/receive messages" -- but a console-proxy VM's own traffic
* (CONSOLE-CMD-EVENT) has gone through kernel-Hermes directly
* (sk_hermes_send_one(), repl.c) since task 3.9, with no dependency on
* this VM's own dictionary containing any messaging vocabulary at all.
* common:messaging.4th no longer exists as of this strip, so this
* needed to come out regardless. Genuinely empty now, past the
* mandatory "Block NNNN" header capsule_exec_payload() requires
* (§F.18) -- confirmed live that an empty body is a safe no-op when
* interpreted (task 3.8's own finding: vm_interpret() on an empty
* string is a no-op, no error, no UNKNOWN WORD). 4997 is an unused
* block number. */
static const char CONSOLE_IDENTITY_SRC[] =
"Block 4997\n";
CapsuleRunResult capsule_console_birth(const char *console_name, VMUuid parent,
VMUuid *out_vm_id, void **out_vm_ctx)
{
if (!console_name) return CAPSULE_RUN_ERR_INVALID;
size_t source_len = sizeof(CONSOLE_IDENTITY_SRC) - 1u;
uint8_t *arena = (uint8_t *)kmalloc(source_len);
if (!arena) return CAPSULE_RUN_ERR_STILLBORN;
memcpy(arena, CONSOLE_IDENTITY_SRC, source_len);
/* Heap-built single-entry directory -- same shape RUNCAP already
* established (§F.6/§F.18); never freed, matches that precedent
* (a VM's IDENTITY exec reads directly from this arena). */
CapsuleNameEntry name_entry;
memset(name_entry.name, 0, sizeof(name_entry.name));
{
size_t n = strlen(console_name);
if (n >= CAPSULE_NAME_MAX) n = CAPSULE_NAME_MAX - 1u;
memcpy(name_entry.name, console_name, n);
}
CapsuleDesc desc;
memset(&desc, 0, sizeof(desc));
desc.magic = CAPSULE_MAGIC_PACK(CAPSULE_VERSION_0, CAPSULE_HASH_XXHASH64);
desc.content_hash = xxhash64_capsule(arena, source_len);
desc.capsule_id = desc.content_hash;
desc.offset = 0;
desc.length = source_len;
desc.flags = CAPSULE_FLAG_ACTIVE | CAPSULE_FLAG_PRODUCTION;
desc.owner_vm = 0;
desc.birth_count = 0;
desc.created_ns = 0;
CapsuleDirHeader dir;
memset(&dir, 0, sizeof(dir));
dir.magic = CAPSULE_DIR_MAGIC;
dir.arena_base = (uint64_t)(uintptr_t)arena;
dir.arena_size = source_len;
dir.desc_count = 1;
dir.desc_capacity = 1;
dir.name_count = 1;
dir.dir_hash = 0;
CapsuleRunResult r = capsule_birth_baby(
console_name, &dir, &desc, &name_entry, arena, parent,
1 /* skip_pki_sig -- not build-time content, same rationale as RUNCAP */,
out_vm_id, out_vm_ctx);
/* capsule_birth_baby() never sets the registry entry's own .name --
* found live in RUNCAP (§F.18), same fix needed here. */
if (r == CAPSULE_RUN_OK && out_vm_id) {
capsule_vm_registry_set_name(*out_vm_id, console_name);
}
return r;
}