Rux

<div align="center">

A Linux-like OS kernel entirely written in Rust

Default Platform: RISC-V 64-bit (RV64GC)

</div>

---

🤖 AI Generation Statement

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

---

🎯 Project Goals

⚠️ Core Principle: Full POSIX/ABI Compatibility

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

---

📊 Project Status

| 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%)

---

🚀 Quick Start

Prerequisites

# 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 and Run

# 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 test

For detailed instructions: Getting Started Guide

---

🏆 Shell Boot Log

██████  ██    ██ ██   ██
██   ██ ██    ██  ██ ██
██████  ██    ██   ███
██   ██ ██    ██  ██ ██
██   ██  ██████  ██   ██
  [ 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#

GUI Boot

<img width="1362" height="1070" alt="image" src="https://github.com/user-attachments/assets/a485db2a-ab4e-4123-a67e-24fbf5d43752" />

---

📁 Project Structure

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

---

✨ Key Features

Implemented Features

• 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

System Calls

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