docs: rewrite README with actual build instructions and architecture
This commit is contained in:
parent
d55b72a791
commit
d0f6d3e7ac
143
README.md
143
README.md
|
|
@ -1,53 +1,120 @@
|
|||
# Rumpk: The Modular Unikernel
|
||||
# Rumpk
|
||||
|
||||
> **"The Kernel is a Library. The App is the OS."**
|
||||
Sovereign unikernel. Zig (L0 HAL) + Nim (L1 kernel logic). Dual-arch: RISC-V 64 and ARM64.
|
||||
|
||||
**Status:** EXPERIMENTAL
|
||||
**Languages:** Zig (L0) + Nim (L1)
|
||||
**Design:** POSIX-hostile, Military-grade
|
||||
**Status:** Experimental — boots on QEMU, 14/14 fibers (riscv64), 9/9 fibers (aarch64)
|
||||
**License:** [Libertaria Sovereign License (LSL) v1.0](LICENSE)
|
||||
|
||||
## Directory Structure
|
||||
## Build
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Zig 0.15.x
|
||||
- Nim 2.0.x
|
||||
- QEMU (for boot testing)
|
||||
- bash
|
||||
|
||||
### Quick Start
|
||||
|
||||
```bash
|
||||
# Clone
|
||||
git clone https://git.sovereign-society.org/nexus/rumpk.git
|
||||
cd rumpk
|
||||
|
||||
# Build kernel (RISC-V 64, default)
|
||||
bash build_nim.sh riscv64 # Nim -> C -> .o
|
||||
bash build_lwip.sh # LwIP static lib
|
||||
zig build # Link final kernel ELF
|
||||
|
||||
# Boot test
|
||||
./run.sh
|
||||
```
|
||||
|
||||
### ARM64
|
||||
|
||||
```bash
|
||||
bash build_nim.sh aarch64
|
||||
bash build_lwip.sh
|
||||
zig build -Darch=aarch64
|
||||
./run_aarch64.sh
|
||||
```
|
||||
|
||||
### Full Build (kernel + NipBox userland + initrd)
|
||||
|
||||
```bash
|
||||
bash build_full.sh riscv64 # or: bash build_full.sh aarch64
|
||||
zig build # or: zig build -Darch=aarch64
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
rumpk/
|
||||
├── boot/ [L0] Entry & Architecture (Zig/Asm)
|
||||
│ ├── start.S Multiboot2/EFI entry point
|
||||
│ └── arch/ Architecture-specific code
|
||||
├── hal/ [L0] Hardware Abstraction (Zig)
|
||||
│ ├── mm.zig Physical/Virtual Memory
|
||||
│ ├── irq.zig Interrupt handling
|
||||
│ ├── serial.zig UART/Early logging
|
||||
│ └── abi.zig C-ABI export to Nim
|
||||
├── core/ [L1] Logic (Nim)
|
||||
│ ├── kernel.nim kmain() entry
|
||||
│ ├── sched.nim LWKT Scheduler
|
||||
│ ├── fiber.nim Fiber/Context management
|
||||
│ └── ring.nim Disruptor buffer
|
||||
├── sys/ [L2] ABI Glue
|
||||
│ └── syscall.zig System call handlers
|
||||
├── payload/ [L3] NPL/NPK Loaders
|
||||
│ └── loader.nim Signature verification
|
||||
└── io/ I/O Subsystem
|
||||
└── governor.nim Adaptive War/Peace mode
|
||||
├── boot/ L0: Entry points, linker scripts (Zig/ASM)
|
||||
├── hal/ L0: Hardware Abstraction (Zig)
|
||||
│ ├── entry_riscv.zig RISC-V boot, MMU, page tables
|
||||
│ ├── entry_aarch64.zig ARM64 boot, MMU, GIC
|
||||
│ ├── virtio_net.zig VirtIO network driver
|
||||
│ ├── virtio_block.zig VirtIO block driver
|
||||
│ ├── virtio_mmio.zig VirtIO MMIO transport (ARM64)
|
||||
│ ├── virtio_pci.zig VirtIO PCI transport (RISC-V)
|
||||
│ ├── mm.zig Memory management
|
||||
│ ├── channel.zig IPC ring buffers
|
||||
│ └── cspace.zig Capability space (HAL side)
|
||||
├── core/ L1: Kernel logic (Nim)
|
||||
│ ├── kernel.nim kmain, boot sequence
|
||||
│ ├── sched.nim Spectrum scheduler (Photon/Matter/Gravity/Void)
|
||||
│ ├── fiber.nim Cooperative fiber management
|
||||
│ ├── ion.nim ION memory allocator
|
||||
│ ├── cspace.nim Capability enforcement
|
||||
│ ├── ontology.nim System Truth Ledger
|
||||
│ ├── netswitch.nim Network fiber (DHCP/TCP/ICMP)
|
||||
│ ├── loader.nim ELF loader + BKDL manifest
|
||||
│ └── fs/ VFS + LittleFS bridge
|
||||
├── libs/
|
||||
│ ├── membrane/ POSIX adaptation layer
|
||||
│ │ ├── libc.nim Freestanding libc for Nim
|
||||
│ │ ├── net_glue.nim LwIP <-> kernel bridge
|
||||
│ │ └── compositor.nim Display compositor
|
||||
│ └── libertaria/ Libertaria Wire Format integration
|
||||
├── npl/nipbox/ NipBox userland shell (21 commands)
|
||||
├── apps/ Subject binaries, linker scripts
|
||||
└── vendor/ LwIP, LittleFS, mksh (vendored)
|
||||
```
|
||||
|
||||
## Key Features
|
||||
### Design Principles
|
||||
|
||||
- **Adaptive I/O**: War Mode (polling) ↔ Peace Mode (interrupts)
|
||||
- **Disruptor Ring**: Lock-free inter-fiber communication
|
||||
- **SipHash IDs**: Collision-resistant process identification
|
||||
- **Ed25519**: Only signed code executes
|
||||
- **Two-language split**: Zig for hardware (deterministic, zero-alloc), Nim for logic (expressive, ARC)
|
||||
- **Capability security**: CSpace + Pledge + BKDL manifests. No ambient authority.
|
||||
- **Spectrum scheduling**: 4-tier priority (Photon 2ms, Matter 10ms, Gravity 50ms, Void unlimited)
|
||||
- **System Truth Ledger**: Every security event recorded. Auditable kernel state.
|
||||
|
||||
## Specifications
|
||||
## NexusOS Workspace
|
||||
|
||||
- [SPEC-008: Architecture](/.agents/specs/SPEC-008-RUMPK-ARCHITECTURE.md)
|
||||
- [SPEC-009: I/O Subsystem](/.agents/specs/SPEC-009-RUMPK-IO.md)
|
||||
- [SPEC-010: Sovereign Hierarchy](/.agents/specs/SPEC-010-SOVEREIGN-HIERARCHY-V2.md)
|
||||
Rumpk is the kernel component of NexusOS. The full system consists of:
|
||||
|
||||
## Build (Coming Soon)
|
||||
| Repository | Purpose | Build |
|
||||
|------------|---------|-------|
|
||||
| [rumpk](https://git.sovereign-society.org/nexus/rumpk) | Kernel | `zig build` |
|
||||
| [nip](https://git.sovereign-society.org/nexus/nip) | Package manager | `nim c nip.nim` |
|
||||
| [nexus](https://git.sovereign-society.org/nexus/nexus) | Build toolkit | `nim c src/nexus.nim` |
|
||||
| [nipbox](https://git.sovereign-society.org/nexus/nipbox) | Userland shell | Built into rumpk via `build_full.sh` |
|
||||
| [nexfs](https://git.sovereign-society.org/nexus/nexfs) | Flash filesystem | `zig build test` |
|
||||
|
||||
### Clone All Repos
|
||||
|
||||
```bash
|
||||
cd core/rumpk
|
||||
zig build # Build L0 HAL
|
||||
nimble build # Build L1 Logic
|
||||
mkdir nexus-workspace && cd nexus-workspace
|
||||
for repo in rumpk nip nexus nipbox nexfs; do
|
||||
git clone https://git.sovereign-society.org/nexus/${repo}.git
|
||||
done
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) (coming soon).
|
||||
|
||||
## Stewardship
|
||||
|
||||
Copyright (c) 2025-2026 Markus Maiwald
|
||||
Stewardship: Self Sovereign Society Foundation
|
||||
|
|
|
|||
Loading…
Reference in New Issue