MetalOS/docs/ROADMAP.md

MetalOS Roadmap

Vision

MetalOS is the absolute minimum operating system needed to boot QT6 Hello World on AMD64 + RX 6600 via UEFI.

Target: < 200 KB of OS code (excluding QT6)

Philosophy: If it doesn't directly enable QT6 Hello World, it doesn't exist.

Development Phases

Phase 1: Foundation ✅ COMPLETE

Goal: Establish project structure and documentation

• Create project directory structure
• Write architecture documentation
• Define build system
• Create bootloader skeleton
• Create kernel skeleton
• Create QT6 hello world application template
• Document development workflow

Deliverables:

• ✅ Project structure in place
• ✅ Documentation framework
• ✅ Skeleton code for bootloader and kernel
• ✅ Build system (Makefiles, CMake, Conan)

Phase 2: UEFI Bootloader ✅ COMPLETE

Goal: Load kernel and jump (< 10 KB code)

Tasks:

• Console output for debugging (UEFI OutputString)
• Get framebuffer info from GOP (Graphics Output Protocol)
• Load kernel blob from known location
• Get minimal memory map
• Exit boot services
• Jump to kernel
• ACPI RSDP discovery (bonus)
• Multiple build system support (bonus)

Achievements:

• ✅ Complete UEFI bootloader implementation (~6.3 KB)
• ✅ Valid PE32+ EFI executable
• ✅ Comprehensive UEFI protocol definitions
• ✅ Support for Make, CMake, and Conan build systems
• ✅ Full documentation and testing

Success Criteria: ✅ Bootloader successfully loads kernel and provides boot information

Phase 3: Minimal Kernel (In Progress)

Goal: Initialize hardware (< 100 KB code)

Tasks:

1. Minimal paging setup

   • Identity map or simple offset
   • Just enough to keep CPU happy
   • No fancy page fault handling

2. Interrupt handling

   • IDT with handlers
   • Timer interrupt
   • Keyboard interrupt
   • Mouse interrupt
   • Basic interrupt framework

3. Memory allocator

   • Basic memory management structures
   • Bump allocator or simple free list
   • malloc/free for applications

4. Core Components

   • GDT (Global Descriptor Table)
   • IDT (Interrupt Descriptor Table)
   • APIC (Advanced Programmable Interrupt Controller)
   • PCI scanning
   • SMP/multicore support framework
   • Spinlocks for synchronization

Progress:

• ✅ Core kernel structure in place
• ✅ GDT and IDT setup
• ✅ Basic interrupt handling
• ✅ APIC initialization
• ✅ PCI device enumeration
• ✅ SMP/multicore support framework
• ⏳ Memory allocator needs completion
• ⏳ Device drivers need implementation

Success Criteria: Kernel boots, prints messages, mallocs work

Phase 4: Hardware Support

Goal: GPU + Input (< 70 KB code)

Tasks:

1. PCI scan (minimal)

   • Hardcode scan for vendor 0x1002 (AMD)
   • Find RX 6600 device ID
   • Enable memory access
   • That's it!

2. GPU Driver (hardest part, < 50 KB)

   • Map MMIO registers
   • Initialize display controller (DCN)
   • Hardcode 1920x1080 mode
   • Set up framebuffer in VRAM
   • Enable display output
   • Study Linux amdgpu driver, but keep it simple

3. Input devices (< 20 KB)

   • Try PS/2 first (much simpler than USB!)
   • If no PS/2: minimal USB XHCI for HID
   • Keyboard: scancode → QT key events
   • Mouse: packets → QT mouse events

Simplifications:

• No PCI tree traversal, just scan for our GPU
• No GPU 3D, just 2D framebuffer
• No hot-plug, no multiple displays
• PS/2 over USB if possible (way simpler)
• No timer sophistication, PIT is fine

Success Criteria: Display working, keyboard/mouse input working

Phase 5: Minimal Syscalls

Goal: User-kernel boundary (< 10 KB code)

Tasks:

1. Syscall mechanism (syscall/sysret or just direct calls)
2. Maybe 5-10 syscalls total:
   • write() - debugging
   • mmap() / munmap() - memory
   • ioctl() - device control
   • poll() - wait for input events
   • exit() - halt system

Simplifications:

• No syscall table if app can directly call kernel functions
• No parameter validation (trust everything)
• No error handling (just panic)

Success Criteria: App can call kernel functions

Phase 6: User Space & Application

Goal: Load and run app

Tasks:

1. Simple app loading

   • Static-linked binary
   • No ELF parsing if we can avoid it
   • Just jump to known entry point

2. C++ minimal runtime

   • Global constructors
   • Basic new/delete (use kernel malloc)
   • No exceptions (disable them)

3. Direct boot to app

   • No init, no shell
   • Kernel calls app's main() directly
   • App exits → kernel halts

Simplifications:

• Static link everything into one blob
• Skip ELF loader completely if possible
• No exceptions (compile with -fno-exceptions)
• App runs in ring 0 or simple ring 3

Success Criteria: Can run simple C++ program

Phase 7: QT6 Port

Goal: Port QT6 to MetalOS

Tasks:

1. QT6 dependencies

   • Port minimal C++ standard library
   • Port required libraries (zlib, png, freetype, etc.)
   • Only what QT6 absolutely needs

2. QT Platform Abstraction (QPA) Plugin

   • MetalOS platform plugin
   • Framebuffer graphics backend
   • Input event integration
   • Event loop integration with kernel

3. Build QT6 for MetalOS

   • Configure QT6 build system
   • Cross-compile QT6
   • Strip unnecessary modules
   • QtCore, QtGui, QtWidgets only

4. Test infrastructure

   • Simple QT apps for testing
   • Verify widgets render
   • Verify input works

Success Criteria: Simple QT6 applications can run

Phase 8: Integration & Polish

Goal: Get Hello World running perfectly

Tasks:

1. Build hello world application

   • Compile against MetalOS QT6
   • Static link everything
   • Create bootable image

2. Full-screen rendering

   • Ensure application fills screen
   • Proper resolution handling
   • Clean graphics output

3. Input handling

   • Keyboard input works
   • Mouse input works (if used by app)
   • Clean event handling

4. Performance tuning

   • Optimize critical paths
   • Reduce boot time
   • Smooth rendering

5. Testing

   • Test on QEMU
   • Test on real hardware (AMD64 + RX 6600)
   • Fix any hardware-specific issues

Success Criteria: QT6 Hello World runs full-screen on target hardware

Timeline Estimates

These are rough estimates for a single developer

• Phase 1: 1 week ✅ (Complete)
• Phase 2: 2-3 weeks ✅ (Complete)
• Phase 3: 3-4 weeks (In Progress)
• Phase 4: 4-6 weeks
• Phase 5: 1-2 weeks
• Phase 6: 2-3 weeks
• Phase 7: 6-8 weeks
• Phase 8: 2-3 weeks

Total: ~4-6 months of focused development

Status: Phase 2 complete, Phase 3 in progress with core kernel components implemented (GDT, IDT, interrupts, memory management, SMP support, PCI scanning).

Technical Challenges

Major Challenges

1. GPU Initialization: Radeon RX 6600 is a modern GPU with complex initialization. May need to study Linux amdgpu driver extensively.

2. QT6 Dependencies: QT6 has many dependencies. Need to port or stub out non-essential ones.

3. QPA Plugin: Creating a QT Platform Abstraction plugin from scratch is non-trivial.

4. Memory Management: Need working virtual memory before user space.

5. USB Stack: If using USB input, need minimal USB stack (XHCI for modern systems).

Risk Mitigation

• Start with serial/VGA console before GPU
• Use PS/2 input before USB if easier
• Test incrementally in QEMU before hardware
• Study existing minimal OS implementations
• Reference Linux kernel code (but don't copy)

Success Metrics

Minimal Success

• Boots on target hardware
• Displays something via GPU
• Can be interacted with via keyboard
• QT6 hello world shows text

Full Success

• Boots reliably on AMD64 + RX 6600
• Full screen 1920x1080 rendering
• Clean QT6 widget rendering
• Responsive input handling
• Boot time < 10 seconds

Resources Needed

Hardware

• AMD64 system with Radeon RX 6600 GPU
• USB keyboard and mouse
• Serial port (optional, for debugging)

Software

• Cross-compiler toolchain (x86_64-elf-gcc)
• QEMU with UEFI support
• GDB for debugging
• QT6 source code

Knowledge

• UEFI specification
• x86_64 architecture
• PCI/PCIe protocol
• AMD GPU documentation
• QT6 architecture
• OS development fundamentals

Design Decisions

1. File System: ❌ Not needed

   • Application embedded in boot image or loaded by bootloader
   • Everything in RAM

2. Command Line / Shell: ❌ Not needed

   • Boot directly into QT6 application
   • No init process, no shell

3. Networking: ❌ Not needed

   • Hello world doesn't need network

4. Dynamic Linking: ❌ Not needed

   • Static link everything for simplicity

5. SMP: ✅ Included

   • Multicore/SMP support implemented
   • Enables better performance and learning opportunities
   • Not strictly necessary but adds value

6. ACPI: ✅ Implemented

   • RSDP discovery in bootloader
   • Needed for hardware discovery

7. Multiple Applications: ❌ Not needed

   • One application only - the QT6 hello world

Contributing

This is a learning/demonstration project. Contributions welcome, but:

• Keep it minimal
• Every feature must justify its existence
• Ask "Does this help run QT6 hello world?" before adding anything
• Prefer simple over clever
• Document everything

References

• UEFI Specification
• OSDev Wiki
• AMD64 Manual
• Linux amdgpu driver
• QT6 Source
• QT QPA Documentation