admin/LithosAnanake
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
StarForth-v4.0.0
LithosAnanake/README.md
T
rajamesandClaude Opus 5.5 a2a4a85d38 docs(v4.0.0): record the three products and v4's acceptance criteria 
Both ruled by Captain Bob, 2026-10-03.

Products (README.md, JUSTIFICATION.md section 15): Hosted StarForth F18
(native Linux, amd64/arm64/riscv64, on hardware); FPGA StarForth F18 (a
32-bit build loaded into the FPGA, the gateway and foundation); and
StarshipOS (bare metal, LithosAnanke on the v4 F18 engine). FORTH-79
recomposed on the F18 engine is stored as a capsule, as are the
StarshipOS portions; the tree will be reorganised around this.

Acceptance (JUSTIFICATION.md section 16, v4/README.md): v4 is equivalent
to v3 at any point in time -- same vocabularies, same behaviour, on the
F18-derived engine -- and every ISA, hosted and bare metal, must still
reach its ok prompt. `make -C v4 test` is a development check, not
acceptance. v4 had no acceptance criteria before this.

Documentation only; no code changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 10:13:58 -04:00

146 lines
6.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# LithosAnanke v2.0.1
**UEFI-bootable FORTH microkernel.** Boots from firmware, initialises memory and interrupts, then runs the StarForth VM as its sole userspace runtime. No libc. No OS. Just stone and necessity.
*Lithos* (foundation) + *Ananke* (necessity) — the kernel under StarshipOS.
---
## Products
StarForth v4 moves the engine onto a 32-instruction core derived from Chuck Moore's F18
(`docs/v4.0.0/`). With it, this repository carries three products, not one:
| Product | What it is |
|---|---|
| **Hosted StarForth F18** | The v4 engine as a native Linux build, for amd64, arm64 and riscv64, on real hardware. |
| **FPGA StarForth F18** | A 32-bit build of the same engine loaded into the FPGA. It is the gateway to the rest: the foundation everything else is built up from. |
| **StarshipOS** | The bare-metal product: LithosAnanke running the v4 F18 engine. |
FORTH-79 is recomposed on the F18 engine and stored as a capsule; the StarshipOS-specific
vocabulary gets the same treatment. The source tree will be reorganised around this split.
v3 remains the reference system until v4 meets its acceptance criteria
(`docs/v4.0.0/JUSTIFICATION.md` §16). Everything below describes v3 as it stands today.
---
## Status — M7.1 (Capsule System · Multi-VM Fleet)
| Milestone | | Status |
|---|---|---|
| M0–M6 | UEFI boot · PMM · VMM · IDT · APIC · heap · framebuffer VT100 console (v1.5.1-FINAL) | ✅ Complete |
| M7 | StarForth VM integration + parity validation | ✅ Complete |
| **M7.1** | **Capsule birth protocol · Mama FORTH vocabulary · Tripod multi-VM fleet (Hermes/Artemis) · Word-level ACL (Phases 1–7)** | 🔄 **In Progress** |
| M8 | REPL — keyboard input, interactive Forth | Planned |
| M9 | Block storage — AHCI driver | Planned |
POST at boot: **parity hash verified across amd64/aarch64/riscv64 · Mama capsule dictionary: 453 words**
### What's live in M7.1
- **Tripod** — a named multi-VM fleet (Hera the Mama VM, Artemis, two Hermes
instances) births, runs, and re-births independently, verified booting
live pre-REPL on all three architectures.
- **Hermes** — a 17-block inter-VM messaging/channel layer between fleet
members, with async delivery and channel negotiation.
- **Artemis** — a Block Allocation Map (BAM) storage subsystem with Q48.16
block-heat tracking and cooldown/reclamation (`ART-COOL`/`ART-REAP`).
- **Word-level ACL** — every dictionary entry carries a TTL/allow/mode/pin
access-control record. Strict, TTL, and pinned modes; two console layers
(emergency `ok>` and superuser `zuse)ok>`). Phases 1–7 complete (C
infrastructure, FORTH policy layer, `zuse` bootstrap superuser, Isabelle
proof stubs, kernel parity); Phase 8 (Ed25519 PKI / thumbdrive
challenge-response) is the only item remaining. Measured overhead once
active on every check: **+0.0054%–+0.0088%**, CV = **0.000%**, across a
3×3 Latin-square DoE campaign (architecture × seed × 30 replicates) —
three orders of magnitude below the measurement floor.
- **VM Fleet Attractor physics** — the L8 Jacquard mode selector now has a
real per-VM heat channel into fleet-wide tuning, replacing hardcoded
compudynamics constants with a dynamically-inferred rate.
- **Kconfig build configuration** — every physics/heartbeat/pipelining/
kernel-only tuning knob (~40 total) is now a discoverable, optional
Kconfig symbol shared with the hosted VM build. See **Quick Start** below.
---
## Quick Start
```bash
# One boot image per physical target (output: build/boards/<board>/)
make boot_image TARGET=SER5 # Beelink SER5 -- GPT/ESP, BOOTX64.EFI
make boot_image TARGET=RASPI # Raspberry Pi 5 -- FAT, config.txt + kernel_2712.img + DTB
make boot_image TARGET=MILKV # Milk-V Mars -- GPT/ESP, BOOTRISCV64.EFI (U-Boot bootefi)
make boot_image TARGET=ZYNQ7020 # Zynq-7020 -- ARMv7 port in progress
make boards # list boards
# The same TARGET drives all, docs and clean (make help)
make # every board with a kernel port + hosted v3 + the book
make TARGET=RASPI # one board's image + build/docs/LithosAnanke-raspi.pdf
make docs # build/docs/LithosAnanke.pdf (LaTeX master: docs/book/main.tex)
make clean TARGET=RASPI # that board's outputs and build/aarch64/kernel
make clean # all of build/ except build/cache/
# Build kernel (requires cross-compilation toolchain, or native gcc)
make -f kernel/Makefile ARCH=amd64
# Run in QEMU with OVMF
make -f kernel/Makefile qemu
# Other architectures
make -f kernel/Makefile ARCH=aarch64 qemu
make -f kernel/Makefile ARCH=riscv64 qemu
```
Artifacts: `build/amd64/kernel/starkernel_loader.efi` · `build/amd64/kernel/starkernel_kernel.elf`
Tree: `kernel/` (LithosAnanke: `Makefile`, `src/`, `include/starkernel/`, `linker/`),
`v3/` (StarForth v3 engine and hosted build: `Makefile`, `src/`, `include/`),
`v4/` (StarForth v4, see `docs/v4.0.0/`), `boards/<board>/` (`board.mk` + boot files).
Every makefile runs from the repo root; the root `Makefile` forwards any other goal to
`v3/Makefile` (hosted build).
For the hosted VM by itself (Linux, no cross-compiler needed, no bare-metal tooling): see
the separate **StarForth** repository — LithosAnanke used to be a branch inside that repo,
now it's its own project with its own `master`.
### Build configuration (optional)
Every kernel-only knob (`STARFORTH_ENABLE_VM`, `PARITY_MODE`, the shared
physics/heartbeat family, etc.) is an optional Kconfig symbol — a plain
`make -f kernel/Makefile` uses the same defaults it always has unless
you opt in:
```bash
make -f kernel/Makefile ARCH=amd64 menuconfig
make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig
```
---
## Documentation
| | |
|---|---|
| [System Architecture](docs/lithosananke/SYSTEM_ARCHITECTURE.md) | Full kernel + VM design |
| [HAL Reference](docs/lithosananke/hal/) | Hardware abstraction layer interfaces |
| [Capsule System — M7.1](docs/lithosananke/M7.1.md) | Capsule birth protocol design |
| [VM Fleet Attractor design log](docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md) | Tripod/Hermes/Artemis physics + build-system history |
| [Getting Started / Kconfig reference](docs/working/architecture/getting-started/DEVELOPER.md#build-configuration-kconfig) | Full symbol reference for both build targets |
| [Changelog](CHANGELOG.md) | Milestone-level history |
| [Roadmap](docs/lithosananke/ROADMAP.md) | Milestone plan through self-hosting |
---
## License
[Starship License 1.0 (SL-1.0)](LICENSE) — free for personal, research, and educational use.
Commercial use requires a separate agreement.
Attribution to **R.A. James (Captain Bob)** must be preserved in all distributions.
**Patent pending.** USPTO provisional filed December 2025 — physics-grounded self-adaptive runtime system. This license does not grant patent rights. Licensing inquiries: rajames440@gmail.com
---
*Robert A. James (Captain Bob) · Systems Engineer · Hacking since 1973*
Reference in New Issue View Git Blame Copy Permalink