English | 中文

SimpleKernel

Interface-Driven OS Kernel for AI-Assisted Learning | Multi-Architecture: RISC-V 64, AArch64

🤖 Design Philosophy: Define clear kernel interfaces, let AI generate the implementation — a new paradigm for learning operating systems

📖 Table of Contents

• ✨ Project Overview
• 🤖 AI-Oriented Design Philosophy
• 🏛️ Interface Architecture Overview
• 🏗️ Supported Architectures
• 🚀 Quick Start
• 📂 Project Structure
• 🎯 Learning Path
• 📦 Third-Party Dependencies
• 📝 Development Guide
• 🤝 Contributing
• 📄 License

✨ Project Overview

SimpleKernel is a modern OS kernel project designed for AI-assisted learning. Written in C++23, it supports RISC-V 64 and AArch64 architectures.

Unlike traditional OS teaching projects, SimpleKernel adopts an Interface-Driven design:

• The project body is interface definitions — complete header files (.h/.hpp) containing class declarations, pure virtual interfaces, type definitions, and Doxygen documentation
• Implementation is done by AI — you only need to understand the interface contracts, and let AI generate .cpp implementations from the interface docs
• Reference implementations for comparison — the project provides complete reference implementations to verify the correctness of AI-generated code

🌟 Core Highlights

Feature	Description
🤖 AI-First Design	Interface docs serve as prompts — AI can generate complete implementations directly from header files
📐 Interface-Implementation Separation	Headers contain only declarations and contracts; implementations live in separate .cpp files
🌐 Two-Architecture Support	RISC-V 64, AArch64 — one set of interfaces adapting to different hardware
🧪 Test-Driven Verification	GoogleTest test suites verify whether AI-generated implementations conform to interface contracts
📖 Complete Doxygen Documentation	Every interface has responsibility descriptions, preconditions, postconditions, and usage examples
🏗️ Engineering Infrastructure	CMake build, Dev Container environment, CI/CD, clang-format/clang-tidy

🤖 AI-Oriented Design Philosophy

Why "AI-Oriented"?

Traditional OS teaching projects follow: read code → understand principles → mimic and modify. This approach has several problems:

1. Kernel codebases are large — beginners easily get lost in implementation details
2. Modules are tightly coupled — difficult to understand individual subsystems independently
3. Implementing a module from scratch has a high barrier with long feedback cycles

SimpleKernel proposes a new paradigm: read interface → understand contract → AI implements → test verifies

┌─────────────────────────────────────────────────────────┐
│                 SimpleKernel Learning Flow                │
│                                                         │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐         │
│   │ 📐 Inter- │───▶│ 🤖 AI    │───▶│ 🧪 Test  │         │
│   │ face Hdrs │    │ Generates│    │ Verifies │         │
│   │ + Doxygen │    │ Impl     │    │ Contract │         │
│   │           │    │ (.cpp)   │    │ GoogleTest│         │
│   └──────────┘    └──────────┘    └──────────┘         │
│        │                               │                │
│        │         ┌──────────┐          │                │
│        └────────▶│ 📚 Ref   │◀─────────┘                │
│                  │ Impl     │                           │
│                  └──────────┘                           │
└─────────────────────────────────────────────────────────┘

Core Workflow

1️⃣ Read Interface, Understand Contract

Each module's header file contains complete interface documentation:

/**
 * @brief Interrupt subsystem abstract base class
 *
 * All architecture interrupt handlers must implement this interface.
 *
 * @pre  Hardware interrupt controller has been initialized
 * @post Can register interrupt handlers via RegisterInterruptFunc
 *
 * Known implementations: PLIC (RISC-V), GIC (AArch64)
 */
class InterruptBase {
public:
  virtual ~InterruptBase() = default;

  /// Execute interrupt handling
  virtual void Do(uint64_t cause, cpu_io::TrapContext* context) = 0;

  /// Register interrupt handler function
  virtual void RegisterInterruptFunc(uint64_t cause, InterruptFunc func) = 0;
};

2️⃣ Let AI Implement

Provide the header file as context to an AI (e.g., GitHub Copilot, ChatGPT, Claude) and ask it to generate the .cpp implementation. The Doxygen comments in the interface are the best prompt.

