Kenix

A microkernel written in Rust for AArch64, featuring L4-style synchronous IPC, user-space device drivers, and a VFS layer with FAT32 support.

Current Status

The kernel boots on QEMU virt and runs multiple user-space servers:

• Console server - UART driver, handles stdin/stdout
• VFS server - Virtual filesystem with ramfs and FAT32
• Block device server - VirtIO-blk driver
• Network device server - VirtIO-net driver
• Init process - System tests and process spawning

Tested features: IPC, shared memory, pipes, file operations, process spawn/execve.

Target

• QEMU virt (dev)
• Raspberry Pi 4/5 (planned)
• ARM Chromebook (planned)

Prerequisites

# Rust nightly
rustup override set nightly
rustup component add rust-src

# QEMU
brew install qemu  # macOS
apt install qemu-system-aarch64  # Linux

# mtools (for FAT32 disk images)
brew install mtools  # macOS
apt install mtools   # Linux

Build & Run

# Build the kernel and user-space programs
make

# Run on QEMU (recommended - direct kernel boot)
make run-kernel

# Run with UEFI bootloader (WIP - currently a stub)
make fetch-ovmf
make run

Sample Output

[console] Server started
[vfs] Server started
[blkdev] VirtIO ready
[netdev] MAC: 52:54:00:12:34:56
[pipeserv] ok, ready!

=== Init Process ===
Testing IPC, VFS, Spawn
--- Basic VFS Test ---
Read /hello.txt: Hello from ramfs!
--- Pipe Test ---
Created pipe: read_fd=3, write_fd=4
Read from pipe: Hello, pipe!
--- Fork Test ---
[parent] fork() returned child PID=8
[child] I'm the child! PID=8
[parent] Child exited with status=0
--- Spawn Test ---
[hello] I was spawned!
[hello] My PID is: 9
=== Init complete ===

Project Structure

kenix/
├── boot/               # UEFI bootloader
├── kernel/             # Microkernel core
│   └── src/
│       ├── main.rs        # Kernel entry point
│       ├── mm/            # Memory management (paging, frames)
│       ├── sched/         # Scheduler and task management
│       ├── exception/     # Exception/interrupt handling
│       ├── ipc.rs         # IPC syscalls
│       ├── shm.rs         # Shared memory
│       ├── syscall.rs     # Syscall dispatcher
│       ├── gic.rs         # ARM GIC driver
│       ├── timer.rs       # ARM timer driver
│       ├── elf.rs         # ELF loader
│       ├── irq.rs         # IRQ-to-task routing
│       └── pipe.rs        # Kernel-level pipes
├── user/               # User-space programs (all Rust)
│   ├── libkenix/          # Shared runtime library
│   │   ├── Cargo.toml
│   │   └── src/lib.rs        # Syscalls, IPC, SHM wrappers
│   ├── console/           # Console server
│   │   ├── Cargo.toml
│   │   └── src/main.rs       # UART driver, IPC message loop
│   ├── init/              # Init process
│   │   ├── Cargo.toml
│   │   └── src/main.rs       # System tests, VFS client
│   ├── vfs/               # VFS server
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── main.rs       # VFS server, mount points
│   │       ├── blk_client.rs # Block device IPC client
│   │       └── fat32/        # FAT32 filesystem
│   ├── blkdev/            # Block device server
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── main.rs       # IPC server loop
│   │       ├── virtio_mmio.rs # VirtIO MMIO registers
│   │       ├── virtqueue.rs  # Virtqueue management
│   │       └── blk.rs        # VirtIO-blk protocol
│   ├── netdev/            # Network device server
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── main.rs       # IPC server loop
│   │       ├── virtio_mmio.rs # VirtIO MMIO registers
│   │       ├── virtqueue.rs  # Virtqueue management
│   │       └── net.rs        # VirtIO-net protocol
│   ├── pipeserv/          # Pipe server (unused, kernel pipes preferred)
│   │   ├── Cargo.toml
│   │   └── src/main.rs
│   ├── hello/             # Test program for spawn
│   │   ├── Cargo.toml
│   │   └── src/main.rs
│   ├── user.ld            # Shared linker script
│   ├── aarch64-kenix-user.json  # Custom target spec
│   └── Cargo.toml         # Workspace root
├── docs/               # Documentation
│   ├── syscalls.md        # System call reference
│   ├── ipc-protocols.md   # IPC message formats
│   └── journal/           # Development notes
├── scripts/            # Build scripts
│   └── create_disk.sh     # FAT32 disk image creation
└── Makefile

Roadmap

Core Kernel

• UEFI boot
• UART output
• Physical memory management (frame allocator)
• Paging (MMU, 2MB blocks)
• 4KB page support (L3 tables)
• Exception handler
• Preemptive scheduler (round-robin, timer-based)

User Space

• User-space tasks (EL0)
• ELF loader
• Syscall interface
• Pure Rust user-space (libkenix)

IPC

• Synchronous IPC (call/recv/reply)
• Inline message passing (24 bytes)
• Shared memory IPC
• Asynchronous notifications (notify/wait_notify)

Servers

• Console server (UART)
• VFS server (ramfs + FAT32)
• Block device server (VirtIO-blk)
• Network device server (VirtIO-net)
• FAT32 filesystem

File Descriptors

• Per-task fd table
• stdin/stdout/stderr
• read() syscall
• write() syscall
• close() syscall
• pipe() syscall (kernel-level pipes)
• dup/dup2/dup3 syscalls

Process Management

• spawn() syscall (create process from ELF in memory)
• execve() syscall (execute program from VFS path)
• getpid() syscall
• exit() syscall
• brk() syscall (heap management)
• getcwd/chdir syscalls (working directory)
• fork() syscall (copy-on-write not yet implemented, full copy)
• wait/waitpid syscalls

Memory Management

• Demand paging
• Copy-on-write (COW)
• Swapping

Hardware Support

• VirtIO-blk driver (block device)
• VirtIO-net driver (network)
• ARM GIC (Generic Interrupt Controller)
• ARM timer interrupts (preemption)
• VirtIO interrupt-driven I/O
• Raspberry Pi 4/5 support
• ARM Chromebook support

Security & Robustness

• Capability-based security
• Resource limits
• Watchdog / task monitoring

Developer Experience

• GDB stub for kernel debugging
• Kernel symbols for crash dumps
• Performance tracing