Kernel Architecture

Rumpk uses a four-layer architecture where each layer has a strict responsibility boundary.

The Four Layers

┌──────────────────────────────────┐
│  NPL / NPK  (Applications)      │  User Mode
│  Isolated fibers, sandboxed      │
├──────────────────────────────────┤
│  Kernel Protocol                 │  Stable contract
│  ION Rings + BKDL + cap verbs    │  Typed messages
├──────────────────────────────────┤
│  Trap ABI (SysTable)             │  Per-arch entry
│  ecall / svc / syscall           │  Implementation detail
├──────────────────────────────────┤
│  Rumpk (Kernel Logic)            │  Supervisor Mode
│  Scheduler, Memory, NetSwitch    │  Nim
├──────────────────────────────────┤
│  HAL (Hardware Abstraction)      │  Machine Mode
│  VirtIO, UART, GIC, Timer, MMU   │  Zig
├──────────────────────────────────┤
│  Rumkv (Hypervisor)              │  Highest Privilege
│  EL2 / Ring-1 / M-Mode           │  Optional
└──────────────────────────────────┘

The Kernel Boundary is a Protocol

The contract between userland and kernel is not a syscall table. It is a protocol: typed ION Ring packets, signed BKDL descriptors, and a small capability verb algebra. Languages and runtimes are transport adapters; the protocol is the stable surface that survives CPU changes, version changes, and language changes.

The SysTable described below is the Trap-ABI side of that protocol — the physical entry mechanism, not the contract itself.

SysTable — the Trap-ABI entry surface

The SysTable is a fixed 136-byte structure at a known physical address:

• RISC-V: 0x83000000
• ARM64: 0x50000000

It carries:

• Pointers to the ION Ring descriptors that back each well-known channel (RX, TX, event, command, input, semantic transport).
• Function pointers for the few fast-path operations that have not yet been re-expressed as ring messages (fn_vfs_open, fn_vfs_read, fn_vfs_write, fn_vfs_close, fn_pledge, fn_yield).
• Framebuffer info for the visual cortex.

The layout is fixed at boot and never reallocated. Validation is by magic number (0x4E585553, "NXUS"). The long-term direction is to migrate the remaining function pointers behind ring messages so the SysTable becomes purely a ring-descriptor table; until that migration lands, applications should target libnexus rather than the SysTable directly.

SMP — Message-Passing, Not Mutexes

Rumpk adopts the DragonflyBSD LWKT (Lightweight Kernel Threads) model for symmetric multiprocessing:

• CPU cores are isolated domains
• Data moves between cores via messages, not shared memory
• No mutexes, no spinlocks, no lock contention
• Linear scaling to 256+ cores

This means: data moves, code stays. A fiber runs on one core. If it needs something from another core, it sends a message through an ION Ring.

Memory Model — Cellular Memory

Memory is divided into two regions:

• Bridgehead: Fixed kernel memory, identity-mapped. Contains the SysTable, scheduler state, and ION Ring descriptors.
• Wild: Dynamic memory for fiber stacks, NPL heaps, and DMA buffers. Protected by PMP (Physical Memory Protection) on RISC-V or MPU on ARM64.

Each fiber gets its own memory partition. One fiber cannot access another's memory without an explicit capability grant.

Interrupt Architecture

Interrupts are handled in a two-phase model:

1. Phase 1 (Zig HAL): The interrupt vector catches the hardware event, acknowledges it (GIC claim on ARM64, PLIC claim on RISC-V), and pushes a minimal event descriptor onto the appropriate ION Ring.
2. Phase 2 (Nim Logic): The scheduler picks up the event and dispatches it to the correct fiber for processing.

This separation means interrupt handling is deterministic — the Zig layer does the absolute minimum, and all logic runs in the scheduler's cooperative context.

Privilege Modes

Rumpk uses hardware privilege modes for isolation:

Mode	RISC-V	ARM64	Role
Highest	M-Mode	EL2	Rumkv hypervisor
Supervisor	S-Mode	EL1	Rumpk kernel
User	U-Mode	EL0	NPL/NPK applications

Transitions between modes are how a fiber submits or awaits a protocol message. The Kernel Protocol itself is mode-agnostic — the same packet that crosses U→S on the same core can cross cell boundaries through the hypervisor without changing shape.