3️⃣ Test and Verify

Run the project's built-in test suite to verify the AI-generated implementation conforms to the interface contract:

cmake --preset build_riscv64
cd build_riscv64 && make unit-test

4️⃣ Compare with Reference Implementation

If tests fail, refer to the project's reference implementation for comparison and learning.

Integration with AI Tools

Scenario	Usage
GitHub Copilot	Open the header file, let Copilot auto-complete the implementation in the corresponding .cpp
ChatGPT / Claude	Paste header file contents as context, request a complete .cpp implementation
Copilot Chat / Cursor	Select the interface in the IDE, ask AI to explain contract meaning or generate implementation
Self-Study	Think about the implementation first, then let AI generate it, and compare differences

🏛️ Interface Architecture Overview

SimpleKernel's interfaces are organized into the following layers:

┌──────────────────────────────────────────┐
│          Application / Syscall Layer      │
│         syscall.h · SyscallInit          │
├──────────────────────────────────────────┤
│            Task Management Layer          │
│  TaskManager · SchedulerBase · Mutex     │
│  CfsScheduler · FifoScheduler · RR ...   │
├──────────────────────────────────────────┤
│          Memory Management Layer          │
│  VirtualMemory · PhysicalMemory          │
│  MapPage · UnmapPage · AllocFrame        │
├──────────────────────────────────────────┤
│          Interrupt / Exception Layer      │
│  InterruptBase · RegisterInterruptFunc   │
│  TimerInit · InterruptInit               │
├──────────────────────────────────────────┤
│               Device Framework Layer           │
│  DeviceManager · DriverRegistry               │
│  PlatformBus · Ns16550aDriver · VirtioBlk     │
├──────────────────────────────────────────┤
│       Architecture Abstraction (arch.h)   │
│  ArchInit · InterruptInit · TimerInit    │
│  EarlyConsole (auto-set during global    │
│               construction phase)         │
├──────────────────────────────────────────┤
│         Runtime Support Libraries         │
│  libc (sk_stdio.h, sk_string.h, ...)     │
│  libcxx (kstd_vector, __cxa_*, ...)      │
├──────────────────────────────────────────┤
│            Hardware / QEMU                │
│  RISC-V 64 · AArch64                    │
└──────────────────────────────────────────┘

Key Interface Files

Interface File	Responsibility	Implementation File
src/arch/arch.h	Architecture-independent unified entry	Each src/arch/{arch}/ directory
src/include/interrupt_base.h	Interrupt subsystem abstract base class	src/arch/{arch}/interrupt.cpp
src/device/include/device_manager.hpp	Device manager	header-only
src/device/include/driver_registry.hpp	Driver registry	header-only
src/device/include/platform_bus.hpp	Platform bus (FDT enumeration)	header-only
src/device/include/driver/ns16550a_driver.hpp	NS16550A UART driver	header-only (Probe/Remove pattern)
src/include/virtual_memory.hpp	Virtual memory management interface	src/virtual_memory.cpp
src/include/kernel_fdt.hpp	Device tree parsing interface	src/kernel_fdt.cpp
src/include/kernel_elf.hpp	ELF parsing interface	src/kernel_elf.cpp
src/task/include/scheduler_base.hpp	Scheduler abstract base class	cfs_scheduler.cpp etc.
src/include/spinlock.hpp	Spinlock interface	header-only (performance)
src/include/mutex.hpp	Mutex interface	src/task/mutex.cpp

📋 See docs/TODO_interface_refactor.md for the complete interface refactoring plan.

🏗️ Supported Architectures

Architecture	Boot Chain	Serial	Interrupt Controller	Timer
RISC-V 64	U-Boot + OpenSBI	SBI Call	Direct Mode	SBI Timer
AArch64	U-Boot + ATF + OP-TEE	PL011	GICv3	Generic Timer

🚀 Quick Start

📋 System Requirements

• Operating System: Linux (Ubuntu 24.04 recommended) or macOS
• Container Engine: Docker or compatible container runtime
• Toolchain: Included in Dev Container (GCC 14 cross-compilers, CMake, QEMU, etc.)
• AI Tools (recommended): GitHub Copilot / ChatGPT / Claude

