Project Moonshot: Rust Kernel

A minimal Linux-ABI-compatible kernel written in Rust. Boots x86_64, runs busybox shell, has networking. Target: usable.

What This Is

Not a Linux rewrite. A new kernel that implements enough of the Linux syscall ABI to run unmodified static Linux binaries (busybox, coreutils). Written in Rust for memory safety.

Planning Documents

Document	Purpose
DECISIONS.md	Architectural decisions, gap analysis, simplification rationale. Read first.
AGENT-GUIDE.md	Common context for every agent task — build env, constraints, conventions, repo structure
INTERFACES.md	Trait contracts and type definitions. Must be merged BEFORE parallel agent work begins.
epic-0-foundation.md	7 tasks — bare-metal boot, serial, interrupts, GDT/IDT, CI
epic-1-memory.md	7 tasks — frame allocator, page tables, heap, VMAs, demand paging
epic-2-process.md	10 tasks — processes, scheduler, context switch, ELF loading, clone/exec
epic-3-filesystem.md	10 tasks — VFS, ramfs, devfs, initramfs, FDs, pipes, path resolution
epic-4-userspace.md	8 tasks — syscall stubs, signals, TTY, poll, init process, busybox boot
epic-5-networking.md	8 tasks — PCI, virtio-net, smoltcp, sockets, DNS, DHCP
epic-6-blockio.md	6 tasks — virtio-blk, GPT, ext2 read/write
epic-7-hardening.md	7 tasks — SMP, APIC, ACPI, locking, OOM killer, panic handler

Stats

Metric	Value
Total tasks	63
Total estimated lines	~10,910
Epics	8 (0-7)
Critical path tasks	42 (Epics 0-4)
Critical path lines	~6,610
Key milestone	Epic 4, Task 4.7: busybox shell boots
Decisions documented	15 (see DECISIONS.md)
Gaps found and resolved	15 (see DECISIONS.md)

Architecture

┌─────────────────────────────────────────────────┐
│                   Userspace                      │
│  (unmodified Linux binaries: busybox, coreutils) │
├─────────────────────────────────────────────────┤
│              System Call Interface                │
│       (Linux-compatible: ~40-80 syscalls)        │
├──────────┬──────────┬──────────┬────────────────┤
│  Memory  │ Process  │   VFS    │   Networking   │
│  Manager │ Scheduler│          │  (smoltcp)     │
├──────────┴──────────┴──────────┴────────────────┤
│              Hardware Abstraction                 │
│  APIC, PCI, VirtIO (net + blk), UART, ACPI      │
├─────────────────────────────────────────────────┤
│          Boot (UEFI via bootloader crate)        │
└─────────────────────────────────────────────────┘

Epic Dependency Graph

Epic 0: Foundation (7 tasks) ───────────────────────→ Boot in QEMU
  │
  ├── Epic 1: Memory (7 tasks) ────────────────────→ Heap works
  │     │
  │     ├── Epic 2: Process (10 tasks) ────────────→ clone/exec works
  │     │     │
  │     │     ├── Epic 3: Filesystem (10 tasks) ───→ VFS + FDs work
  │     │     │     │
  │     │     │     └── Epic 4: Userspace (8 tasks) → ★ BUSYBOX BOOTS ★
  │     │     │
  │     │     └── Epic 7: Hardening (7 tasks) ─────→ SMP, stability
  │     │
  │     └── Epic 6: Block I/O (6 tasks) ──────────→ ext2, persistence
  │
  └── Epic 5: Networking (8 tasks) ───────────────→ TCP/IP works
       (needs Epic 2 for processes, Epic 3 for sockets-as-FDs)

Critical path to "usable": Epic 0 → 1 → 2 → 3 → 4 = 42 tasks, ~6,610 lines Full feature set: add Epics 5, 6, 7 in any order after Epic 4.

What Changed (v2 Refinement)

The original plan had 98 tasks. After gap analysis and simplification:

• 98 → 63 tasks (-36%) by merging sequential micro-tasks and grouping related syscalls
• 15 architectural decisions documented (fork strategy, clone vs fork, initramfs delivery, etc.)
• 15 gaps found and resolved (missing wait queues, user pointer helpers, writev, poll, clone, etc.)
• 2 optional tasks dropped (VGA console, slab allocator) from critical path
• Every task stays 100-400 lines — no task was merged past the size limit

See DECISIONS.md for the full gap analysis and rationale for every change.

Task Size and Agent Suitability

Every task is designed for an AI coding agent:

• 100-400 lines of code per task
• 1-5 files touched
• Interface contracts defined up front (see INTERFACES.md)
• Acceptance criteria are binary (compile check, unit test, QEMU boot test)
• Dependencies explicitly listed — agents can work in parallel on independent tasks
• Context specified — each task says which files to read and what reference material to use

Testing Strategy

Tier	How	When	Agent Can Run?
Tier 1: Unit tests	cargo test --lib (runs on host)	Pure logic: allocators, parsers, data structures	Yes
Tier 2: no_std check	cargo build --target x86_64-unknown-none	Every task	Yes
Tier 3: QEMU boot	tools/run-qemu.sh	Hardware-dependent: page tables, interrupts, drivers	Maybe (needs QEMU)

Design Principles

1. x86_64 only — no multi-arch until core is stable
2. Linux ABI, not Linux internals — compatible syscall interface, clean Rust internals
3. Safety first — minimize unsafe, isolate it in arch/ and drivers/ layers
4. Reuse crates aggressively — x86_64, bootloader, smoltcp, goblin, acpi
5. Incremental usability — each epic produces something bootable and testable
6. Decisions over ambiguity — every non-obvious choice is documented in DECISIONS.md

Go / No-Go Decision Points

After Epic	Question	Go If...
0	Is kernel dev in Rust enjoyable?	Having fun, learning
1	Is the memory model workable?	Unsafe contained, allocator stable
2	Can we context switch reliably?	No corruption, scheduler fair
4	Can busybox run?	This is "usable" — the primary goal
5	Is networking worth the effort?	Interesting, not just grinding syscalls

Key References

• Writing an OS in Rust — Phil Oppermann (covers Epic 0 + parts of Epic 1)
• Kerla — Linux-ABI Rust kernel (stalled, ~80 syscalls, great reference)
• Redox OS — Full Rust microkernel OS
• OSDev Wiki — OS development encyclopedia
• VirtIO Spec v1.1 — VirtIO device protocol
• Intel SDM / AMD Architecture Manual — hardware reference
• Linux kernel source — the syscall ABI spec is the implementation