Architecture

cupid-os is a monolithic, single-address-space, ring-0 operating system for 32-bit x86. Every component - kernel, drivers, shell, applications - runs in the same flat memory space with full hardware access.

---

Boot Sequence

BIOS loads boot.asm at 0x7C00 (real mode, 16-bit)
    │
    ├── Set up stack at 0x7C00
    ├── Load kernel from disk (sectors 1+) to 0x10000
    ├── Set 640×480×32bpp via Bochs VBE I/O ports (0x01CE/0x01CF)
    ├── Read VBE LFB address from PCI BAR0 → store at 0x0500
    ├── Set up GDT (flat model: code + data segments)
    ├── Switch to protected mode (CR0 bit 0)
    └── Far jump to kernel entry at 0x10000
            │
            ├── idt_init()          - Interrupt Descriptor Table
            ├── pic_init()          - PIC remapping (IRQ0→32, IRQ8→40)
            ├── irq_init()          - IRQ handler registration
            ├── pmm_init()          - Physical memory manager
            ├── paging_init()       - Identity-mapped 4KB pages (32MB)
            │                         + maps VBE LFB region from 0x0500
            ├── heap_init()         - Kernel heap (2MB) with canaries
            ├── keyboard_init()     - PS/2 keyboard (IRQ1)
            ├── pit_init()          - PIT at 100Hz (IRQ0)
            ├── serial_init()       - COM1 at 115200 baud
            ├── rtc_init()          - CMOS Real-Time Clock
            ├── fat16_init()        - FAT16 filesystem + block cache
            ├── fs_init()           - In-memory filesystem
            ├── vfs_init()          - Virtual File System
            │   ├── Register ramfs, devfs, fat16 filesystem types
            │   ├── Mount ramfs at /
            │   ├── Create /bin, /tmp, /home directories
            │   ├── Mount devfs at /dev (null, zero, random, serial)
            │   ├── Mount fat16 at /home (ATA disk)
            │   └── Pre-populate /LICENSE.txt, /MOTD.txt
            ├── process_init()      - Process table, idle process (PID 1)
            ├── Register desktop as PID 2
            ├── vga_init_vbe()      - Init 640×480 32bpp framebuffer
            ├── mouse_init()        - PS/2 mouse (IRQ12)
            └── desktop_run()       - Main event loop

---

Memory Layout

0x00000000 ┌──────────────────────────┐
           │ Interrupt Vector Table   │ (not used - we use IDT)
0x00000500 ├──────────────────────────┤
           │ VBE LFB address          │ ← Written by bootloader
0x00001000 ├──────────────────────────┤
           │ Kernel Code + Data       │ ← Loaded by bootloader
           │ (.text, .data, .bss)     │ ← starts at 0x10000
           ├──────────────────────────┤
           │ Boot Stack               │ ← 0x7C00 (real mode)
0x00110000 ├──────────────────────────┤
           │ Stack Guard Region       │ ← 512KB kernel stack
0x00190000 ├──────────────────────────┤
           │ Kernel Heap              │ ← kmalloc/kfree, 2MB
           │ (canary-protected)       │ ← includes VBE back buffer
           ├──────────────────────────┤
           │ Process Stacks           │ ← kmalloc'd, 4KB+ each
           │ (canary at bottom)       │
0x000A0000 ├──────────────────────────┤
           │ VGA Text Memory          │ ← Text mode (legacy)
0x00100000 ├──────────────────────────┤
           │ Extended Memory          │ ← PMM bitmap manages this
           │ (pages allocated here)   │
0x02000000 ├──────────────────────────┤
           │ End of managed memory    │ (32MB total)
           └──────────────────────────┘
           ·
           · (unmapped gap)
           ·
0xFD000000 ┌──────────────────────────┐
           │ VBE Linear Framebuffer   │ ← 640×480×4 = 1.2MB
           │ (identity-mapped by      │   PCI BAR0, QEMU default
           │  paging_init)            │
0xFD140000 └──────────────────────────┘

---

Component Architecture

Kernel Core