🛠️ Environment Setup

Option 1: Using Dev Container (Recommended)

# 1. Clone the project
git clone https://github.com/simple-xx/SimpleKernel.git
cd SimpleKernel

# 2. Open in VS Code and reopen in container
#    Install Dev Containers extension, click the >< icon at bottom-left
#    Select "Reopen in Container"

# Or use CLI
npm install -g @devcontainers/cli
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash

Also supports GitHub Codespaces: Click Code → Codespaces → Create codespace on main

See Dev Container documentation for details.

Option 2: Local Environment

Refer to Toolchain Documentation for local development environment setup.

⚡ Build and Run

cd SimpleKernel

# Select target architecture (RISC-V 64 example)
cmake --preset build_riscv64
cd build_riscv64

# Build kernel
make SimpleKernel

# Run in QEMU emulator
make run

# Run unit tests (verify your implementation)
make unit-test

Supported Architecture Presets:

• build_riscv64 - RISC-V 64-bit architecture
• build_aarch64 - ARM 64-bit architecture

🎯 AI-Assisted Development Workflow

# 1. Open project in VS Code (GitHub Copilot extension recommended)
code ./SimpleKernel

# 2. Read interface definitions in header files (e.g., src/include/virtual_memory.hpp)

# 3. Create/edit the corresponding .cpp file, let AI generate implementation from the interface

# 4. Build and verify
cd build_riscv64 && make SimpleKernel

# 5. Run tests
make unit-test

# 6. Run in QEMU, observe behavior
make run

📂 Project Structure

SimpleKernel/
├── src/                        # Kernel source code
│   ├── include/                # 📐 Public interface headers (project core)
│   │   ├── virtual_memory.hpp  #   Virtual memory management interface
│   │   ├── kernel_fdt.hpp      #   Device tree parsing interface
│   │   ├── kernel_elf.hpp      #   ELF parsing interface
│   │   ├── spinlock.hpp        #   Spinlock interface
│   │   ├── mutex.hpp           #   Mutex interface
│   │   └── ...
│   ├── arch/                   # Architecture-specific code
│   │   ├── arch.h              # 📐 Architecture-independent unified interface
│   │   ├── aarch64/            #   AArch64 implementation
│   │   └── riscv64/            #   RISC-V 64 implementation
│   ├── device/                 # Device management framework
│   │   ├── include/            # 📐 Device framework interfaces (DeviceManager, DriverRegistry, Bus, etc.)
│   │   │   └── driver/         #   Concrete drivers (ns16550a_driver.hpp, virtio_blk_driver.hpp)
│   │   └── device.cpp          #   Device initialization entry (DeviceInit)
│   ├── task/                   # Task management
│   │   ├── include/            # 📐 Scheduler interfaces (SchedulerBase, etc.)
│   │   └── ...                 #   Scheduler implementations
│   ├── libc/                   # Kernel C standard library
│   └── libcxx/                 # Kernel C++ runtime
├── tests/                      # 🧪 Test suite
│   ├── unit_test/              #   Unit tests
│   ├── integration_test/       #   Integration tests
│   └── system_test/            #   System tests (QEMU-based)
├── docs/                        # 📚 Documentation
│   ├── TODO_interface_refactor.md  # Interface refactoring plan
│   └── ...
├── cmake/                      # CMake build configuration
├── 3rd/                        # Third-party dependencies (Git Submodule)
└── tools/                      # Build tools and templates

Directories/files marked with 📐 are interface definitions — these are what you should focus on reading.

🎯 Learning Path

We recommend learning and implementing modules in the following order:

Phase 1: Infrastructure (Boot)

Module	Interface File	Difficulty	Description
Early Console	src/arch/arch.h comments	⭐	Earliest output, understand global construction
Serial Driver	ns16550a_driver.hpp	⭐⭐	Implement Probe/Remove, understand device framework and MMIO
Device Tree Parsing	kernel_fdt.hpp	⭐⭐	Parse hardware info, understand FDT format
ELF Parsing	kernel_elf.hpp	⭐⭐	Symbol table parsing, used for stack backtrace

