From d0f6d3e7ac3e4335fc9b29fe1d9f7d37b8c857e5 Mon Sep 17 00:00:00 2001 From: Markus Maiwald Date: Mon, 16 Feb 2026 09:15:05 +0100 Subject: [PATCH] docs: rewrite README with actual build instructions and architecture --- README.md | 143 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 105 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 21c8358..113f5cd 100644 --- a/README.md +++ b/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