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
|
**Status:** Experimental — boots on QEMU, 14/14 fibers (riscv64), 9/9 fibers (aarch64)
|
||||||
**Languages:** Zig (L0) + Nim (L1)
|
**License:** [Libertaria Sovereign License (LSL) v1.0](LICENSE)
|
||||||
**Design:** POSIX-hostile, Military-grade
|
|
||||||
|
|
||||||
## 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/
|
rumpk/
|
||||||
├── boot/ [L0] Entry & Architecture (Zig/Asm)
|
├── boot/ L0: Entry points, linker scripts (Zig/ASM)
|
||||||
│ ├── start.S Multiboot2/EFI entry point
|
├── hal/ L0: Hardware Abstraction (Zig)
|
||||||
│ └── arch/ Architecture-specific code
|
│ ├── entry_riscv.zig RISC-V boot, MMU, page tables
|
||||||
├── hal/ [L0] Hardware Abstraction (Zig)
|
│ ├── entry_aarch64.zig ARM64 boot, MMU, GIC
|
||||||
│ ├── mm.zig Physical/Virtual Memory
|
│ ├── virtio_net.zig VirtIO network driver
|
||||||
│ ├── irq.zig Interrupt handling
|
│ ├── virtio_block.zig VirtIO block driver
|
||||||
│ ├── serial.zig UART/Early logging
|
│ ├── virtio_mmio.zig VirtIO MMIO transport (ARM64)
|
||||||
│ └── abi.zig C-ABI export to Nim
|
│ ├── virtio_pci.zig VirtIO PCI transport (RISC-V)
|
||||||
├── core/ [L1] Logic (Nim)
|
│ ├── mm.zig Memory management
|
||||||
│ ├── kernel.nim kmain() entry
|
│ ├── channel.zig IPC ring buffers
|
||||||
│ ├── sched.nim LWKT Scheduler
|
│ └── cspace.zig Capability space (HAL side)
|
||||||
│ ├── fiber.nim Fiber/Context management
|
├── core/ L1: Kernel logic (Nim)
|
||||||
│ └── ring.nim Disruptor buffer
|
│ ├── kernel.nim kmain, boot sequence
|
||||||
├── sys/ [L2] ABI Glue
|
│ ├── sched.nim Spectrum scheduler (Photon/Matter/Gravity/Void)
|
||||||
│ └── syscall.zig System call handlers
|
│ ├── fiber.nim Cooperative fiber management
|
||||||
├── payload/ [L3] NPL/NPK Loaders
|
│ ├── ion.nim ION memory allocator
|
||||||
│ └── loader.nim Signature verification
|
│ ├── cspace.nim Capability enforcement
|
||||||
└── io/ I/O Subsystem
|
│ ├── ontology.nim System Truth Ledger
|
||||||
└── governor.nim Adaptive War/Peace mode
|
│ ├── 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)
|
- **Two-language split**: Zig for hardware (deterministic, zero-alloc), Nim for logic (expressive, ARC)
|
||||||
- **Disruptor Ring**: Lock-free inter-fiber communication
|
- **Capability security**: CSpace + Pledge + BKDL manifests. No ambient authority.
|
||||||
- **SipHash IDs**: Collision-resistant process identification
|
- **Spectrum scheduling**: 4-tier priority (Photon 2ms, Matter 10ms, Gravity 50ms, Void unlimited)
|
||||||
- **Ed25519**: Only signed code executes
|
- **System Truth Ledger**: Every security event recorded. Auditable kernel state.
|
||||||
|
|
||||||
## Specifications
|
## NexusOS Workspace
|
||||||
|
|
||||||
- [SPEC-008: Architecture](/.agents/specs/SPEC-008-RUMPK-ARCHITECTURE.md)
|
Rumpk is the kernel component of NexusOS. The full system consists of:
|
||||||
- [SPEC-009: I/O Subsystem](/.agents/specs/SPEC-009-RUMPK-IO.md)
|
|
||||||
- [SPEC-010: Sovereign Hierarchy](/.agents/specs/SPEC-010-SOVEREIGN-HIERARCHY-V2.md)
|
|
||||||
|
|
||||||
## 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
|
```bash
|
||||||
cd core/rumpk
|
mkdir nexus-workspace && cd nexus-workspace
|
||||||
zig build # Build L0 HAL
|
for repo in rumpk nip nexus nipbox nexfs; do
|
||||||
nimble build # Build L1 Logic
|
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