A Linux-like OS kernel entirely written in Rust
Default Platform: RISC-V 64-bit (RV64GC)
This project's code is developed with AI assistance (Claude Code + Opus4.6/GLM5.1/Minimax2.7).
- Uses Anthropic Claude Code CLI tool for assisted development
- Follows POSIX standards and maintains 100% Linux ABI compatibility
- Aims to explore the possibilities and limitations of AI-assisted OS kernel development
Core Objective: A Linux-compatible OS kernel written in Rust
- ✅ 100% POSIX Compatible - Full compliance with POSIX standards
- ✅ Linux ABI Compatible - Can run native Linux userspace programs directly
- ✅ System Call Compatible - Uses Linux system call numbers and interfaces
- ✅ Filesystem Compatible - Supports ext4 and other Linux filesystems
- ✅ ELF Format Compatible - Executable format identical to Linux
Design Philosophy:
- External interfaces must be 100% compatible with Linux
- Internal implementation can use better designs when it doesn't affect compatibility
- Welcoming improvements that maintain Linux ecosystem compatibility
| Metric | Value | Details |
|---|---|---|
| Lines of Code | ~86,600 lines | Code Structure |
| Source Files | 225 files (221 Rust + 3 ASM + 1 LD) | Project Structure |
| Kernel Tests | 53 test files | Testing Guide |
| Smoke Tests | 23 tests (all passing) | Testing Guide |
| mini-ltp | 25 compatibility tests | Testing Guide |
| Linux LTP | 1,838 official tests | Testing Guide |
| Platform Support | RISC-V 64-bit | Roadmap |
Module Distribution:
- Filesystem (fs/): 20,720 lines (23.9%)
- System Calls (syscall/): 7,546 lines (8.7%)
- Device Drivers (drivers/): 8,389 lines (9.7%)
- Memory Management (mm/): 7,592 lines (8.8%)
- Architecture (arch/): 7,003 lines (8.1%)
- Unit Tests (tests/): 7,376 lines (8.5%)
- Network Stack (net/): 5,177 lines (6.0%)
- Process Scheduling (sched/): 4,431 lines (5.1%)
- Top-level: 4,523 lines (5.2%)
- Process Management (process/): 2,827 lines (3.3%)
- Sync Primitives (sync/): 1,156 lines (1.3%)
# Rust toolchain (nightly recommended)
rustc --version
cargo --version
# QEMU system emulator
qemu-system-riscv64 --version
# RISC-V target
rustup target add riscv64gc-unknown-none-elf# Build kernel
make build
# Build userspace programs (shell, apps, mini-ltp, toybox)
make user
# Build Rootfs image
make rootfs
# Run kernel (default shell)
make run
# Run GUI desktop
make gui
# Run unit tests
make testFor detailed instructions: Getting Started Guide
██████ ██ ██ ██ ██
██ ██ ██ ██ ██ ██
██████ ██ ██ ███
██ ██ ██ ██ ██ ██
██ ██ ██████ ██ ██
[ RISC-V 64-bit | POSIX Compatible | v0.1.0 ]
Kernel starting...
Module Description Status
---------------- -------------------------------- --------
console: UART ns16550a driver [ok]
smp: 4 CPU(s) online [ok]
trap: stvec handler installed [ok]
trap: ecall syscall handler [ok]
mm: Sv39 3-level page table [ok]
mm: satp CSR configured [ok]
mm: buddy allocator order 0-12 [ok]
mm: heap region 32MB @ 0x80A00000 [ok]
mm: slab allocator 4MB [ok]
boot: FDT/DTB parsed [ok]
boot: cmd: root=/dev/vda rw init=... [ok]
mm: user frame allocator 64MB [ok]
mm: 32768 page descriptors [ok]
intc: PLIC @ 0x0C000000 [ok]
intc: external IRQ routing [ok]
ipi: SSIP software IRQ [ok]
bio: buffer cache layer [ok]
fs: ext4 driver loaded [ok]
fs: ramfs mounted / [ok]
fs: procfs initialized [ok]
fs: procfs mounted /proc [ok]
driver: virtio-blk PCI x1 [ok]
driver: GenDisk registered [ok]
fs: ext4 mounted / [ok]
fs: procfs remounted /proc [ok]
driver: virtio-net x1 [ok]
sched: CFS scheduler v1 [ok]
sched: runqueue per-CPU [ok]
sched: PID allocator init [ok]
sched: idle task (PID 0) [ok]
mm: PCP cpu2 hotpage [ok]
trap: sie.SEIE enabled [ok]
driver: virtio-gpu probed [ok]
gpu: 1280x800 32bpp framebuffer [ok]
fs: devfs mounted /dev [ok]
driver: evdev /dev/input/event0 [ok]
driver: evdev /dev/input/event1 [ok]
driver: PS/2 keyboard (stub) [ok]
driver: PS/2 mouse (stub) [ok]
init: loading /bin/shell [ok]
init: ELF loaded to user space [ok]
init: init task (PID 1) enqueued [ok]
========================================
Rux OS Shell v0.5 (musl libc)
========================================
Type 'help' for available commands
root#
Rux/
├── kernel/ # Kernel source (~86,600 lines)
│ ├── src/
│ │ ├── fs/ # Filesystem (20,720 lines)
│ │ │ ├── ext4/ # ext4 filesystem
│ │ │ ├── jbd2/ # JBD2 journaling layer
│ │ │ ├── devfs/ # devfs device filesystem
│ │ │ └── procfs/ # procfs process filesystem
│ │ ├── arch/ # RISC-V architecture (7,003 lines)
│ │ │ ├── mm/ # Arch-specific MM (pt, fixmap, ASID, page fault)
│ │ │ ├── boot.S # MMU trampoline, VMA/LMA linking
│ │ │ ├── trap.S # PtRegs save/restore, ret_from_fork
│ │ │ └── uaccess.S # User memory access assembly
│ │ ├── drivers/ # Device drivers (8,389 lines)
│ │ │ ├── gpu/ # GPU/framebuffer drivers
│ │ │ ├── input/ # Input device drivers
│ │ │ ├── virtio/ # VirtIO devices (blk/net/gpu/input)
│ │ │ └── net/ # Network devices
│ │ ├── mm/ # Memory management (7,592 lines)
│ │ │ ├── Zone allocator (DMA/DMA32/NORMAL/MOVABLE)
│ │ │ ├── vmemmap, buddy, slab, PCP, memblock
│ │ │ ├── VMA, mm_struct, page fault, COW
│ │ │ └── rmap, hugepage, meminfo
│ │ ├── tests/ # Unit tests (53 files, 7,376 lines)
│ │ ├── syscall/ # System calls (7,546 lines, 80+ syscalls)
│ │ ├── net/ # Network stack (5,177 lines)
│ │ ├── sched/ # Process scheduling (4,431 lines)
│ │ │ ├── CFS, RT (FIFO/RR), Deadline (EDF+CBS), Idle
│ │ ├── process/ # Process management (2,827 lines)
│ │ └── sync/ # Sync primitives (1,156 lines)
│ └── build.rs # Build script
├── userspace/ # Userspace programs
│ ├── shell/ # Default shell (musl libc)
│ ├── apps/ # GUI apps (desktop, calculator, clock, vshell)
│ ├── libs/gui/ # GUI library (rux_gui)
│ ├── tests/mini-ltp/ # Kernel compatibility tests (25)
│ ├── tests/smoke_test/ # Smoke tests (23 tests, all passing)
│ ├── linux-ltp/ # Official LTP tests (1,838)
│ └── toybox/ # Toybox (BusyBox alternative)
├── toolchain/ # Toolchain (musl libc)
├── docs/ # 📚 Documentation center
├── test/ # Test scripts
└── Cargo.toml # Workspace configuration
Detailed structure: Project Structure Documentation
- Process Management: fork/execve/wait4/signal handling/CFS scheduler/clone flags/gettid
- Memory Management: Sv39 page table/Zone allocator/vmemmap/PCP/COW/Demand paging/ASID/MAP_PRIVATE COW
- Filesystem: ext4/procfs/devfs/ramfs/JBD2 journaling
- Device Drivers: VirtIO-blk/net/gpu/input, framebuffer, evdev
- Network Stack: TCP/UDP/IPv4/ARP/Socket API
- SMP Multi-core: 4-core support/load balancing/IPI/per-CPU idle tasks
- Linux-Style Boot: MMU trampoline/VMA-LMA linking/PtRegs at stack top
- GUI: Desktop environment/calculator/clock/visual shell
Supports 80+ Linux system calls, including:
- File: openat/close/read/write/readv/writev/pread64/pwrite64/lseek/fstat/getdents64/mkdirat/rmdir/unlinkat/sendfile/statfs
- Process: fork/execve/wait4/exit/getpid/getppid/gettid/kill/clone/sched_yield
- Memory: brk (expand+shrink)/mmap/munmap (MAP_PRIVATE COW)/mprotect/mremap/madvise/msync
- Signal: sigaction/sigprocmask/sigreturn/sigaltstack/sigpending
- Network: socket/bind/listen/accept/connect/sendto/recvfrom
- IPC: pipe/pipe2/dup/dup3/select/poll/epoll/eventfd/futex
- Getting Started - Up and running in 5 minutes
- Roadmap - Phase planning and current status (Phase 30)
- Project Structure - Source code organization
- Design Principles - POSIX compatibility and Linux ABI alignment
- RISC-V Architecture - RV64GC support details
- Boot Process - MMU trampoline, VMA/LMA linking, page table init
- Memory Management - Zone allocator, vmemmap, COW, demand paging
- Changelog - Version history and update records
- Development Workflow - Contributing code and development standards
- Boot Process - From OpenSBI to kernel boot
- Test Count: 23 (all passing)
- Coverage: File I/O, process management, memory, signals, O_CLOEXEC, sendfile, wait4, process groups, setsid, credentials, readv/writev, gettid, pwrite64, dup3, kill, statfs, sched_yield
- Test Files: 53
- Coverage: Memory, process, filesystem, network, drivers, etc.
- Test Count: 25
- Coverage: Core system calls like fork, fileio, pipe, mmap, signal, execve
- Test Count: 1,838
- LTP Version: 20240524
- Compile Rate: 101% (musl libc cross-compilation)
- Coverage: Syscalls (1,378), memory (108), containers (46), filesystem (29), security (24), scheduler (23), IO (19)
Contributions are welcome! Please check the Roadmap for tasks that need help.
- Follow Conventional Commits specification
- Refer to Development Workflow for development standards
Core Principles:
- ✅ Strictly follow POSIX standards and Linux ABI
- ✅ External interfaces must be 100% compatible with Linux
- ✅ Internal implementation can use any design approach
- ✅ Welcoming any improvements that maintain compatibility
MIT License - See LICENSE for details
This project is inspired by:
Made with ❤️ and Rust + AI