🖥️ MiniOS — A Bare-Metal x86 Operating System

A minimal operating system built from scratch in C and x86 Assembly. No libraries, no frameworks — just raw hardware interaction.

✨ Features

• Multiboot-compliant — boots via GRUB or qemu -kernel
• VGA Text Mode Driver — 80×25 display with 16 colors, scrolling, cursor
• PS/2 Keyboard Driver — US QWERTY layout with Shift & Caps Lock support
• Serial Port (COM1) — debug logging at 38400 baud
• Global Descriptor Table (GDT) — flat memory model, kernel & user segments
• Interrupt Descriptor Table (IDT) — 32 CPU exceptions + 16 hardware IRQs
• PIC 8259 Remapping — hardware IRQs remapped to INT 32-47
• Kernel Panic Handler — prints register dump on unhandled CPU exceptions
• PIT Timer — tracks system uptime via IRQ0
• Interactive Shell — help, info, clear, echo, color, tick, panic, reboot

📂 Project Structure

mini-os/
├── Makefile                    # Build system
├── linker.ld                   # Kernel linker script (loads at 1MB)
└── src/
    ├── boot/
    │   └── boot.s              # Multiboot entry point (assembly)
    ├── cpu/
    │   ├── ports.h             # I/O port access (inb/outb)
    │   ├── gdt.h / gdt.c       # Global Descriptor Table
    │   ├── gdt_flush.s         # GDT reload (assembly)
    │   ├── idt.h / idt.c       # Interrupt Descriptor Table
    │   ├── isr.h / isr.c       # ISR/IRQ C handlers + PIC remap
    │   └── isr_stubs.s         # ISR/IRQ assembly stubs
    ├── drivers/
    │   ├── vga.h / vga.c       # VGA text mode display driver
    │   ├── serial.h / serial.c # Serial port (COM1) debug output
    │   └── keyboard.h / keyboard.c  # PS/2 keyboard driver
    ├── kernel/
    │   ├── kernel.h            # OS constants
    │   ├── kernel.c            # Kernel main entry point
    │   └── shell.c             # Interactive command shell
    └── lib/
        ├── string.h / string.c # Freestanding string/memory functions

🛠️ Prerequisites

macOS (Homebrew)

brew install i686-elf-gcc i686-elf-binutils nasm qemu

Ubuntu / Debian

sudo apt update
sudo apt install build-essential nasm qemu-system-x86
# For a proper cross-compiler, build i686-elf-gcc from source
# or use: sudo apt install gcc-multilib

🚀 Build & Run

# Build the kernel
make

# Run in QEMU (serial output in terminal)
make run

# Debug with GDB
make debug
# In another terminal:
gdb -ex "target remote :1234" -ex "symbol-file minios.bin"

# Clean build artifacts
make clean

🎮 Shell Commands

Command	Description
help	Display available commands
clear	Clear the screen
info	Show system information
echo <text>	Print text to the terminal
color	Display all 16 VGA colors
tick	Show PIT timer tick count & uptime
panic	Trigger a divide-by-zero kernel panic
reboot	Reboot the machine

🏗️ Architecture Overview

                    ┌─────────────────────────────────────┐
                    │           Interactive Shell          │
                    ├──────────┬──────────┬───────────────┤
                    │ VGA      │ Keyboard │ Serial (COM1) │
                    │ Driver   │ Driver   │ Driver        │
                    ├──────────┴──────────┴───────────────┤
                    │    IDT + ISR/IRQ Handlers + PIC     │
                    ├─────────────────────────────────────┤
                    │    GDT (Protected Mode Segments)    │
                    ├─────────────────────────────────────┤
                    │    Multiboot Bootloader (boot.s)    │
                    ├─────────────────────────────────────┤
                    │         x86 Hardware (QEMU)         │
                    └─────────────────────────────────────┘

📚 What You'll Learn

Building this project teaches you:

1. How computers boot — BIOS → Bootloader → Kernel
2. CPU Protected Mode — GDT segment descriptors, privilege rings
3. Hardware Interrupts — PIC 8259, IDT gates, ISR dispatching
4. Device Drivers — Direct I/O port programming (VGA, keyboard, serial)
5. Freestanding C — Writing C without any standard library
6. x86 Assembly — Register manipulation, calling conventions, IRET
7. Build Systems — Cross-compilation, linker scripts, binary formats

📖 License

MIT — Use freely for learning, portfolios, and interviews.