rustkernel/ARCHITECTURE.md

Rust Kernel Architecture

Project Structure

This Rust kernel project is organized as follows:

rust/
├── README.md           # Project overview and build instructions
├── Cargo.toml          # Root workspace configuration
├── Makefile           # Build automation
├── src/
│   └── lib.rs         # Top-level kernel library
├── kernel/            # Core kernel crate
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs     # Main kernel library
│       ├── prelude.rs # Common imports and macros
│       ├── error.rs   # Error handling
│       ├── types.rs   # Kernel data types
│       ├── memory/    # Memory management
│       ├── sync.rs    # Synchronization primitives
│       ├── process.rs # Process management
│       ├── scheduler.rs # Task scheduling
│       ├── device.rs  # Device management
│       ├── driver.rs  # Driver framework
│       ├── interrupt.rs # Interrupt handling
│       ├── console.rs # Console/logging
│       ├── module.rs  # Module system
│       ├── init.rs    # Initialization
│       ├── panic.rs   # Panic handler
│       └── arch/      # Architecture-specific code
├── modules/           # Loadable kernel modules
│   ├── Cargo.toml
│   └── src/
│       ├── hello.rs   # Hello world module
│       └── test.rs    # Test module
├── drivers/           # Device drivers
│   ├── Cargo.toml
│   └── src/
│       └── dummy.rs   # Example dummy driver
└── test.sh           # Build and test script

Design Philosophy

This kernel is designed with the following principles:

1. Memory Safety: Leveraging Rust's ownership system to prevent memory bugs
2. Zero-Cost Abstractions: High-level APIs without runtime overhead
3. Modularity: Clean separation between subsystems
4. Linux Compatibility: Similar APIs and concepts where applicable
5. Modern Design: Taking advantage of modern language features

Key Components

Core Kernel (kernel/)

• Memory Management: Page allocation, heap management, virtual memory
• Process Management: Process and thread abstractions
• Synchronization: Spinlocks, mutexes, and other primitives
• Device Framework: Generic device and driver abstractions
• Module System: Support for loadable kernel modules
• Error Handling: Comprehensive error types and Result-based APIs

Modules (modules/)

Loadable kernel modules that can extend kernel functionality:

• hello.rs: Simple demonstration module
• test.rs: Testing and validation module

Drivers (drivers/)

Device drivers implementing the kernel driver framework:

• dummy.rs: Example driver showing the driver API

Architecture Support

Currently includes basic support for:

• x86_64 (primary target)
• ARM64 (stub)
• RISC-V (stub)

Building and Testing

# Build everything
make

# Run tests
make test

# Check code quality
make clippy fmt-check

# Run the automated test script
./test.sh

Development Status

This is a foundational implementation demonstrating:

• ✅ Basic kernel structure and organization
• ✅ Memory management framework
• ✅ Module system with examples
• ✅ Driver framework
• ✅ Synchronization primitives
• ✅ Error handling
• ✅ Build system integration

Areas for future development:

• Complete memory management implementation
• Interrupt handling and timers
• Full scheduler implementation
• File system support
• Network stack
• Hardware abstraction layers
• Boot loader integration
• Performance optimization

Relationship to Linux Kernel

This project is inspired by the Linux kernel's Rust infrastructure (/linux/rust/) but is designed as a standalone kernel implementation. It demonstrates how modern Rust can be used for systems programming while maintaining the familiar concepts from traditional kernel development.

The module system and driver framework are designed to be conceptually similar to Linux while taking advantage of Rust's type system for additional safety guarantees.