# System Architecture

This document describes the high-level architecture and design of ModuOS.

## Architecture Overview

ModuOS uses a **monolithic kernel** architecture where all core services and drivers run in kernel space (Ring 0). User applications run in user space (Ring 3) and communicate with the kernel through system calls.

```
┌─────────────────────────────────────────────────────────┐
│                   User Space (Ring 3)                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │  Shell   │  │  Games   │  │   Apps   │  │   ELF   │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │
└───────┼─────────────┼─────────────┼─────────────┼──────┘
        │             │             │             │
        └─────────────┴─────────────┴─────────────┘
             SYSCALL (int 0x80) OR SYSCALL/SYSRET
        ┌─────────────────────────────────────────────────┐
        │                                                 │
┌───────┼────────────────────────────────────────────────┼┐
│       │         Kernel Space (Ring 0)                  ││
│  ┌────▼────────────────────────────────────────────────▼┐│
│  │            System Call Interface (syscall.c)         ││
│  └────┬─────────────────────────────────────────────┬───┘│
│       │                                             │    │
│  ┌────▼──────────────┐      ┌──────────────────────▼──┐ │
│  │  Process Manager  │      │   Memory Management     │ │
│  │  - Scheduler      │      │   - Physical allocator  │ │
│  │  - Context Switch │      │   - Paging (PML4)       │ │
│  │  - ELF Loader     │      │   - Kernel Heap         │ │
│  └───────────────────┘      └─────────────────────────┘ │
│                                                          │
│  ┌────────────────────────────────────────────────────┐ │
│  │        Virtual File System (VFS) Layer             │ │
│  │  ┌──────────┐  ┌──────────┐  ┌─────────────────┐  │ │
│  │  │  FAT32   │  │ ISO9660  │  │  Mount Table    │  │ │
│  │  └────┬─────┘  └────┬─────┘  └────────┬────────┘  │ │
│  └───────┼─────────────┼─────────────────┼───────────┘ │
│          └─────────────┴─────────────────┘             │
│  ┌────────────────────────────────────────────────────┐ │
│  │              Device Drivers                        │ │
│  │  ┌─────────┐ ┌─────────┐ ┌────────┐ ┌──────────┐  │ │
│  │  │   ATA   │ │  AHCI   │ │  VGA   │ │   PS/2   │  │ │
│  │  └────┬────┘ └────┬────┘ └───┬────┘ └────┬─────┘  │ │
│  └───────┼───────────┼──────────┼───────────┼────────┘ │
│          └───────────┴──────────┴───────────┘          │
│  ┌────────────────────────────────────────────────────┐ │
│  │          Hardware Abstraction Layer                │ │
│  │  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐           │ │
│  │  │ IDT  │  │ IRQ  │  │ PIC  │  │ PCI  │           │ │
│  │  └──────┘  └──────┘  └──────┘  └──────┘           │ │
│  └────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
                         │
        ┌────────────────┴────────────────┐
        │       Hardware (Ring -1)        │
        │  CPU  │  RAM  │  Drives  │ I/O  │
        └─────────────────────────────────┘
```

## Core Components

### 1. Boot Subsystem
- **Location**: `src/arch/AMD64/boot/`
- **Purpose**: Initialize the CPU and transition to long mode
- **Components**:
  - `header.asm`: Multiboot2 header
  - `main.asm`: 32-bit bootstrap code
  - `main64.asm`: 64-bit kernel entry point

**Boot Flow**:
```
GRUB → Multiboot2 Header → 32-bit Protected Mode → 
Enable Paging → Long Mode → Kernel Main (kernel.c)
```

### 2. Memory Management
- **Location**: `src/kernel/memory/`
- **Purpose**: Manage physical and virtual memory

**Components**:
- **Physical Memory Manager** (`phys.c`):
  - Bitmap-based allocator
  - 4KB page granularity
  - Tracks free/used pages
  
- **Virtual Memory Manager** (`paging.c`):
  - 4-level paging (PML4 → PDPT → PD → PT)
  - Identity mapping for kernel
  - Higher-half kernel (optional)
  
- **Kernel Heap** (`kheap.c`):
  - Dynamic memory allocation
  - kmalloc/kfree interface
  - Alignment support

**Memory Layout**:
```
0x0000000000000000 - 0x00007FFFFFFFFFFF  User Space (128TB)
0xFFFF800000000000 - 0xFFFFFFFFFFFFFFFF  Kernel Space (128TB)
  0xFFFFFFFF80000000 - 0xFFFFFFFFFFFFFFFF  Kernel Code/Data
```

### 3. Process Management
- **Location**: `src/kernel/process/`
- **Purpose**: Multitasking and process scheduling

**Components**:
- **Process Manager** (`process.c`):
  - Process creation/termination
  - Process table (256 max processes)
  - File descriptor table per process
  
- **Scheduler**:
  - Round-robin with priority
  - Preemptive multitasking
  - Time slicing (10ms default)
  
- **Context Switcher** (`context_switch.asm`):
  - Save/restore CPU state
  - Stack switching
  - Preserves all registers and RFLAGS

**Process States**:
```
READY → RUNNING → BLOCKED/SLEEPING → READY
   ↓
ZOMBIE → TERMINATED
```