Component	Files	Purpose
Kernel entry	kernel.c/h	VGA, init sequence, main print functions
IDT	idt.c/h	Interrupt descriptor table setup
ISR/IRQ	isr.asm, irq.c/h	Interrupt/exception dispatching
PIC	pic.c/h	Programmable interrupt controller
Memory	memory.c/h, paging.c	PMM, heap, paging, canaries, leak detection
VFS	vfs.c/h	Virtual filesystem, mount table, path resolution
Panic	panic.c/h, assert.h	Crash handler, assertions
Strings	string.c/h	strlen, strcmp, memcpy, memset
Math	math.c/h	64-bit division, itoa, hex printing

Drivers

Driver	Files	IRQ	Purpose
Keyboard	keyboard.c/h	IRQ1	PS/2 input with modifiers
Mouse	mouse.c/h	IRQ12	PS/2 mouse with cursor
Timer	timer.c/h, pit.c/h	IRQ0	100Hz PIT, uptime, sleep
VGA	vga.c/h	-	VBE 640×480 32bpp, double buffering
ATA	ata.c/h	-	PIO disk read/write
Serial	serial.c/h	-	COM1 logging
Speaker	speaker.c/h	-	PC speaker tones
RTC	rtc.c/h	-	CMOS real-time clock

Subsystems

Subsystem	Files	Purpose
Shell	shell.c/h	38-command interactive shell with CWD support
CupidScript	cupidscript*.c/h	Bash-like scripting language
Ed Editor	ed.c/h	Unix ed(1) line editor
VFS	vfs.c/h	Virtual File System with mount table and path resolution
RamFS	ramfs.c/h	In-memory filesystem (root, /bin, /tmp)
DevFS	devfs.c/h	Device filesystem (/dev/null, zero, random, serial)
FAT16 VFS	fat16_vfs.c/h	FAT16 VFS wrapper for /home
FAT16	fat16.c/h, blockdev.c/h, blockcache.c/h	FAT16 driver with block cache
In-Memory FS	fs.c/h	Legacy read-only system file table
Exec	exec.c/h	CUPD program loader
Process Mgr	process.c/h, context_switch.asm	Scheduler, context switching
GUI	gui.c/h, desktop.c/h, graphics.c/h, font_8x8.c/h	Window manager, desktop
Terminal	terminal_app.c/h	GUI terminal application
Notepad	notepad.c/h	Text editor application (VFS file dialog)
Clipboard	clipboard.c/h	System clipboard
Calendar	calendar.c/h	Calendar math, time/date formatting, popup state

---

Interrupt Map

IRQ	Vector	Handler	Purpose
IRQ0	32	timer_callback	PIT timer tick (100Hz), scheduler flag
IRQ1	33	keyboard_handler	PS/2 keyboard input
IRQ12	44	mouse_handler	PS/2 mouse input
-	0	division_error	Divide by zero exception
-	6	invalid_opcode	Invalid opcode exception
-	13	general_protection	GPF
-	14	page_fault	Page fault (with CR2 reporting)

---

Execution Model

cupid-os uses deferred preemptive multitasking:

1. PIT IRQ0 fires every 10ms → sets need_reschedule flag
2. Flag is checked at safe voluntary points only:
   • Desktop main loop (before HLT)
   • process_yield() calls
   • Idle process loop
3. Context switch happens via pure assembly context_switch():
   • Save EBP, EDI, ESI, EBX, EFLAGS on current stack
   • Store ESP into old process PCB
   • Load new process ESP and jump to new EIP

This avoids the complexity and stack corruption risks of switching inside interrupt handlers.

---

CupidScript Execution Pipeline

.cup file on disk
      │
      ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│    Lexer     │───▶│    Parser    │───▶│  Interpreter │
│ (tokenize)   │     │ (build AST)  │     │ (execute AST)│
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                           ┌──────────────────────┤
                           ▼                      ▼
                    ┌──────────────┐     ┌──────────────┐
                    │   Runtime    │     │    Shell     │
                    │ (variables,  │     │ (execute_    │
                    │  functions)  │     │  command())  │
                    └──────────────┘     └──────────────┘

---

See Also

• Getting Started - Build and run
• Process Management - Scheduler details
• Filesystem - Disk I/O architecture
• Debugging - Memory safety and crash testing