docs: reorganise -- current reference gathered, finished work archived, superseded and dead ideas marked as such
docs/CLAUDE.md Phase 2, 2026-10-14. All moves by git mv; every archived file carries a header saying what it is, why, and where to look instead. - docs/reference/ (new): roadmap and versioning policy, M7.1, word-ACL design, kernel args, hosted acceptance test, dictionary, primitives, ontology, L8 table -- previously spread over docs/, docs/lithosananke/ and docs/03-architecture/. - docs/working/archive/historical/: finished work (session plan, test-gap audit, birthing plan, fix write-ups, the January architecture draft). - docs/working/archive/superseded/: the Hermes-VM Tripod docs and July Hermes designs (-> FABRIC-3.5/3.6), the StarForth roadmap, every working doc already flagged superseded or obsolete. - docs/working/archive/dead/: the hal_* target contract (never adopted), L4Re, metrics-and-knobs. - Papers and proposals into docs/working/papers/. - References rewritten across the repo (not logs/, not docs/patent/); CLAUDE.md's documentation section rewritten. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
1a4b163861
commit
7aed588f78
@@ -0,0 +1,246 @@
|
||||
> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/).
|
||||
> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/README.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/hal/README.md to docs/working/archive/dead/hal-target-contract/README.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ TARGET HAL — NOT THE BUILT INTERFACE (flagged 2026-10-09).** This document family
|
||||
> describes a proposed `hal_*`-named interface and a `src/platform/<platform>/` layout that
|
||||
> was never adopted as written. The implemented kernel HAL lives in `src/starkernel/hal/`
|
||||
> with different (time-backend-style) naming. Treat all five documents here as design intent,
|
||||
> not the current API. For current architecture see `.claude/CLAUDE.md`.
|
||||
|
||||
# Hardware Abstraction Layer (HAL) Documentation
|
||||
|
||||
This directory contains comprehensive documentation for StarForth's Hardware Abstraction Layer (HAL), which enables the evolution from hosted VM to StarKernel to StarshipOS.
|
||||
|
||||
> **HISTORICAL — L4Re/Fiasco.OC**: L4Re references throughout this directory's docs describe a target that was a supported platform through mid-2026. L4Re support has since been removed as an active target — `src/platform/l4re/time.c` and related `#ifdef __l4__` code are retained for reference but no longer wired into any build.
|
||||
|
||||
---
|
||||
|
||||
## Document Organization
|
||||
|
||||
Read in this order for full understanding:
|
||||
|
||||
### 1. **[overview.md](overview.md)** - Start Here
|
||||
**What:** High-level HAL architecture, design principles, and rationale
|
||||
**Who:** Everyone (developers, architects, contributors)
|
||||
**Why read:** Understand the problem HAL solves and how it fits into StarForth → StarKernel → StarshipOS
|
||||
|
||||
**Key sections:**
|
||||
- The Problem (why HAL is necessary)
|
||||
- Architecture Overview (3-layer model)
|
||||
- Design Principles (VM purity, contract-first, testability)
|
||||
- HAL Subsystems (time, interrupts, memory, console, CPU)
|
||||
- HAL and Physics Subsystems
|
||||
- Success Criteria
|
||||
|
||||
---
|
||||
|
||||
### 2. **[interfaces.md](interfaces.md)** - The Contract
|
||||
**What:** Detailed HAL interface specifications (function signatures, semantics, guarantees)
|
||||
**Who:** VM developers, platform implementers
|
||||
**Why read:** Understand exactly what each HAL function does and requires
|
||||
|
||||
**Key sections:**
|
||||
- Time & Timers interface (`hal_time.h`)
|
||||
- Interrupts interface (`hal_interrupt.h`)
|
||||
- Memory interface (`hal_memory.h`)
|
||||
- Console interface (`hal_console.h`)
|
||||
- CPU interface (`hal_cpu.h`)
|
||||
- Panic/Error interface (`hal_panic.h`)
|
||||
- Interface safety summary (ISR-safe, thread-safe)
|
||||
|
||||
**Critical details:**
|
||||
- Function semantics (what it does, guaranteed behavior)
|
||||
- Error handling (when it can fail, how to handle)
|
||||
- Performance expectations (latency, overhead)
|
||||
- Concurrency model (thread-safe? ISR-safe?)
|
||||
|
||||
---
|
||||
|
||||
### 3. **[platform-implementations.md](platform-implementations.md)** - How to Implement
|
||||
**What:** Platform-specific implementation examples and guidance
|
||||
**Who:** Platform developers adding HAL support for new targets
|
||||
**Why read:** Learn how to implement HAL for a specific platform
|
||||
|
||||
**Key sections:**
|
||||
- Platform directory structure
|
||||
- Linux HAL implementation (reference platform)
|
||||
- Kernel HAL implementation (StarKernel)
|
||||
- Platform testing strategy
|
||||
- Common implementation pitfalls
|
||||
|
||||
**Includes complete code examples for:**
|
||||
- Linux (POSIX, hosted)
|
||||
- Kernel (freestanding, bare metal)
|
||||
|
||||
---
|
||||
|
||||
### 4. **[migration-plan.md](migration-plan.md)** - Refactoring Guide
|
||||
**What:** Step-by-step plan for refactoring existing StarForth to use HAL
|
||||
**Who:** Core developers doing the migration work
|
||||
**Why read:** Execute the HAL migration safely with zero regressions
|
||||
|
||||
**Key sections:**
|
||||
- 7-phase migration strategy
|
||||
- Incremental refactoring approach
|
||||
- Test validation after each phase
|
||||
- Rollback strategy
|
||||
- Timeline estimates (2-4 weeks)
|
||||
|
||||
**Phases:**
|
||||
1. Define HAL interfaces (headers only)
|
||||
2. Implement HAL for Linux
|
||||
3. Migrate VM core to use HAL
|
||||
4. Migrate physics subsystems to use HAL
|
||||
5. Migrate REPL and word implementations
|
||||
6. Implement HAL for L4Re (optional validation)
|
||||
7. Validate deterministic behavior
|
||||
|
||||
---
|
||||
|
||||
### 5. **[starkernel-integration.md](starkernel-integration.md)** - Kernel Details
|
||||
**What:** StarKernel-specific HAL implementation and boot sequence
|
||||
**Who:** Kernel developers building StarKernel
|
||||
**Why read:** Understand UEFI boot, freestanding C, hardware initialization
|
||||
|
||||
**Key sections:**
|
||||
- StarKernel architecture (boot sequence)
|
||||
- Directory structure (`src/platform/kernel/`)
|
||||
- Boot sequence detail (UEFI → StarKernel → VM)
|
||||
- HAL implementation details (time, interrupts, memory, console, CPU)
|
||||
- Build system (freestanding toolchain, linker script)
|
||||
- Testing on QEMU/OVMF
|
||||
- Debugging techniques
|
||||
- Roadmap to `ok` prompt
|
||||
|
||||
**Includes:**
|
||||
- Complete UEFI loader implementation
|
||||
- Kernel entry point
|
||||
- Hardware initialization sequence
|
||||
- QEMU testing guide
|
||||
- Debugging strategies
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### For Different Roles
|
||||
|
||||
**I'm a VM developer:**
|
||||
- Read: `overview.md`, `interfaces.md`
|
||||
- Use HAL functions in VM code
|
||||
- Never call platform-specific APIs directly
|
||||
|
||||
**I'm adding a new platform:**
|
||||
- Read: `overview.md`, `interfaces.md`, `platform-implementations.md`
|
||||
- Implement all HAL interfaces for your platform
|
||||
- Test against VM test suite (936+ tests must pass)
|
||||
|
||||
**I'm migrating existing code to HAL:**
|
||||
- Read: `migration-plan.md`
|
||||
- Follow 7-phase incremental approach
|
||||
- Test after each phase
|
||||
|
||||
**I'm building StarKernel:**
|
||||
- Read: All documents, especially `starkernel-integration.md`
|
||||
- Start with UEFI boot + serial output
|
||||
- Build incrementally to `ok` prompt
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### HAL Principles
|
||||
|
||||
1. **VM Purity:** VM code is platform-agnostic, never knows which platform it's on
|
||||
2. **Contract-First:** HAL interfaces are contracts with precise semantics
|
||||
3. **Testability:** Develop/test on Linux, deploy on kernel
|
||||
4. **Zero Overhead:** HAL inlines to direct hardware access when optimized
|
||||
5. **Fail-Fast:** Validate platform assumptions at init, not during execution
|
||||
|
||||
### Success Criteria
|
||||
|
||||
The HAL is successful if:
|
||||
- ✅ VM core has zero platform-specific code
|
||||
- ✅ All 936+ tests pass on all platforms
|
||||
- ✅ 0% algorithmic variance maintained
|
||||
- ✅ No measurable performance regression
|
||||
- ✅ StarKernel boots to `ok` prompt
|
||||
- ✅ Physics subsystems work identically on all platforms
|
||||
|
||||
---
|
||||
|
||||
## Document Status
|
||||
|
||||
| Document | Status | Last Updated |
|
||||
|----------|--------|--------------|
|
||||
| overview.md | ✅ Complete | 2025-12-14 |
|
||||
| interfaces.md | ✅ Complete | 2025-12-14 |
|
||||
| platform-implementations.md | ✅ Complete | 2025-12-14 |
|
||||
| migration-plan.md | ✅ Complete | 2025-12-14 |
|
||||
| starkernel-integration.md | ✅ Complete | 2025-12-14 |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate (HAL Migration)
|
||||
1. Review and approve HAL interface specifications
|
||||
2. Execute migration plan Phase 1 (define interfaces)
|
||||
3. Execute migration plan Phase 2 (implement Linux HAL)
|
||||
4. Continue through Phase 7 (validation)
|
||||
|
||||
### Near-Term (StarKernel)
|
||||
1. Implement UEFI boot loader
|
||||
2. Implement kernel HAL subsystems
|
||||
3. Boot to `ok` prompt on QEMU
|
||||
4. Validate physics subsystems on bare metal
|
||||
|
||||
### Long-Term (StarshipOS)
|
||||
1. Add storage drivers (AHCI, NVMe)
|
||||
2. Add networking stack (TCP/IP)
|
||||
3. Implement process model (Forth tasks)
|
||||
4. Build device model (block/net/char)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
### StarForth Documentation
|
||||
- `docs/CLAUDE.md` - Project overview and build instructions
|
||||
- `docs/03-architecture/heartbeat-system/` - Heartbeat subsystem details
|
||||
- `docs/FEEDBACK_LOOPS.md` - Physics feedback loops
|
||||
- `README.md` - Project quick start
|
||||
|
||||
### External Resources
|
||||
- [UEFI Specification](https://uefi.org/specifications)
|
||||
- [GNU-EFI](https://sourceforge.net/projects/gnu-efi/)
|
||||
- [OSDev Wiki](https://wiki.osdev.org/)
|
||||
- [Intel Software Developer Manual](https://www.intel.com/sdm)
|
||||
- [ACPI Specification](https://uefi.org/acpi)
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
When updating HAL documentation:
|
||||
|
||||
1. **Keep documents synchronized** - Changes to interfaces require updates to implementation guides
|
||||
2. **Maintain code examples** - Examples must compile and work
|
||||
3. **Update this README** - Reflect new sections or document reorganization
|
||||
4. **Version documentation** - Note "Last Updated" dates
|
||||
5. **Test instructions** - Verify all commands and code snippets work
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
For questions about HAL architecture or StarKernel implementation, see:
|
||||
- GitHub Issues: https://github.com/anthropics/starforth/issues (if public)
|
||||
- Project maintainer: (contact info)
|
||||
- Documentation feedback: (preferred method)
|
||||
|
||||
---
|
||||
|
||||
*The HAL is not just a kernel bootstrapping tool—it's the architectural foundation for StarForth → StarKernel → StarshipOS.*
|
||||
Reference in New Issue
Block a user