Skip to content

System Architecture

Jump to bottom
NtinosTheGamer2324 edited this page Apr 17, 2026 · 4 revisions

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:

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

Clone this wiki locally