Bare-Metal Architecture

How guideXOS runs directly on hardware

On This Page

What is Bare-Metal?

guideXOS is a fully bare-metal operating system written in C# that runs directly on x86/x64 hardware without any underlying OS layer. This means:

  • ❌ No Windows/Linux/macOS underneath
  • ❌ No hypervisor or emulation layer
  • ✅ Direct control of CPU, memory, and devices
  • ✅ Custom bootloader and kernel initialization
  • ✅ Runs on real hardware or VMs
⚡ Key Features:

- Custom kernel with direct hardware access
- Native device drivers compiled into kernel
- Custom memory allocator (no garbage collection)
- Full IPv4 network stack
- GUI system with window manager
- Custom .gxm executable format

NativeAOT Compilation

guideXOS uses Microsoft's NativeAOT (Native Ahead-of-Time compilation) instead of Cosmos:

How It Works

  1. Compiles C# directly to native x86/x64 machine code - No IL interpreter or JIT
  2. Provides low-level intrinsics - unsafe code, pointers, direct hardware access
  3. Removes .NET runtime dependencies - Custom CoreLib replaces standard libraries
  4. Zero garbage collection - Custom page-based allocator with explicit Free() calls
  5. Production-grade optimization - Microsoft's industrial-strength compiler

Build Configuration

<PackageReference Include="Microsoft.DotNet.ILCompiler" Version="7.0.0-alpha.1.22074.1" />

<PropertyGroup>
  <IlcSystemModule>guideXOS</IlcSystemModule>
  <EntryPointSymbol>Entry</EntryPointSymbol>
  <LinkerSubsystem>NATIVE</LinkerSubsystem>
  <IlcOptimizationPreference>Size</IlcOptimizationPreference>
</PropertyGroup>

Build Pipeline

C# Source Code
    ↓
NativeAOT Compiler (ILCompiler)
    ↓
Native x86/x64 Machine Code (.exe)
    ↓
Custom Bootloader (EntryPoint.asm)
    ↓
GRUB2 Bootloader
    ↓
Boots on Real Hardware or VM

Why NativeAOT vs Cosmos?

Feature Cosmos guideXOS (NativeAOT)
Compiler Custom IL-to-x86 translator Microsoft NativeAOT (official .NET)
Maturity Experimental/Educational Production-grade
Performance Slower, basic optimizations Fast, advanced optimizations
Code Quality Experimental Industrial-strength
Target Use Learning OS development Production bare-metal systems

Boot Sequence

Understanding how guideXOS boots from power-on to desktop: 

BIOS/UEFI
    ↓
GRUB2 Bootloader (from ISO)
    ↓
Load kernel.bin (bootloader + native exe)
    ↓
EntryPoint.asm (Assembly bootstrap)
    ↓
Kernel Entry Point (Program.Main in C#)
    ↓
├─ GDT.Initialize()          (Global Descriptor Table)
├─ IDT.Initialize()          (Interrupt Descriptor Table)
├─ PageTable.Initialize()    (Paging setup)
├─ Allocator.Initialize()    (Memory allocator)
├─ PCI.Initialise()          (Scan hardware)
├─ IDE.Initialize()          (Storage drivers)
├─ Timer.Initialize()        (HPET/APIC timers)
├─ Keyboard.Initialize()     (PS/2 keyboard)
├─ NETv4.Initialize()        (Network stack)
│   ├─ Intel825xx.Initialize()
│   └─ RTL8111.Initialize()
├─ Framebuffer.Initialize()  (Graphics)
├─ WindowManager.Initialize() (GUI system)
└─ Desktop.Initialize()      (Launch desktop)

Boot Stages Explained

  • GRUB2: Loads kernel.bin from ISO into memory at specified address
  • EntryPoint.asm: Sets up protected mode, enables paging, jumps to C# entry
  • GDT/IDT: Configure CPU segmentation and interrupt vectors
  • PageTable: Enable virtual memory with identity mapping
  • Allocator: Initialize 512MB page pool for memory management
  • Hardware Init: Detect and initialize all drivers
  • Desktop Launch: Start GUI and open Console window

Memory Layout

How memory is organized in guideXOS: 

0x00000000 ┌── Null page (unmapped)
            │
0x00100000 ├── Kernel code & data
            │
0x00400000 ├── Allocator page pool start
            │   (512MB of 4KB pages)
            │
0x20400000 ├── Allocator page pool end
            │
0xFD000000 ├── Framebuffer (MMIO)
            │
0xFFFFFFFF └── High memory

Memory Regions

  • Kernel: Native compiled code starts at 0x10000000 (linked with /base flag)
  • Page Pool: 131,072 pages × 4KB = 512MB for allocations
  • Framebuffer: Memory-mapped VGA/VESA video memory
  • Hardware MMIO: Device registers mapped to high addresses

Interrupt Handling

How hardware interrupts are processed: 

Hardware Interrupt
    ↓
IDT (Interrupt Descriptor Table)
    ↓
Save CPU state
    ↓
Call registered handler
    ├─ Timer.OnInterrupt() → Scheduler tick
    ├─ Keyboard.OnInterrupt() → Key event
    ├─ Intel825xx.OnInterrupt() → Network packet
    └─ ...
    ↓
Restore CPU state
    ↓
IRET (Return from interrupt)

Interrupt Vectors

  • 0x20 - Timer (1ms tick for scheduling)
  • 0x21 - Keyboard (PS/2 or USB HID)
  • 0x2C - Mouse (PS/2)
  • Custom - Network cards (Intel/Realtek)

Comparison with Standard OS

Feature Standard OS guideXOS
Driver Model Loadable kernel modules Compiled-in
Memory Virtual addresses + MMU Physical addresses
Allocation Heap (malloc/new) Page allocator
I/O System calls, HAL Direct port/MMIO
Interrupts Handler registration Direct IDT entries
DMA IOMMU translation Physical buffers
Networking Kernel stack + userspace Built-in IPv4 stack
Executables ELF/PE/Mach-O Custom .gxm format
Language C/C++/Rust C# + unsafe code
✅ Advantages:

- Simplified architecture (no layers)
- Predictable performance (no GC pauses)
- Fast boot time (2-5 seconds)
- Full hardware control
- Educational value

⚠ Trade-offs:

- No driver hot-loading
- Manual memory management
- Limited hardware support
- No process isolation (yet)
- Educational project status

Learn More

Driver System

PCI discovery and hardware drivers
Memory Management

Page allocator and memory tracking
Development Guide

Build from source and contribute