Phase 2: Interrupt System

Module	Interface File	Difficulty	Description
Interrupt Base	interrupt_base.h	⭐⭐	Understand unified interrupt abstraction
Interrupt Controller	Per-arch driver headers	⭐⭐⭐	GIC/PLIC hardware programming
Timer Interrupt	arch.h → TimerInit	⭐⭐	Timer configuration, tick-driven

Phase 3: Memory Management

Module	Interface File	Difficulty	Description
Virtual Memory	virtual_memory.hpp	⭐⭐⭐	Page table management, address mapping
Physical Memory	Related interfaces	⭐⭐⭐	Frame allocator, buddy system

Phase 4: Task Management (Thread/Task)

Module	Interface File	Difficulty	Description
Spinlock	spinlock.hpp	⭐⭐	Atomic operations, multi-core synchronization
Mutex	mutex.hpp	⭐⭐⭐	Task-blocking based lock
Scheduler	scheduler_base.hpp	⭐⭐⭐	CFS/FIFO/RR scheduling algorithms

Phase 5: System Calls

Module	Interface File	Difficulty	Description
System Calls	arch.h → SyscallInit	⭐⭐⭐	User/kernel mode switching

📦 Third-Party Dependencies

Dependency	Purpose
google/googletest	Testing framework
charlesnicholson/nanoprintf	printf implementation
MRNIU/cpu_io	CPU I/O operations
riscv-software-src/opensbi	RISC-V SBI implementation
MRNIU/opensbi_interface	OpenSBI interface
u-boot/u-boot	Universal bootloader
OP-TEE/optee_os	OP-TEE operating system
ARM-software/arm-trusted-firmware	ARM Trusted Firmware
dtc/dtc	Device Tree Compiler
MRNIU/bmalloc	Memory allocator
MRNIU/MPMCQueue	Lock-free MPMC queue
MRNIU/device_framework	Device management framework

📝 Development Guide

🎨 Code Style

• Language Standard: C23 / C++23
• Coding Standard: Google C++ Style Guide
• Auto Formatting: .clang-format + .clang-tidy
• Comment Standard: Doxygen style; interface files must contain complete contract documentation

Naming Conventions

Type	Style	Example
Files	lower_snake_case	kernel_log.hpp
Classes/Structs	PascalCase	TaskManager
Functions	PascalCase / snake_case	ArchInit / sys_yield
Variables	snake_case	per_cpu_data
Macros	SCREAMING_SNAKE	SIMPLEKERNEL_DEBUG
Constants	kCamelCase	kPageSize
Kernel libc/libc++ headers	libc: sk_ prefix, libcxx: kstd_ prefix	sk_stdio.h / kstd_vector

📋 Git Commit Convention

<type>(<scope>): <subject>

type: feat|fix|docs|style|refactor|perf|test|build|revert
scope: optional, affected module (arch, device, libc)
subject: max 50 chars, no period

📚 Documentation

• Toolchain: docs/0_工具链.md
• System Boot: docs/1_系统启动.md
• Debug Output: docs/2_调试输出.md
• Interrupts: docs/3_中断.md
• Dev Container: docs/docker.md
• Interface Refactoring Plan: docs/TODO_interface_refactor.md

🤝 Contributing

We welcome all forms of contributions!

🎯 Ways to Contribute

Method	Description
🐛 Report Issues	Report bugs via GitHub Issues
📐 Improve Interfaces	Suggest better interface abstractions and documentation improvements
🧪 Add Tests	Write more comprehensive test cases for existing interfaces
📖 Improve Documentation	Enhance Doxygen comments, add usage examples
🔧 Submit Implementations	Submit reference or alternative implementations of interfaces

🔧 Code Contribution Workflow

1. Fork this repository
2. Create a feature branch: git checkout -b feat/amazing-feature
3. Follow coding standards during development
4. Ensure all tests pass
5. Commit changes: git commit -m 'feat(scope): add amazing feature'
6. Create a Pull Request

📄 License

This project is dual-licensed:

• Code License - MIT License
• Anti-996 License - Anti 996 License

---