CLUU is a hobby operating system written in Rust, pursuing a clean L4-style microkernel architecture with strong emphasis on correctness, minimality, and explicit authority. The project is deliberately engineered, test-driven, and uncompromising about architectural discipline.
This README reflects the current kernel status. The token system is complete and integrated. Core kernel subsystems are implemented, tested, and internally consistent.
Modern monolithic kernels are large, implicit, and difficult to reason about. CLUU intentionally moves in the opposite direction:
- minimal kernel surface
- explicit authority via capabilities / tokens
- message-passing as the primary abstraction
- aggressive separation between mechanism (kernel) and policy (userspace)
The goal is not speed of development, but clarity of design and long-term evolvability.
- Microkernel first – scheduler, memory, IPC, tokens, interrupts
- Everything else in userspace – filesystems, drivers, services
- Explicit authority – no ambient permissions, no global namespaces
- Deterministic control flow – no hidden work, no implicit magic
- SOLID by construction – traits, composition, strict responsibility
+-------------------------+
| Userspace |
|-------------------------|
| init | procmgr | vfs |
| ramfs | console | shell |
| cat | drivers | servers |
+----------- IPC ---------+
| Microkernel |
|-------------------------|
| Scheduler | IPC | VMM |
| PMM | Tokens | IRQ |
| Syscalls | Timer |
+-------------------------+
| Hardware |
+-------------------------+
The kernel provides mechanisms only. All policy lives in userspace.
| Subsystem | Status |
|---|---|
| Physical Memory (PMM) | ✅ Complete |
| Virtual Memory (VMM) | ✅ Complete |
| Address Spaces | ✅ Complete |
| Scheduler | ✅ Complete |
| IPC (rendezvous) | ✅ Complete |
| Capability / Token system | ✅ Complete |
| IRQ handling | ✅ Complete |
| Syscall infrastructure | ✅ Complete |
| Logging (IRQ-safe) | ✅ Complete |
| Userspace ABI | ✅ Stable |
Total kernel tests: 145/145 passing
Each process owns a strict address space:
USERSPACE
0x00000000 NULL guard
0x00400000 Text
0x00600000 Data / BSS
0x00800000 Heap (lazy)
0x7ff00000 Stack
KERNELSPACE (high half)
0xffff8000_00000000 physmap
0xffffffff_c0000000 kernel heap
- Lazy heap allocation via page faults
- Explicit validation of all user pointers
- No implicit memory sharing
- O(1) priority bitmap scheduler
- 256 priority levels
- FIFO fairness within same priority
- Cooperative + preemptive modes
- Clean separation between policy and mechanism
Ready queues: [256]
Priority bitmap: 256 bits
pick_next(): O(1)
IPC is synchronous rendezvous, inspired by L4:
Sender ----+ +---- Receiver
| |
+-- IPC +
| |
Sender <-- + + --> Receiver
- send / recv / call / reply / replyrecv
- optional buffer transfer
- copy / map / grant semantics
- deterministic blocking behavior
IPC is the only communication primitive.
All authority is represented by cryptographically signed tokens.
- Opaque, non-enumerable object references
- Explicit rights bitmask
- Mandatory expiration
- Delegation via derivation
- HMAC-SHA256 integrity
Tokens are conceptually similar to JWTs, but kernel-verified and capability-safe.
Token = {
scope : OpaqueScope,
rights : RightsMask,
issuer : Kernel | Authority,
expires : Timestamp,
sig : HMAC
}
No token → no authority → no operation.
Only 7 syscalls exist:
Send
Recv
Call
Reply
Yield
Invoke (all privileged operations)
DebugPrint (debug only)
All resource manipulation flows through sys_invoke() using tokens.
- Full x86_64 IDT
- All CPU exceptions handled
- Page faults integrated with VMM
- Timer IRQ drives preemption
- IRQ-safe logging (no locks, no allocation)
- Zero-cost in release builds
- IRQ-safe
- No allocation
- Manual formatting
- UART-backed
Logging is a diagnostic tool, not a runtime dependency.
Userspace programs are:
- statically linked ELF binaries
- no_std
- linked against
libcluu
libcluu provides:
- syscall wrappers
- IPC helpers
- error handling
- runtime entry point
CLUU uses the BOOTBOOT bootloader as its stage-2 boot mechanism.
BOOTBOOT provides a clean, modern boot environment and deliberately minimal abstractions, aligning well with CLUU’s microkernel philosophy.
Key BOOTBOOT features used by CLUU:
- High-half kernel loading
- Identity-mapped physmap
- Early UART debug support
- Framebuffer setup
- Initrd delivery
- Strict boot-time memory map
The kernel is loaded as sys/core from the initrd, following BOOTBOOT conventions. All early platform setup (CPU mode, paging, memory discovery) is delegated to BOOTBOOT, allowing the kernel to remain focused on core mechanisms only.
CLUU uses a thin build wrapper around Rust’s xtask pattern. The build system is intentionally explicit and scriptable, avoiding hidden magic.
cargo xtaskis the primary interfacemakeis provided only as a convenience wrapper- Kernel and userspace are built with custom Rust targets
- Disk images are produced via mkbootimg + BOOTBOOT
all: build
build:
cargo xtask build
run:
cargo xtask run
run-debug:
cargo xtask run --debug
test:
cargo xtask test
clean:
cargo xtask clean
userspace:
cargo xtask userspace
kernel:
cargo xtask kernelUsage summary:
make build # Build everything
make run # Build and run in QEMU
make run-debug # Run with GDB + telnet serial
make test # Run all tests
make clean # Clean artifacts
For idiomatic Rust development, prefer using cargo xtask directly:
cargo xtask build [--profile dev|release]
cargo xtask run [--profile dev|release]
cargo xtask run --debug
cargo xtask test
cargo xtask clean
cargo xtask userspace [--profile dev|release]
cargo xtask kernel [--profile dev|release]
Debug mode starts QEMU paused with:
- GDB server on
localhost:1234 - Telnet serial on
localhost:4321
Terminal 1: cargo xtask run --debug
Terminal 2: telnet localhost 4321
Terminal 3: gdb target/.../kernel-*.elf
(gdb) target remote :1234
(gdb) continue
The xtask binary orchestrates the full system build:
- Builds userspace programs (no_std ELFs)
- Builds the kernel (custom target)
- Assembles NASM sources
- Constructs initrd layout
- Invokes
mkbootimgto generatecluu.img - Launches QEMU (normal or debug)
xtask is intentionally boring and explicit: every step is visible, inspectable, and reproducible.
Working userspace shell executing:
$ cat file.txt
Demonstrates:
- scheduling
- IPC-based VFS
- zero-copy buffers
- userspace drivers
- token-based authority
- POSIX compatibility (explicitly not a goal)
- Monolithic drivers
- Implicit global state
- Fast iteration at the cost of clarity
If an operation is possible, the authority must be visible. If authority is visible, it must be explicit. If it is explicit, it must be minimal.
CLUU is intentionally slow, explicit, and strict — by design.
Active development. Architecture considered stable. Implementation continues in userspace.
