329 lines
7.3 KiB
Markdown
329 lines
7.3 KiB
Markdown
# LithosAnanke Roadmap
|
||
|
||
**Branch:** `lithosananke`
|
||
**Current:** M7 Complete
|
||
|
||
---
|
||
|
||
## Milestone Overview
|
||
|
||
```
|
||
M0 UEFI Boot ████████████████████ COMPLETE
|
||
M1 PMM ████████████████████ COMPLETE
|
||
M2 VMM ████████████████████ COMPLETE
|
||
M3 IDT ████████████████████ COMPLETE
|
||
M4 APIC ████████████████████ COMPLETE
|
||
M5 Timer ████████████████████ COMPLETE
|
||
M6 Heap ████████████████████ COMPLETE
|
||
M7 VM Parity ████████████████████ COMPLETE
|
||
M7.1 Capsules ████████████░░░░░░░░ DESIGN COMPLETE
|
||
M8 REPL ░░░░░░░░░░░░░░░░░░░░ PLANNED
|
||
M9 Block I/O ░░░░░░░░░░░░░░░░░░░░ PLANNED
|
||
M10 Networking ░░░░░░░░░░░░░░░░░░░░ FUTURE
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 1: Boot Foundation (M0-M6)
|
||
|
||
### M0: UEFI Boot + Serial Output
|
||
|
||
**Goal:** Kernel prints "LithosAnanke booting..." to serial
|
||
|
||
**Deliverables:**
|
||
- [x] UEFI loader (`uefi_loader.c`)
|
||
- [x] BootInfo handoff (memory map, ACPI, framebuffer)
|
||
- [x] ExitBootServices
|
||
- [x] Serial console output
|
||
|
||
**Validation:**
|
||
```
|
||
StarKernel UEFI Loader
|
||
Loading...
|
||
RAW SERIAL UP
|
||
```
|
||
|
||
---
|
||
|
||
### M1: Physical Memory Manager
|
||
|
||
**Goal:** Track and allocate physical page frames
|
||
|
||
**Deliverables:**
|
||
- [x] Bitmap allocator
|
||
- [x] Parse UEFI memory map
|
||
- [x] `pmm_alloc_pages()` / `pmm_free_pages()`
|
||
- [x] Statistics reporting
|
||
|
||
**Validation:**
|
||
```
|
||
PMM initialized.
|
||
PMM statistics:
|
||
Total pages: 249450
|
||
Free pages : 247921
|
||
```
|
||
|
||
---
|
||
|
||
### M2: Virtual Memory Manager
|
||
|
||
**Goal:** 4-level paging, identity + higher-half mapping
|
||
|
||
**Deliverables:**
|
||
- [x] PML4 → PDPT → PD → PT setup
|
||
- [x] CR3 switch
|
||
- [x] `vmm_map()` / `vmm_unmap()`
|
||
- [x] Self-test
|
||
|
||
**Validation:**
|
||
```
|
||
VMM initialized (mapped RAM, CR3 switched)
|
||
VMM self-test: mapped OK at 0xffff800000000000
|
||
```
|
||
|
||
---
|
||
|
||
### M3: Interrupt Descriptor Table
|
||
|
||
**Goal:** CPU exceptions and IRQ handling
|
||
|
||
**Deliverables:**
|
||
- [x] 256-entry IDT
|
||
- [x] ISR stubs (asm)
|
||
- [x] Exception handlers (div-by-zero, page fault, etc.)
|
||
- [x] IRQ routing framework
|
||
|
||
**Validation:**
|
||
```
|
||
IDT installed.
|
||
```
|
||
|
||
---
|
||
|
||
### M4: APIC Timer
|
||
|
||
**Goal:** Local APIC initialization and timer IRQs
|
||
|
||
**Deliverables:**
|
||
- [x] Local APIC enable
|
||
- [x] APIC timer configuration
|
||
- [x] Spurious interrupt vector
|
||
|
||
**Validation:**
|
||
```
|
||
APIC: init...
|
||
APIC enabled (SIVR=0xFF).
|
||
APIC: init done
|
||
```
|
||
|
||
---
|
||
|
||
### M5: Timer Calibration
|
||
|
||
**Goal:** Accurate time measurement
|
||
|
||
**Deliverables:**
|
||
- [x] TSC frequency detection
|
||
- [x] HPET calibration (when available)
|
||
- [x] PM Timer fallback
|
||
- [x] Relative vs. absolute trust levels
|
||
|
||
**Validation:**
|
||
```
|
||
Timer: init...
|
||
Timer: trust=1 (0=NONE,1=REL,2=ABS), TSC=0 Hz
|
||
Timer: init done
|
||
```
|
||
|
||
---
|
||
|
||
### M6: Kernel Heap
|
||
|
||
**Goal:** `kmalloc()` / `kfree()` working
|
||
|
||
**Deliverables:**
|
||
- [x] Heap initialization
|
||
- [x] Allocation tracking
|
||
- [x] Statistics
|
||
|
||
**Validation:**
|
||
```
|
||
Kernel heap initialized.
|
||
Heap statistics:
|
||
Total bytes: 16777176
|
||
Free bytes: 16777176
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 2: VM Integration (M7)
|
||
|
||
### M7: VM Parity Validation
|
||
|
||
**Goal:** StarForth VM boots with reproducible dictionary hash
|
||
|
||
**Deliverables:**
|
||
- [x] VMHostServices abstraction
|
||
- [x] VM arena allocation (5 MB)
|
||
- [x] FORTH-79 word registration (295 words)
|
||
- [x] Parity checkpoint logging
|
||
- [x] Heartbeat thread start
|
||
|
||
**Validation:**
|
||
```
|
||
VM: bootstrap parity...
|
||
[HAL][host] VMHostServices table registered
|
||
VM arena allocated: 0xffff900000000000 (5 MB)
|
||
Registering FORTH-79 Standard word set...
|
||
PARITY:M7.1a word_count=295 here=0x30 latest_id=294 hash=0x684bbf2fa1d96d55
|
||
PARITY:OK
|
||
VM: parity bootstrap complete
|
||
Starting heartbeat...
|
||
APIC Timer: started
|
||
```
|
||
|
||
**Commit:** `6f350bc` — M7: StarForth VM integration with parity validation
|
||
|
||
---
|
||
|
||
## Phase 3: Capsule Architecture (M7.1)
|
||
|
||
### M7.1: Init Capsule System
|
||
|
||
**Goal:** Content-addressed, immutable init capsules for VM birth
|
||
|
||
**Status:** Design Complete (see [M7.1.md](M7.1.md))
|
||
|
||
**Core Concepts:**
|
||
|
||
| Concept | Description |
|
||
|---------|-------------|
|
||
| **DOMAIN** | Mama-only construction space — never visible to babies |
|
||
| **PERSONALITY** | Baby-only identity — result of executing (p) INIT |
|
||
| **(p) Production** | Truth-bearing capsules that birth VMs |
|
||
| **(e) Experiment** | Mama-only workloads for DoE |
|
||
|
||
**Birth Protocol:**
|
||
1. Mama selects one production `(p)` capsule by content hash
|
||
2. Mama validates eligibility (ACTIVE, PRODUCTION, not REVOKED)
|
||
3. Mama allocates new VM
|
||
4. INIT blocks copied to execution window (RAM blocks 0–2047)
|
||
5. INIT blocks executed sequentially
|
||
6. Execution window cleared
|
||
7. VM begins life with PERSONALITY imprinted
|
||
8. Mama logs `PARITY:BIRTH vm_id=N capsule_id=X mode=p ...`
|
||
9. Mama increments `capsule.birth_count`
|
||
|
||
**Deliverables:**
|
||
- [ ] `CapsuleDesc` struct (64 bytes, cache-aligned)
|
||
- [ ] `CapsuleDirHeader` struct
|
||
- [ ] xxHash64 implementation (freestanding)
|
||
- [ ] `capsule_validate()` function
|
||
- [ ] Birth protocol (`PARITY:BIRTH` logging)
|
||
- [ ] DoE run logging (`CapsuleRunRecord`)
|
||
- [ ] `mkcapsule` build tool
|
||
|
||
**Key Design Decisions:**
|
||
- Content-addressed: `capsule_id == content_hash`
|
||
- (p) Production vs (e) Experiment modes
|
||
- One truth per VM — no shared/implicit base INITs
|
||
- Mama holds all truths — (e) capsules never touch babies
|
||
- Twins/variants are just VMs with same/similar capsules
|
||
|
||
---
|
||
|
||
## Phase 4: Interactive Forth (M8)
|
||
|
||
### M8: REPL + Interactive Forth
|
||
|
||
**Goal:** Type Forth at the kernel, get `ok` prompt
|
||
|
||
**Deliverables:**
|
||
- [ ] Keyboard input (PS/2 or USB HID)
|
||
- [ ] REPL loop integration
|
||
- [ ] Line editing (backspace, minimal)
|
||
- [ ] Word execution from console
|
||
|
||
**Validation:**
|
||
```
|
||
LithosAnanke v0.3.0
|
||
ok 1 2 + .
|
||
3 ok
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 5: Persistence (M9)
|
||
|
||
### M9: Block Storage
|
||
|
||
**Goal:** Read/write blocks to disk
|
||
|
||
**Deliverables:**
|
||
- [ ] AHCI driver (SATA)
|
||
- [ ] Block device abstraction
|
||
- [ ] `BLOCK` / `BUFFER` / `UPDATE` / `FLUSH` words
|
||
- [ ] Persistent dictionary
|
||
|
||
---
|
||
|
||
## Future Milestones
|
||
|
||
### M10: Networking
|
||
- VirtIO-net driver
|
||
- TCP/IP stack (minimal)
|
||
- DHCP client
|
||
|
||
### M11: Process Model
|
||
- Forth tasks
|
||
- Scheduling
|
||
- IPC
|
||
|
||
### M12: Self-Hosting
|
||
- Compile Forth on LithosAnanke
|
||
- Edit/assemble/link cycle
|
||
|
||
---
|
||
|
||
## Validation Commands
|
||
|
||
```bash
|
||
# Build
|
||
make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1
|
||
|
||
# Run QEMU
|
||
make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1 qemu
|
||
|
||
# Clean
|
||
make -f Makefile.starkernel ARCH=amd64 clean-kernel
|
||
```
|
||
|
||
---
|
||
|
||
## Branch Relationship
|
||
|
||
```
|
||
master (hosted StarForth)
|
||
│
|
||
├── lithosananke (kernel branch)
|
||
│ │
|
||
│ └── M7 complete, M7.1 design complete
|
||
│
|
||
└── starkernel-junkyard (legacy, can delete)
|
||
```
|
||
|
||
---
|
||
|
||
## Success Criteria
|
||
|
||
LithosAnanke is successful when:
|
||
|
||
1. **M7 Parity** — VM dictionary hash reproducible across boots
|
||
2. **M7.1 Capsules** — Birth protocol enforced, provenance logged
|
||
3. **M8 REPL** — Interactive Forth at bare metal
|
||
4. **M9 Persistence** — State survives reboot
|
||
|
||
---
|
||
|
||
*The foundation is laid. The necessity is clear.*
|