MetalOS/docs/MINIMALISM.md

# MetalOS - Extreme Minimalism Guide

## What ABSOLUTE MINIMUM Means

We're not building a general-purpose OS. We're building **the smallest possible software layer** that lets QT6 Hello World run on AMD64 + RX 6600.

## Cut Everything

### ❌ NO Scheduler
- **Why not?**: One app = one process = always running
- **Instead**: Direct execution, no context switching
- **Saves**: Scheduler code, process queues, timer interrupts for scheduling

### ❌ NO Process Management
- **Why not?**: Only one process ever exists
- **Instead**: App runs in ring 0 (kernel mode) or simple ring 3 with static setup
- **Saves**: Process structures, fork/exec, process lifecycle

### ❌ NO File System
- **Why not?**: Everything loaded at boot
- **Instead**: App binary embedded in boot image or loaded by bootloader once
- **Saves**: VFS, inode structures, file descriptors, read/write/open/close

### ❌ NO Networking
- **Why not?**: Hello World doesn't need network
- **Instead**: Nothing
- **Saves**: TCP/IP stack, network drivers, sockets

### ❌ NO Security
- **Why not?**: Single app, demo system
- **Instead**: Trust everything
- **Saves**: Permissions, user/group IDs, capabilities, security modules

### ❌ NO Virtual Memory (maybe)
- **Why not?**: Could run everything with identity mapping
- **Instead**: Simple page tables just to keep CPU happy
- **Saves**: TLB management, page fault handling, swapping

### ❌ NO Dynamic Linking
- **Why not?**: Complexity nightmare
- **Instead**: Static link everything into one blob
- **Saves**: ELF loader complexity, PLT/GOT, symbol resolution at runtime

### ❌ NO Multi-core
- **Why not?**: One app on one core is plenty
- **Instead**: Use only bootstrap processor (BSP)
- **Saves**: SMP initialization, locks, atomic operations, IPI handling

### ❌ NO ACPI (mostly)
- **Why not?**: Complex and usually not needed for basic operation
- **Instead**: Minimal ACPI just for GPU if absolutely required
- **Saves**: AML interpreter, ACPI tables parsing, power management

### ❌ NO Signals/IPC
- **Why not?**: One process = nobody to talk to
- **Instead**: Nothing
- **Saves**: Signal handling, pipes, message queues, shared memory

### ❌ NO Timers (mostly)
- **Why not?**: QT6 needs *some* time, but minimal
- **Instead**: Simple timer for QT event loop only
- **Saves**: Complex timer infrastructure, high-resolution timers

## What We MUST Keep (Absolute Minimum)

### ✅ Memory Allocator
- **Why**: QT6 needs malloc/free
- **Minimum**: Simple bump allocator or basic free list
- **No need for**: Fancy algorithms, defragmentation, memory pools

### ✅ Interrupts
- **Why**: Keyboard/mouse input, timer for QT
- **Minimum**: 
  - Keyboard interrupt
  - Mouse interrupt  
  - Timer interrupt (for QT event loop)
  - GPU interrupt (if needed)
- **That's it!** Maybe 4-5 interrupt handlers total

### ✅ GPU Driver
- **Why**: Need to display graphics
- **Minimum**:
  - Initialize display pipeline
  - Set up framebuffer
  - Blit pixels to screen
- **No need for**: 3D acceleration, multiple displays, hot-plug

### ✅ Input Drivers
- **Why**: Need keyboard/mouse for QT events
- **Minimum**:
  - USB XHCI (or PS/2 if simpler!)
  - HID keyboard
  - HID mouse
- **No need for**: Other USB devices, complex HID parsing

### ✅ PCI Enumeration
- **Why**: Find the GPU
- **Minimum**: 
  - Scan bus for our specific GPU
  - Enable memory/IO access
- **No need for**: Full PCI tree, hot-plug, PCI-to-PCI bridges

### ✅ System Calls (bare minimum)
- **Why**: User space needs to talk to kernel
- **Minimum**:
  - `write()` - for debugging output
  - `mmap()` - for memory
  - `ioctl()` - for GPU/input
  - Maybe 5-10 syscalls total
- **No need for**: POSIX compatibility, 300+ syscalls

## Radical Simplifications

### Framebuffer Over Everything
- **Skip**: Complex GPU 3D acceleration
- **Use**: Direct framebuffer blitting
- **QT6**: Can render to memory, we copy to VRAM
- **Trade-off**: Slower but WAY simpler

### Identity Mapping (maybe)
- **Skip**: Complex virtual memory
- **Use**: Physical = Virtual (or simple offset)
- **Note**: x86-64 requires paging enabled, but can be trivial

### PS/2 Over USB
- **Skip**: Complex USB stack if possible
- **Use**: PS/2 keyboard/mouse if hardware supports
- **Simpler**: Direct port I/O vs USB protocol

### Polling Over Interrupts (where possible)
- **Skip**: Complex interrupt handling
- **Use**: Poll for events in tight loop
- **Trade-off**: CPU usage vs complexity

### Hardcode Everything
- **Skip**: Configuration files, boot parameters
- **Use**: Compiled-in constants
- **Examples**: 
  - Screen resolution: 1920x1080 (hardcoded)
  - GPU PCI ID: hardcoded
  - Memory layout: hardcoded

## Code Size Targets

Aim for **minimal code size**:

- **Bootloader**: < 10 KB
- **Kernel**: < 100 KB
- **GPU Driver**: < 50 KB (hardest part)
- **Input Drivers**: < 20 KB
- **QT6 + App**: ~10-20 MB (unavoidable - QT is big)

**Total OS (without QT)**: ~200 KB or less!

## Performance Targets

We don't care about performance, we care about **working**:

- Boot time: Don't care (< 30 seconds is fine)
- Frame rate: Don't care (30 FPS is plenty)
- Memory usage: Don't care (512 MB is plenty)
- CPU usage: Don't care (can peg one core)

**Trade complexity for simplicity every time.**

## Implementation Strategy

### Phase 1 ✅ (Done)
- Project structure
- Documentation

### Phase 2 (Bootloader)
- UEFI console output (for debugging)
- Load kernel blob
- Jump to kernel
- **Skip**: Complex file systems, just load from known location

### Phase 3 (Kernel)
- Set up page tables (minimal)
- Set up interrupts (only what we need)
- Memory allocator (simple bump allocator)
- **Skip**: Complex memory management

### Phase 4 (GPU)
- PCI scan for RX 6600
- Enable BAR
- Initialize display (hardcode 1920x1080)
- Framebuffer blit
- **Skip**: Everything else GPU can do

### Phase 5 (Input)
- Try PS/2 first (simpler!)
- If not available, minimal USB XHCI
- Keyboard scancodes -> QT key events
- Mouse packets -> QT mouse events
- **Skip**: Complex HID parsing, other devices

### Phase 6 (QT6)
- Port minimal QT6 (Core + Gui + Widgets only)
- QPA plugin: just framebuffer blit + input events
- Static link everything
- **Skip**: All optional QT modules

### Phase 7 (Integration)
- Link app with QT6
- Embed in boot image
- Test and debug
- **Skip**: Anything that doesn't work - iterate

## When in Doubt

Ask these questions:

1. **Does Hello World need this?** No → Cut it
2. **Can we hardcode this?** Yes → Hardcode it
3. **Can we do this simpler?** Yes → Do it simpler
4. **Does Linux do it complex?** Yes → Do it simpler anyway

## Bottom Line

**Build the smallest possible OS that boots QT6 Hello World.**

If it doesn't directly contribute to that goal, it doesn't exist.

No compromises. Maximum minimalism.