A modern, 32-bit operating system written in C and x86 Assembly that combines clean design with nostalgic aesthetics. The project implements core OS functionality while serving as both a learning platform and a foundation for experimental OS concepts. Inspired by systems like TempleOS and OsakaOS, cupid-os aims to provide a transparent, hands-on environment where users can directly interact with hardware.
- Custom bootloader with protected mode transition
- Comprehensive interrupt handling system
- Advanced PS/2 keyboard driver with full US layout support
- High-precision programmable timer system
- VGA text mode graphics with custom character rendering
The goal of cupid-os is to create an accessible, well-documented operating system that serves as both a learning platform and a foundation for experimental OS concepts. Drawing inspiration from TempleOS, OsakaOS, and classic game systems, it focuses on combining technical excellence with an engaging user experience.
cupid-os embraces a philosophy of complete user empowerment and transparency, inspired by TempleOS. Like TempleOS, cupid-os gives users full, unrestricted access to the entire system:
- No security boundaries or privilege levels - all code runs in ring 0
- Direct hardware access from user programs
- Full memory access with no virtual memory restrictions
- Complete visibility into and control over all system internals
- No artificial limitations or "protections" getting in the way
The goal is to create a pure, simple environment where users have complete freedom to explore, experiment, and truly understand how their computer works at the lowest level. While this approach sacrifices security and isolation, it maximizes learning potential and enables direct hardware manipulation that modern OSes restrict.
This design choice reflects our belief that users should be trusted and empowered rather than constrained. For educational and experimental purposes, having full access to bare metal is invaluable.
With that being said cupid-os also will have a mix of influence from mostly Linux and UNIX-like systems, with some visual and other inspiration coming from both templeOS, and OsakaOS.
-
boot/
boot.asm– Bootloader that sets up the environment, loads the kernel, and switches to protected mode.
-
kernel/
kernel.c– Main kernel file handling VGA initialization, timer calibration, and overall system startup.idt.c/h– IDT setup and gate configuration.isr.asm– Assembly routines for common ISR/IRQ stubs.irq.c/h– IRQ dispatch and handler installation.pic.c/h– PIC (Programmable Interrupt Controller) initialization and masking functions.math.c/h– Math utilities including 64-bit division, itoa, and hex printing.shell.c/h– A basic shell interface that handles user input and simple commands.string.c/h– Basic string manipulation functions.cpu.h– CPU utility functions (includingrdtscand CPU frequency detection).kernel.h– Core kernel definitions and shared globals (e.g., VGA parameters).
-
drivers/
keyboard.c/h– PS/2 keyboard driver with enhanced key support (arrow keys, delete, and modifiers).timer.c/h– Timer functions including sleep/delay, tick counting, and multi-channel support.pit.c/h– PIT configuration and frequency setup.speaker.c/h– PC speaker driver with tone and beep functionality.
-
link.ld – Linker script defining the kernel image layout.
-
Makefile – Build configuration that compiles the bootloader, kernel, and drivers into a bootable image.
-
LICENSE – GNU General Public License v3.
-
Custom Bootloader & Protected Mode Transition
- Loads at
0x7C00and sets up a simple boot message. - Loads the kernel from disk and switches from 16-bit real mode to 32-bit protected mode.
- Sets up a Global Descriptor Table (GDT) for proper memory segmentation.
- Loads at
-
Interrupt & Exception Handling
- Comprehensive Interrupt Descriptor Table (IDT) configuration.
- Exception handlers with detailed error messages.
- IRQ management with PIC remapping and custom handler registration.
- A common ISR/IRQ stub that saves processor state before dispatch.
-
PS/2 Keyboard Driver
- Full US keyboard layout support.
- Interrupt-driven input processing (IRQ1) with scancode-to-ASCII conversion.
- Enhanced Key Handling:
- Support for modifier keys (Shift, Ctrl, Alt, Caps Lock) with proper state tracking.
- Extended key support including arrow keys and the delete key.
- Circular buffer implementation for key event storage.
- Configurable key repeat and debouncing via timestamping.
-
Timer & CPU Calibration
- Uses the Intel 8253/8254 Programmable Interval Timer (PIT) for system timing.
- Provides system tick counters, sleep/delay functions, and multi-channel timer callbacks.
- High-Precision Timing:
- Calibrates using the CPU’s Time Stamp Counter (TSC) to measure the CPU frequency.
- Exposes
get_cpu_freq()andget_pit_ticks_per_ms()for accurate timing calculations.
-
VGA Text Mode Graphics
- Basic VGA driver for an 80×25 text display.
- Functions for printing characters, strings, and integers.
- Automatic screen scrolling and hardware cursor updates.
-
PC Speaker Driver
- Implements basic tone and beep functionality.
- Supports configuring PIT channel 2 to generate square waves for sound output.
-
Shell Interface
- Now Implemented: A simple command-line shell with a prompt and basic command parsing.
- Currently supports an
echocommand (with room for future expansion).
-
Utility Libraries
- Math Library: Includes 64-bit division (
udiv64), integer-to-string conversion (itoa), and hexadecimal printing. - String Library: Implements basic functions like
strlenandstrcmp.
- Math Library: Includes 64-bit division (
The development roadmap outlined below represents our current plans and priorities. However, it's important to note that this roadmap is flexible and will evolve based on:
- New requirements discovered during development
- Technical challenges and learning opportunities encountered
- Community feedback and contributions
- Integration needs between different system components
- Performance optimization requirements
- Hardware support requirements
- Testing and debugging needs
As we progress, new phases and tasks may be added, existing ones may be modified, and priorities may shift to ensure we're building the most robust and useful system possible.
-
Interrupt Handling (✅ Complete)
- ✅ Implement IDT (Interrupt Descriptor Table)
- ✅ Set up basic exception handlers
- ✅ Handle hardware interrupts
- ✅ Implement PIC configuration
- ✅ Add detailed error messages for exceptions
- ✅ Support for custom interrupt handlers
- ⭕ Basic boot sequence logging
-
Keyboard Input (✅ Complete)
- ✅ Implement PS/2 keyboard driver
- ✅ Basic input buffer
- ✅ Scancode handling
- ✅ Input event processing
- ✅ Keyboard state management
- ✅ Modifier key support (Shift, Caps Lock)
- ✅ Additional modifier keys (Ctrl, Alt)
- ✅ Key repeat handling
- ✅ Function keys support
- ✅ Extended key support
- ✅ Key debouncing
- ✅ Circular buffer implementation
- ⭕ Arrow keys
-
Timer Support (🔄 In Progress)
- ✅ PIT (Programmable Interval Timer) implementation
- ✅ Basic system clock
- ✅ Timer interrupts
- ✅ System tick counter
- ✅ Sleep/delay functions
- ✅ Timer calibration
- ✅ Multiple timer channels
- ✅ Variable frequency support
- X PC Speaker support [WILL BE SUPPORTED LATER]
- 🔄 High-precision timing modes
-
Memory Management (⭕ Planned)
- ⭕ Physical memory manager
- ⭕ Simple memory allocation/deallocation
- ⭕ Basic paging setup
- ⭕ Memory protection
- ⭕ Heap management
- ⭕ Memory mapping
- ⭕ Virtual memory support
- ⭕ Memory statistics tracking
-
Shell Interface (🔄 In-Progress)
- ✅ Basic command parsing and prompt display.
- ✅ Currently supports the
echocommand. - ⭕ Advanced command parsing
- ⭕ Basic shell commands
- ⭕ Command history
- ⭕ Tab completion
-
Process Management (⭕ Planned)
- ⭕ Process creation/termination
- ⭕ Basic scheduling
- ⭕ Process states
- ⭕ Context switching
-
Basic Device Drivers (⭕ Planned)
- ✅ PS/2 Keyboard
- ⭕ VGA graphics
- ⭕ Serial port
- ⭕ Real-time clock
-
Simple Filesystem (⭕ Planned)
- ⭕ Basic file operations
- ⭕ Directory structure
- ⭕ File permissions
- Custom compiler
- Advanced memory management
- Extended device support
- Multi-process scheduling
- Custom music program in dedication to Terry A. Davis
- NASM (Netwide Assembler) for bootloader compilation
- GCC (32-bit support required)
- GNU Make
- QEMU for testing (qemu-system-i386)
- Linux environment (or equivalent Unix-like system)
- Install dependencies (Ubuntu/Debian):
sudo apt-get install nasm gcc make qemu-system-x86- Build the OS:
make- Run in QEMU:
make run- Loads at 0x7C00 (BIOS loading point)
- Sets up initial environment
- Loads kernel from disk
- Switches to protected mode
- Jumps to kernel at 0x1000
- Entry point at 0x1000
- Implements basic screen I/O
- VGA text mode driver
- System initialization
- IDT initialization
- Complete IDT setup and management
- Exception handlers with detailed error messages
- Hardware interrupt support (IRQ0-15)
- Programmable Interrupt Controller (PIC) configuration
- Custom interrupt handler registration
- Debug exception handling
- PS/2 keyboard driver with:
- Full US keyboard layout support
- Shift and Caps Lock modifiers
- Key state tracking
- Interrupt-driven input handling (IRQ1)
- Debouncing support
- Extended key support (e.g. right ctrl/alt)
- Circular buffer for key events
- Support for special keys (backspace, tab, enter)
- Bootloader: 0x7C00
- Kernel: 0x1000
- Stack: 0x90000
- IDT: Dynamically allocated
To modify or extend the OS:
-
Bootloader changes:
- Edit
boot/boot.asm - Modify GDT if adding memory segments
- Update kernel loading if kernel size changes
- Edit
-
Kernel changes:
- Edit
kernel/kernel.c - Update
kernel/link.ldif changing memory layout - Modify Makefile if adding new source files
- Edit
- Debug with QEMU monitor:
make run
# Press Ctrl+Alt+2 for QEMU monitor- Debug with GDB:
# Terminal 1
qemu-system-i386 -s -S -boot a -fda cupidos.img
# Terminal 2
gdb
(gdb) target remote localhost:1234- Fork the repository
- Create your feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
GNU v3
- Implemented comprehensive keyboard driver with full modifier key support
- Added function key handling (F1-F12)
- Implemented key repeat functionality with configurable delays
- Added debouncing support for more reliable key input
- Enhanced exception handling with detailed error messages
- Implemented basic PIT timer with system tick counter
- Added initial delay/sleep functionality using timer ticks