### 4. Interrupt Handling
- **Location**: `src/arch/AMD64/interrupts/`
- **Purpose**: Handle CPU exceptions and hardware interrupts

**Components**:
- **IDT** (`idt.c`): Interrupt Descriptor Table setup
- **ISR** (`isr.asm`): Interrupt Service Routines (0-31)
- **IRQ** (`irq.c`): Hardware interrupt handlers (32-47)
- **PIC** (`pic.c`): 8259 Programmable Interrupt Controller
- **Timer** (`timer.c`): PIT (Programmable Interval Timer)

**Interrupt Vector Table**:
```
0-31:  CPU Exceptions (Faults)
32-47: Hardware IRQs (PIC)
48+:   Software Interrupts
0x80:  System Call Interrupt
```

### 5. File System Layer
- **Location**: `src/fs/`
- **Purpose**: Abstract file system access

**Architecture**:
- **VFS Core** (`fs.c`): Mount slots + path resolution for `/...` and routing support for `$/...` (DevFS and mount views)
- **FAT32** (`fs/DOS/FAT32/`): MS-DOS file system
- **ISO9660** (`fs/ISOFS/`): CD-ROM file system
- **File Descriptors** (`fd.c`): Per-process file handles

**Mount System**:
```
Slot 0 (A:) → Drive 0, Partition 0 (FAT32)
Slot 1 (B:) → Drive 1, Partition 0 (ISO9660)
...
Slot 25 (Z:) → Boot Drive
```

### 6. Device Drivers

**Storage Drivers**:
- **ATA/ATAPI** (`drivers/Drive/ATA/`): IDE drives and CD-ROMs
- **AHCI/SATA** (`drivers/Drive/SATA/`): Modern SATA controllers
- **vDrive** (`drivers/Drive/vDrive.c`): Virtual drive abstraction

**Graphics Drivers**:
- **VGA** (`drivers/graphics/VGA.c`): Text mode 80x25
- **SQRM GPU modules** (`modules/`): Framebuffer GPU drivers (QXL, VMSVGA, MD VGA Compatible Display Driver)

**Input Drivers**:
- **PS/2** (`drivers/input/ps2/`): Keyboard and mouse
- **USB** (`drivers/USB/`): USB controllers (UHCI, OHCI, EHCI)

**System Drivers**:
- **PCI** (`drivers/PCI/`): Device enumeration
- **ACPI** (`drivers/power/`): Power management
- **RTC** (`drivers/Time/`): Real-time clock

### 7. System Call Interface
- **Location**: `src/kernel/syscall/`
- **Purpose**: User-kernel communication

**Mechanism**: Software interrupt (INT 0x80)

**Syscall Convention**:
```
RAX: Syscall number
RDI: Argument 1
RSI: Argument 2
RDX: Argument 3
RCX: Argument 4
R8:  Argument 5
R9:  Argument 6
Return: RAX
```

**Available Syscalls** (see `syscall_numbers.h`):
- Process control (exit, fork, exec)
- File I/O (open, close, read, write)
- Memory management (mmap, munmap)
- System information (getpid, uname)

### 8. Userland
- **Location**: `userland/`
- **Purpose**: User-space programs

**Programs**:
- `cat.c`: Display file contents
- `echo.c`: Print text
- `sh.c`: Simple shell
- `memtest.c`: Memory testing
- `zsfetch.c`: System information

**Build System**: Separate build with user-space linker script

## Design Decisions

### Why Monolithic?
- **Simplicity**: All code in kernel space, no IPC needed
- **Performance**: Direct function calls, no context switches
- **Learning**: Easier to understand and implement

### Why Not Microkernel?
- More complex IPC mechanisms
- Higher overhead for driver communication
- Requires mature message passing system

### Address Space
Currently uses a **flat memory model** with a single page table shared across all processes. Future versions may implement per-process page tables.

### Scheduling Algorithm
Round-robin with priority was chosen for:
- Simplicity and fairness
- Predictable behavior for debugging
- Easy to implement preemption

## Kernel Entry Point

The kernel starts at `kernel_main()` in `src/kernel/kernel.c`:

```c
void kernel_main(void) {
    // 1. Initialize COM ports (debug output)
    // 2. Parse Multiboot2 info
    // 3. Initialize memory management
    // 4. Set up interrupts (IDT, PIC, timer)
    // 5. Initialize drivers (PCI, ATA, AHCI, etc.)
    // 6. Mount file systems
    // 7. Initialize process manager
    // 8. Start scheduler
    // 9. Launch init process (shell)
}
```

## Data Flow Examples

### File Read Operation
```
User Program → syscall_read() → 
fd_read() → fs_read_file() → 
FAT32/ISO9660 driver → ATA/AHCI driver → 
Hardware
```

### Timer Interrupt
```
Hardware Timer → PIC → IDT Entry 32 → 
timer_handler() → scheduler_tick() → 
schedule() → context_switch() → 
Next Process
```

## Next Steps

- [Boot Process](Boot-Process.md) - Detailed boot sequence
- [Memory Management](Memory-Management.md) - Memory subsystem details
- [Process Management](Process-Management.md) - Multitasking internals
- [File Systems](File-Systems.md) - FS implementation