Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Current Status

This page describes current repository behavior, not the full long-term design. For operational priority and open review items, read WORKPLAN.md and REVIEW_FINDINGS.md.

Implemented

Boot and Kernel Baseline

  • Limine boots the x86_64 kernel in QEMU.
  • The kernel initializes serial output, GDT, IDT, PIC, PIT, syscall MSRs, memory management, page tables, heap allocation, and the global capability registry.
  • The kernel creates its own page tables with per-section permissions and keeps the higher-half direct map for physical memory access.
  • SMEP/SMAP are enabled when the QEMU CPU advertises support.

Code: kernel/src/main.rs, kernel/src/arch/x86_64/, kernel/src/mem/.

Validation: cargo build --features qemu, make run.

Process and Userspace Runtime

  • Processes have isolated address spaces, per-process kernel stacks, CapSet bootstrap pages, capability rings, and local capability tables.
  • ELF loading supports static no_std userspace binaries and TLS setup.
  • capos-rt owns the userspace entry path, allocator initialization, ring-client access, typed clients, result-cap parsing, and owned-handle release.

Code: kernel/src/spawn.rs, kernel/src/process.rs, capos-rt/src/, init/src/main.rs, demos/.

Validation: make capos-rt-check, make run, make run-spawn.

Capability Ring and IPC

  • The shared ring ABI supports CALL, RECV, RETURN, RELEASE, and NOP transport operations.
  • cap_enter processes submissions and can block until completions arrive or a timeout expires.
  • Endpoints route ring-native IPC between processes.
  • Direct IPC handoff lets a blocked receiver run before unrelated round-robin work after a matching CALL arrives.
  • Transport errors and application exceptions are surfaced through CQEs and typed runtime client errors.

Code: capos-config/src/ring.rs, kernel/src/cap/ring.rs, kernel/src/cap/endpoint.rs, capos-rt/src/ring.rs, capos-rt/src/client.rs.

Validation: cargo test-ring-loom, make run.

Capabilities

Implemented kernel capabilities include:

  • Console for serial output.
  • FrameAllocator for physical frame grants.
  • Endpoint for IPC rendezvous.
  • VirtualMemory for anonymous user page map, unmap, and protect operations.
  • ProcessSpawner and ProcessHandle for init-driven child process creation and wait semantics.

Code: kernel/src/cap/console.rs, kernel/src/cap/frame_alloc.rs, kernel/src/cap/endpoint.rs, kernel/src/cap/virtual_memory.rs, kernel/src/cap/process_spawner.rs.

Validation: make run, make run-spawn, cargo test-lib.

Capability Transfer and Release

  • IPC CALL and RETURN support sideband transfer descriptors.
  • Copy and move transfer are implemented.
  • Move transfer reserves the sender slot until destination insertion and commit.
  • Transfer result caps carry interface ids to userspace.
  • CAP_OP_RELEASE removes local capability-table slots. Runtime owned-handle drop queues one local release, and Runtime::flush_releases() forces queued releases when code cannot wait for the next ring-client acquisition/drop.

Code: kernel/src/cap/transfer.rs, kernel/src/cap/ring.rs, capos-lib/src/cap_table.rs, capos-rt/src/ring.rs.

Validation: cargo test-lib, make run.

Manifest Tooling and Smokes

  • tools/mkmanifest turns system.cue into a Cap’n Proto boot manifest.
  • The build uses repo-pinned Cap’n Proto and CUE tool paths through the Makefile; direct mkmanifest invocation also rejects missing, unpinned, or version-mismatched CUE compilers.
  • Default QEMU smoke services cover CapSet bootstrap, Console paths, ring corruption handling, reserved opcodes, NOP, ring fairness, TLS, VirtualMemory, FrameAllocator cleanup, Endpoint cleanup, and cross-process IPC.
  • system-spawn.cue drives the ProcessSpawner smoke where init spawns endpoint, IPC, VirtualMemory, and FrameAllocator cleanup children and checks hostile spawn inputs.

Code: tools/mkmanifest/, system.cue, system-spawn.cue, demos/.

Validation: cargo test-mkmanifest, make generated-code-check, make run, make run-spawn.

Partially Implemented

Init-Owned Service Startup

init can use ProcessSpawner in the spawn smoke, but default make run still uses the kernel boot path to create all manifest services. The selected milestone is to make default boot use init to validate and execute the service graph.

Current blockers are tracked in WORKPLAN.md and REVIEW_FINDINGS.md. Manifest schema-version guardrails, BootPackage authority exposure to init, init-side manifest graph validation, ProcessSpawner badge attenuation, direct manifest-tool CUE pin enforcement, generic manifest spawning, and child-local FrameAllocator/VirtualMemory grants are in place for the spawn-manifest path. Remaining milestone work is legacy kernel service-graph retirement for the default boot path.

Hardware and Networking

The QEMU virtio-net path has legacy PCI config-space enumeration and a make run-net boot target. A virtio-net driver, smoltcp integration, ICMP, and TCP smoke are not implemented.

Code: kernel/src/pci.rs, kernel/src/arch/x86_64/pci_config.rs, tools/qemu-net-harness.sh.

Validation: make run-net, make qemu-net-harness for the existing PCI smoke path.

Security and Verification Track

The repo has Miri, proptest, fuzz, Loom, Kani, generated-code, dependency policy, trusted-build-input, panic-surface, and DMA-isolation work. Coverage is not complete for every trust boundary.

References: Trusted Build Inputs, Panic Surface Inventory, DMA Isolation, and Security and Verification Proposal.

Future Work

Future architecture includes generic manifest execution in init, service restart policy, capability-scoped system monitoring, notification objects, promise pipelining, epoch revocation, shared-buffer capabilities, scheduling-context donation, session quotas, SMP, storage and naming, userspace networking, cloud boot support, user identity, policy enforcement, boot-to-shell authentication, text shell launch, and broader language/runtime support.

Design references: