AionCore - RT Microkernel

A real-time microkernel with units, capabilities, and message-passing designed from the ground up for:

• Hard real-time guarantees
• Multi-core scalability
• Capability-based security
• Userspace services
• Formal verification potential

Quick Start

# Build
make

# Run in QEMU
make run

# Clean
make clean

First Boot

AionCore v0.1.0 booting in QEMU - showing HAL initialization, timer calibration, and real-time tick updates

Current Status

Phase 1: ✅ Foundation complete (HAL, per-CPU, IDT, VGA) Phase 2: ✅ Complete (Timer, PMM, MMU/paging) Phase 3.1: ✅ Preemptive multitasking working! Phase 3.2: ✅ Syscalls complete (INT 0x80) Phase 3.3: ✅ Ring 3 userspace working! Phase 3.4: 🔨 Next up (Per-task address spaces)

👉 See CURRENT_WORK.md for today's status and next steps.

Architecture

This is not a UNIX clone. Key concepts:

• Units: Isolated execution containers (not "processes")
• Threads: Execute within units
• Channels: Message-passing IPC
• Capabilities: Explicit access rights, no ambient authority
• No POSIX in kernel: POSIX is a userspace personality

The kernel is <10K LOC and provides only core primitives. Everything else (filesystems, drivers, services) runs in userspace.

Documentation

📂 docs/ - All documentation

Start here:

• 📍 CURRENT_WORK.md - What we're working on NOW
• 📔 DEVELOPMENT_LOG.md - Development narrative and history
• 📖 docs/DOCS.md - Documentation index
• 🎯 docs/VISION.md - Long-term vision and goals
• 🗺️ docs/IMPLEMENTATION_ROADMAP.md - Phase-by-phase plan

Design details:

• 🏗️ docs/ARCHITECTURE.md - Design principles
• 🔷 docs/UNITS_ARCHITECTURE.md - Units model
• ⏱️ docs/RT_CONSTRAINTS.md - Real-time requirements
• ✓ docs/FORMAL_VERIFICATION.md - Verification strategy
• 🌐 docs/MULTI_ARCH.md - Multi-architecture support

Development:

• 📝 docs/KERNEL_C_STYLE.md - C coding standards and rules
• 🧪 docs/TESTING.md - Unit testing guide
• 🐛 docs/ISSUES.md - Known issues and action items

Project Structure

kernel/
├── CURRENT_WORK.md          ← Start here for current status
├── DEVELOPMENT_LOG.md       ← Development narrative and history
├── README.md                ← You are here
├── Makefile                 ← Build system
├── grub.cfg                 ← GRUB configuration
├── .claude.md               ← Development workflow rules
│
├── arch/x86/                ← x86-specific code
│   ├── boot.s               │  Multiboot entry point
│   ├── hal.c                │  Hardware abstraction layer
│   ├── gdt.c                │  GDT and TSS setup
│   ├── idt.c / idt_asm.s    │  Interrupt handling
│   ├── timer.c              │  PIT + TSC calibration
│   ├── mmu.c                │  x86 paging/MMU
│   ├── context.s            │  Hybrid context switch (kernel/user)
│   ├── syscall.s            │  INT 0x80 syscall entry
│   ├── user_test.s          │  Ring 3 test program
│   └── linker.ld            │  Memory layout
│
├── core/                    ← Architecture-neutral kernel core
│   ├── init.c               │  Kernel entry and initialization
│   ├── percpu.c             │  Per-CPU data structures
│   ├── task.c               │  Task management
│   ├── scheduler.c          │  O(1) priority scheduler
│   ├── syscall.c            │  Syscall dispatcher and implementations
│   ├── user.c               │  Userspace task creation
│   ├── console.c            │  Console multiplexer
│   └── ktest.c              │  Unit testing framework
│
├── drivers/                 ← Device drivers (modular)
│   ├── vga/                 │  VGA text mode driver
│   │   ├── vga.c            │  VGA subsystem
│   │   ├── vga_text.c       │  Text mode implementation
│   │   └── vga_console.c    │  Console backend
│   └── serial/              │  Serial UART driver
│       ├── uart.c           │  8250/16550 driver
│       └── serial_console.c │  Console backend
│
├── lib/                     ← Kernel library functions
│   └── string.c             │  Safe string operations
│
├── mm/                      ← Memory management
│   └── pmm.c                │  Physical memory manager
│
├── tests/                   ← Unit tests
│   ├── test_main.c          │  Host test runner
│   ├── pmm_test.c           │  PMM unit tests
│   ├── scheduler_test.c     │  Scheduler unit tests
│   └── kprintf_test.c       │  kprintf unit tests
│
├── include/                 ← Public headers
│   ├── kernel/              │  Core kernel headers
│   │   ├── hal.h            │  HAL interface
│   │   ├── idt.h            │  Interrupt handling
│   │   ├── percpu.h         │  Per-CPU data
│   │   ├── task.h           │  Task management
│   │   ├── scheduler.h      │  Scheduler
│   │   ├── timer.h          │  Timer subsystem
│   │   ├── pmm.h            │  Physical memory
│   │   ├── mmu.h            │  Virtual memory
│   │   ├── console.h        │  Console multiplexer
│   │   └── types.h          │  Type definitions
│   ├── drivers/             │  Driver interfaces
│   │   ├── vga.h            │  VGA driver
│   │   └── serial.h         │  Serial driver
│   └── lib/                 │  Library headers
│       └── string.h         │  String functions
│
└── docs/                    ← Documentation
    ├── DOCS.md              │  Documentation index
    ├── VISION.md            │  Long-term vision
    ├── IMPLEMENTATION_ROADMAP.md  │  Development plan
    ├── UNITS_ARCHITECTURE.md      │  Units model details
    ├── RT_CONSTRAINTS.md          │  RT requirements
    ├── FORMAL_VERIFICATION.md     │  Verification strategy
    ├── MULTI_ARCH.md              │  Multi-arch support
    ├── ARCHITECTURE.md            │  Design principles
    └── ISSUES.md                  │  Issue tracking

Features

✅ Implemented (Phases 1-3.1)

Foundation & HAL:

• Hardware Abstraction Layer (HAL)
• Per-CPU data structures (cache-line aligned)
• IDT and interrupt handling (256 entries)
• Exception handlers with register dumps
• Safe string library (no strcpy/strcat)
• Lock-free per-CPU tracing

Drivers & Console:

• Modular VGA driver with kprintf
• Serial UART driver (8250/16550, 115200 baud)
• Console multiplexer (VGA + serial dual output)

Timing:

• PIT timer with TSC calibration (1000 Hz, microsecond precision)

Memory Management:

• Physical memory manager (PMM, bitmap-based)
• MMU with x86 paging (identity-mapped kernel)
• O(1) page map/unmap operations

Tasks & Scheduling:

• Task management (create, destroy, yield)
• O(1) scheduler (256 priority levels)
• Context switching (< 200 cycles, full EFLAGS/segment restore)
• Timer-driven preemptive multitasking (1000 Hz)
• Priority-based preemption with round-robin

Testing & Development:

• Unit testing framework (ktest)
• Host-side unit tests for logic validation
• Direct QEMU kernel boot (5x faster iteration)

🔨 In Progress (Phase 3.2)

• Syscall mechanism (INT 0x80 or SYSENTER/SYSEXIT)
• GDT with ring 3 segments
• TSS for kernel stack switching
• First userspace task (ring 3 transition)

📋 Planned

• Phase 3: Tasks, threads, scheduler, syscalls
• Phase 4: IPC, capabilities, message passing
• Phase 5: Userspace services
• Phase 6: SMP/multicore
• Phase 7: More userspace servers
• Phase 8: Advanced features (shared memory, IRQ caps)

Design Principles

1. Microkernel First - IPC and capabilities early, not late
2. Real-Time Throughout - Every path has bounded time
3. Userspace by Default - If it can be userspace, it must be
4. Per-CPU Everything - Minimize locking, maximize parallelism
5. Capability Security - No ambient authority
6. Small TCB - <10K LOC for verification
7. No POSIX in Kernel - Build as userspace personality

See docs/ARCHITECTURE.md for detailed rationale.

Real-Time Guarantees

Operation	Target	Status
Context switch	<200 cycles	Phase 3
Scheduler pick	<100 cycles	Phase 3
IPC send/recv	<500 cycles	Phase 4
IRQ dispatch	<100 cycles	✅ Ready
Interrupt latency	<10µs	Phase 2

See docs/RT_CONSTRAINTS.md for full requirements.

Building

Requirements

• i686-elf cross-compiler
• GNU Make
• GRUB tools (grub-mkrescue)
• QEMU (for testing)

Build Commands

# Full build
make

# Clean build
make clean && make

# Run in QEMU (direct kernel boot - fast)
make run

# Run in QEMU (GRUB/ISO boot)
make run-iso

# Run in QEMU (terminal only, no GUI)
make run-nographic

# Build and run with unit tests
make test

# Show help
make help

Development

Daily workflow:

1. Check CURRENT_WORK.md for current status
2. Read DEVELOPMENT_LOG.md to understand context and history
3. Follow docs/IMPLEMENTATION_ROADMAP.md for APIs
4. Follow docs/KERNEL_C_STYLE.md before/after coding
5. Follow docs/RT_CONSTRAINTS.md for performance
6. Update docs when completing work

Coding guidelines:

• Small functions (<50 LOC)
• No undefined behavior
• Bounded execution time (O(1) in RT paths)
• Document invariants
• Keep arch code in arch/
• All hardware access via HAL
• Write unit tests for new subsystems

See docs/KERNEL_C_STYLE.md for complete coding standards.

Contributing

This is an experimental kernel exploring modern OS design patterns. Key areas:

• Capability-based security
• Message-passing IPC
• Real-time scheduling
• Lock-free per-CPU patterns
• Formal verification techniques

See docs/VISION.md for the full design philosophy.

License

MIT License - Copyright (c) 2025 sistemica GmbH

See LICENSE for full details.

References

Influences:

• seL4 - Formally verified microkernel
• Fuchsia - Capability-based Zircon kernel
• QNX - Real-time microkernel
• MINIX - Pioneering microkernel design

Our twist:

• Units instead of processes
• Built for RT from day one
• Designed for formal verification
• No POSIX in kernel
• Per-CPU lock-free patterns
• Message-passing by default

---

Start exploring: Read CURRENT_WORK.md for what's happening now!