MetalOS/docs/COMPONENTS.md

MetalOS - Planned Components

This document outlines the key components that need to be implemented.

Bootloader Components

Implemented

• Basic structure
• EFI types and definitions
• Entry point stub

TODO

• UEFI protocol implementations
  • Console I/O (OutputString, etc.)
  • Graphics Output Protocol
  • Simple File System Protocol
  • Memory allocation
• Graphics initialization
  • Mode enumeration
  • Mode selection
  • Framebuffer setup
• Kernel loading from disk
• Memory map retrieval
• Exit boot services
• Jump to kernel with boot info

Kernel Components

Core Kernel

Implemented

• Entry point
• Basic console output to framebuffer
• Boot info structure

TODO

• GDT (Global Descriptor Table) setup
• IDT (Interrupt Descriptor Table) setup
• Interrupt handlers (ISRs)
• Exception handlers
• Timer interrupt (for scheduling)

Memory Management

TODO

• Physical memory allocator
  • Parse UEFI memory map
  • Bitmap or buddy allocator
  • Page allocation (4KB pages)
• Virtual memory
  • Page table setup (4-level paging)
  • Kernel space mapping
  • User space mapping
• Heap allocator
  • Simple malloc/free
  • For kernel use

Process Management

TODO

• Process structure
• Thread structure
• Context switching
  • Save/restore CPU state
  • Stack switching
• Simple scheduler
  • Round-robin
  • Single user process initially
• User/kernel mode transitions

System Calls

TODO

• System call mechanism (syscall/sysret)
• System call table
• Essential syscalls:
  • exit()
  • write() - for debugging
  • mmap() - memory allocation
  • ioctl() - device control
  • poll() - wait for events

Hardware Abstraction Layer (HAL)

PCI Bus

TODO

• PCI configuration space access
• Device enumeration
• Find GPU (vendor 0x1002, device ID for RX 6600)
• BAR (Base Address Register) reading
• Enable memory and I/O access

GPU Driver (Radeon RX 6600)

This needs to be precise - based on actual AMD GPU specs.

TODO

• GPU identification
  • Check PCI vendor/device ID
  • Verify it's RX 6600 (Navi 23)
• Basic initialization
  • Map MMIO registers
  • Reset GPU if needed
  • Initialize display engine
• Display pipeline setup
  • Configure CRTC (display controller)
  • Set up display timing
  • Configure framebuffer
  • Enable output
• Framebuffer management
  • Allocate VRAM for framebuffer
  • Map to CPU address space
  • Set up for blitting

Note: This is the most complex part. Will need to reference:

• Linux amdgpu driver
• AMD register specifications
• Display Controller (DCN) documentation

Input Devices

TODO

• USB Stack (minimal)
  • XHCI controller initialization
  • USB device enumeration
  • HID class driver
• Keyboard driver
  • USB HID keyboard
  • Key code translation
  • Event generation for QT
• Mouse driver
  • USB HID mouse
  • Movement/button tracking
  • Event generation for QT

Timer

TODO

• APIC timer or PIT
• Timer interrupt setup
• Time tracking for scheduler

User Space

Runtime

TODO

• ELF loader
  • Parse ELF64 headers
  • Load program segments
  • Set up entry point
• C runtime
  • _start function
  • Call constructors
  • Call main()
  • Call destructors
• C++ runtime
  • Global constructors
  • Global destructors
  • Exception handling (minimal or disabled)
• Standard library subset
  • malloc/free
  • memcpy/memset/memcmp
  • String functions
  • Basic I/O

Application Launcher (No Init Needed)

TODO

• Direct kernel boot into application
• Load QT6 hello world as only user process
• No shell, no command line
• Handle application exit (just halt or reboot)

QT6 Port

Dependencies

TODO

• Identify minimal QT6 dependencies
• Port/stub required libraries:
  • zlib
  • libpng
  • freetype (fonts)
  • Others as discovered

QT Platform Abstraction (QPA)

TODO

• Create MetalOS QPA plugin
• Implement platform integration
  • Window system integration (full screen)
  • Event dispatcher
  • Backingstore (framebuffer backing)
• Graphics backend
  • Raster rendering to framebuffer
  • Optionally: GPU acceleration
• Input integration
  • Keyboard events
  • Mouse events
  • Event queue
• Font backend
  • Basic font rendering
  • Use embedded font or simple bitmap

QT Build

TODO

• Configure QT6 for MetalOS target
• Disable unnecessary modules
• Enable: QtCore, QtGui, QtWidgets only
• Cross-compile for MetalOS
• Static linking

Applications

Hello World

Implemented

• Basic QT6 hello world source code
• .pro file

TODO

• Build for MetalOS
• Static link with QT6
• Test rendering
• Test input handling
• Package into bootable image

Build System

Implemented

• Basic Makefiles
• Directory structure

TODO

• Cross-compiler setup scripts
• Image creation script
  • Create GPT disk image
  • Format EFI System Partition
  • Copy bootloader and kernel
• Automated testing in QEMU
• CI/CD pipeline (optional)

Documentation

Implemented

• README.md
• ARCHITECTURE.md
• BUILD.md
• DEVELOPMENT.md
• ROADMAP.md
• CONTRIBUTING.md

TODO

• API documentation
• Driver development guide
• Troubleshooting guide
• Performance tuning guide

Testing

TODO

• Unit tests for key components
• Integration tests
• QEMU boot tests
• Hardware test checklist

---

This is a living document - components will be checked off as implemented.