admin/LithosAnanake
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7bc658bb83d754fd320813130f26eed6e11307ce
LithosAnanake/README.md
T
rajamesandClaude Opus 5.5 f8fbc37698 docs: the 12 duplicates deleted; README rewritten to the system as it is 
Captain Bob's rulings, 2026-10-14: "delete" -- the duplicates listed in
DELETE-CANDIDATES.md are removed (the list stays as the record; the
formal tier's provenance comments repointed at the maintained copies) --
and "rewrite" the README: v2.1.0, the Tripod as Hera/Artemis/Hestia,
kernel-Hermes, identities on thumbdrives, the corrected ACL overhead,
1052-test POST and the current parity line, keyboards and storage, board
images carrying both systems and how to switch, and docs/README.md as
the way in.  The book is left as it is, to be reworked later.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 16:45:39 -04:00

147 lines
7.5 KiB
Markdown
Raw 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.1.0
**UEFI-bootable FORTH microkernel.** Boots from firmware, initialises memory and interrupts, then
runs StarForth 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. |
| **FPGA StarForth F18** | A 32-bit build of the same engine loaded into the FPGA: the gateway to the rest, the foundation everything else is built up from. |
| **StarshipOS** | The bare-metal product: LithosAnanke running StarForth. |
FORTH-79 is recomposed on the F18 engine and stored as a capsule; the StarshipOS-specific
vocabulary gets the same treatment. v3 remains the reference system until v4 meets its
acceptance criteria (`docs/v4.0.0/JUSTIFICATION.md` §16). **Both run on bare metal now:** every
board image carries v3 and v4, and one word in its boot configuration chooses (see below).
---
## Status
| Milestone | | Status |
|---|---|---|
| M0–M6 | UEFI boot · PMM · VMM · IDT · APIC · heap · framebuffer VT100 console | ✅ Complete |
| M7 | StarForth VM integration + parity validation | ✅ Complete |
| M7.1 | Capsule birth · Mama FORTH vocabulary · the Tripod fleet · kernel-Hermes · word-level ACL | ✅ Live |
| M8 | Keyboard input to the REPL — PS/2, virtio and **USB** keyboards (a full keyboard: Caps/Num Lock, keypad) | ✅ In QEMU, all three ISAs |
| M9 | Block storage — Artemis's disk on virtio-blk; identity thumbdrives on USB mass storage | ✅ In QEMU · real disks: no driver yet (`boards/BRINGUP.md` A4) |
| Bare metal | SER5 (amd64), Raspberry Pi 5 (aarch64), Milk-V Mars (riscv64); Zynq-7020 (ARMv7) not yet ported | Images build; first boots on the bench — `boards/BRINGUP.md` |
POST at boot, on all three ISAs: **1052 tests**, parity hash verified —
`PARITY:M7.1a word_count=526 hash=0x82f4ae7cb2e2d424`. The v4 system's POST: 538 tests.
### What's live
- **The Tripod** — a named multi-VM fleet: **Hera** (the Mama VM, the governor), **Artemis**
(block storage: a Block Allocation Map with Q48.16 block heat, cooldown and reclamation) and
**Hestia**, birthed, run and re-birthed independently on all three architectures.
- **kernel-Hermes** — messaging moved into the kernel (the Hermes VM is gone,
`docs/fabric/FABRIC-3.5.md`): every VM takes its own messages on its own turn, under a
cooperative switcher that every VM takes part in.
- **Identities on thumbdrives** — Zuse, the superuser, and every user is a minted USB
thumbdrive (Ed25519, Zuse-signed); plugging one in births that user's VMs, pulling it out
ends them. There is only the drive: no password, no PIN.
- **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>`). Measured overhead of the live ACL-TTL mechanism: **+0.0603%**, CV 0.000%,
architecture-independent (`docs/fabric/FABRIC-1.md` §T).
- **Logs that persist** — every VM's log records go to a ring on Artemis's disk (`LOG-FLUSH`,
`LOG-SHOW`).
- **The physics-driven runtime** — seven feedback loops and the L8 Jacquard mode selector, with
a per-VM heat channel into fleet-wide tuning (VM Fleet Attractor).
- **Kconfig build configuration** — about 40 physics, heartbeat, pipelining and kernel-only
knobs, shared with the hosted build.
---
## 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 boards # list boards (the Zynq-7020 has no ARMv7 port yet)
# Each image carries v3 and v4. As built it boots v3; to boot v4, change the one word
# system=v3 -> system=v4
# in starforth.cfg on the SER5's stick or the Mars's card, or cmdline.txt on the Pi 5's card.
# The same TARGET drives all, docs and clean (make help)
make # every board with a kernel port + hosted v3 + the book
make docs # build/docs/LithosAnanke.pdf (LaTeX master: docs/book/main.tex)
make clean TARGET=RASPI # that board's outputs and build/aarch64/kernel
# The kernel in QEMU (OVMF / AAVMF / EDK2), one architecture at a time
make -f kernel/Makefile ARCH=amd64 clean qemu
make -f kernel/Makefile ARCH=aarch64 clean qemu
make -f kernel/Makefile ARCH=riscv64 clean qemu
make -f kernel/Makefile ARCH=amd64 STARFORTH_V4=1 clean qemu # the v4 system
# The Pi 5's native boot path, rehearsed on QEMU's virt machine at EL2
make -f kernel/Makefile ARCH=aarch64 RPI5_NATIVE_BASE=0x40080000 rpi5-rehearsal
```
Artifacts: `build/<arch>/kernel/starkernel_loader.efi` · `build/<arch>/kernel/starkernel_kernel.elf`
Tree: `kernel/` (LithosAnanke: `Makefile`, `src/`, `include/starkernel/`, `linker/`),
`v3/` (StarForth v3 engine and hosted build), `v4/` (StarForth v4, see `docs/v4.0.0/`),
`boards/<board>/` (`board.mk` + boot files), `capsules/` (the FORTH capsules). Every makefile
runs from the repo root; the root `Makefile` forwards any other goal to `v3/Makefile`.
For the hosted v3 VM by itself, see the separate **StarForth** repository — LithosAnanke used to
be a branch inside it, and is now its own project.
### Build configuration (optional)
Every kernel-only knob is an optional Kconfig symbol; a plain `make -f kernel/Makefile` uses
the defaults unless you opt in:
```bash
make -f kernel/Makefile ARCH=amd64 menuconfig
make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig
```
---
## Documentation
**Start at [docs/README.md](docs/README.md)** — the map: where each kind of document lives and
which to believe. Among them:
| | |
|---|---|
| [The FABRIC record](docs/fabric/) | Every design decision and the work as it happened (`FABRIC-3.md` is the living one) |
| [StarForth v4](docs/v4.0.0/) | The F18-derived engine |
| [Board bring-up](boards/BRINGUP.md) | Getting onto the SER5, the Pi 5 and the Mars |
| [Roadmap and versioning](docs/reference/ROADMAP.md) | Milestone plan and release-versioning policy |
| [Capsule System — M7.1](docs/reference/M7.1.md) | Capsule birth protocol |
| [Word-level ACL](docs/reference/word-acl/DESIGN.md) | The access-control design |
| [HAL, as built](kernel/src/hal/README.md) | Hardware abstraction layer |
| [Developer guide / Kconfig reference](docs/working/architecture/getting-started/DEVELOPER.md#build-configuration-kconfig) | Full symbol reference for both builds |
| [Dead ideas and revised claims](docs/DEAD-AND-REVISED.md) | What is no longer true, and since when |
| [Changelog](CHANGELOG.md) | Milestone-level history |
---
## 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