A bare-metal operating system written entirely in FASM (Flat Assembler), targeting x86 protected mode. No C, no external runtime — assembly all the way down.

🚀 Preemptive Multitasking — Round-robin scheduler with quantum-based time slicing ⚡ Fast Context Switching — Full CPU + FPU/SSE state preservation in ~500 cycles 🛡️ Robust Exception Handling — All 32 CPU exceptions caught with register dumps ⏱️ 100 Hz System Timer — PIT-driven scheduler with 10ms tick precision 💾 16 KB Thread Stacks — Support for up to 8 concurrent kernel threads 🎯 Pure Assembly — 15 KB kernel binary, zero runtime dependencies

• Two-stage BIOS bootloader (MBR → protected mode)
• 32-bit protected-mode kernel with flat GDT
• IDT with CPU exception handlers (0-31) and IRQ dispatch
• 8259A PIC remapping (IRQ0-7 → 0x20, IRQ8-15 → 0x28)
• Full exception handling with register dumps and panic screen

• Preemptive multitasking with round-robin scheduler
• PIT timer at 100 Hz (10ms quantum)
• Thread Control Blocks (TCB) with full CPU context save/restore
• FPU/SSE state preservation (FXSAVE/FXRSTOR when available)
• Thread API: thread_create, thread_yield, thread_exit
• Support for up to 8 concurrent threads with 16 KB kernel stacks
• Idle thread (TID 0) with HLT power saving

• VGA text mode driver (80×25, colour, hardware cursor, scroll)
• VESA linear framebuffer driver (800×600×32bpp, optional)
• 8×16 bitmap font for VESA text rendering
• PS/2 keyboard driver — scancode-set-1, Shift/Ctrl/Alt/CapsLock
• PS/2 mouse driver — 3-byte packets, coordinate clamping

• Interactive shell with command history and line editing
• Demo commands: system info, thread spawning, exception testing

Install on Debian/Ubuntu:

sudo apt install fasm qemu-system-x86 make

# Build and run
make && make run

# Try the scheduler!
PFineOS> threads
# Watch two threads alternate execution

# Test exception handling
PFineOS> panic
# See register dump and graceful halt

# Check system timer
PFineOS> ticks
# View tick counter (100 Hz)

# Build disk image (32-bit protected mode)
make

# Boot in QEMU
make run

# Boot with 800x600 VESA graphics
make VESA=1 run

# GDB debug session (QEMU paused, GDB stub on :1234)
make debug
# In another terminal:
gdb -ex 'target remote localhost:1234' -ex 'set arch i386'

# Remove build artefacts
make clean

# Show disk layout and binary sizes
make info

ProbablyFineOS/
├── boot/
│   ├── stage1.asm          MBR (512 bytes) — loads stage2
│   └── stage2.asm          Stage 2 — A20, PM switch, loads kernel
├── kernel/
│   ├── kernel.asm          Entry point; includes all subsystems
│   ├── gdt.asm             Global Descriptor Table
│   ├── idt.asm             Interrupt Descriptor Table
│   ├── exceptions.asm      CPU exception handlers (0-31)
│   ├── pic.asm             8259A PIC
│   ├── fpu.asm             FPU/SSE initialization and FXSR support
│   ├── pit.asm             Programmable Interval Timer (100 Hz)
│   ├── thread.asm          Thread structure and context switching
│   ├── scheduler.asm       Round-robin scheduler with ready queue
│   └── shell.asm           Interactive shell with commands
├── drivers/
│   ├── video/
│   │   ├── vga.asm         VGA text mode 80×25
│   │   ├── vesa.asm        VESA 800×600×32bpp framebuffer
│   │   └── font.inc        8×16 bitmap font (ASCII 0x20–0x7E)
│   └── input/
│       ├── keyboard.asm    PS/2 keyboard, IRQ1, scancode set 1
│       └── mouse.asm       PS/2 mouse, IRQ12, 3-byte packets
├── include/
│   ├── constants.inc       I/O ports, memory map, VGA colours
│   ├── macros.inc          outb/inb/io_delay/eoi/freeze helpers
│   └── structs.inc         GDT/IDT entry macros, TCB structure
├── build/                  Generated artefacts (gitignored)
├── openspec/               Spec-driven change management
├── Makefile
└── README.md

• Algorithm: Round-robin with time-slice preemption
• Quantum: 100 ticks (1 second at 100 Hz)
• Ready Queue: Circular linked list of READY threads
• States: READY → RUNNING → (READY or DEAD)

Each thread has a 608-byte TCB containing:

• Identity: TID, state, quantum counter
• CPU context: EAX-EDI, ESP, EIP, EFLAGS
• FPU state: 512-byte buffer for FXSAVE/FXRSTOR (16-byte aligned)
• Stack info: Base address, size (16 KB per thread)
• Queue links: Next/prev pointers for ready queue

1. Save: Push registers, save ESP, save EFLAGS, FXSAVE FPU state
2. Switch: Update current_thread pointer
3. Restore: FXRSTOR FPU state, restore EFLAGS, pop registers, RET to saved EIP

; Create a new thread
; Input: eax = entry point address
; Returns: eax = TID or -1 on failure
thread_create:

; Voluntarily yield CPU to next thread
thread_yield:

; Terminate current thread (never returns)
thread_exit:

• TID 0, runs when no other threads are READY
• Infinite loop with HLT instruction (power saving)
• Never added to ready queue

1. Create drivers/<category>/<name>.asm with a <name>_init procedure and public symbols documented in a header comment.
2. Add include '../drivers/<category>/<name>.asm' at the bottom of kernel/kernel.asm.
3. Call <name>_init in kernel_entry after pic_init.
4. Add the new file to the $(KERNEL) dependency list in Makefile.
5. Create an OpenSpec proposal (openspec/changes/add-<name>/).

• No linker: FASM assembles the entire kernel as one flat binary (format binary). All sub-files are include-d into kernel/kernel.asm.
• Calling convention: cdecl-like stack passing for public API (vga_puts: push ptr / call / add esp, 4).
• IRQ flow: pic_init masks all IRQs → each driver's *_init installs its IDT gate via idt_set_gate then calls pic_unmask_irq.
• Threading: Preemptive multitasking with round-robin scheduler driven by PIT timer at 100 Hz. Context switching preserves all CPU registers and FPU/SSE state (when FXSR available via CPUID check).
• Exception handling: All CPU exceptions (0-31) print register dumps, exception details, and halt the system gracefully.
• x64 stub: pass ARCH=64 to assemble with long-mode code paths (scaffold; paging and 64-bit entry not yet complete).

MIT — see LICENSE.

  ____           _           _     _       ___  ____
 |  _ \ _ __ ___| |__   __ _| |__ | |_   / _ \/ ___|
 | |_) | '__/ _ \ '_ \ / _` | '_ \| | | | | | \___ \
 |____/|_|  \___/_.__/ \__,_|_.__/|_|\___\___/|____|
  v0.1.0  |  FASM  |  x86 Protected Mode  |  2026
  Type "help" for commands.

PFineOS>

PFineOS> threads
Creating test threads...
Test threads created successfully.
Thread A running
Thread B running
Thread A running
Thread B running
Thread A running
Thread B running

PFineOS> panic
Testing exception handler...
========================================
   KERNEL PANIC - Exception
========================================
Exception: Divide By Zero (#DE)
EIP: 0x00010ABC  Error Code: 0x00000000

Registers:
  EAX: 12345678  EBX: 9ABCDEF0
  ECX: 00000000  EDX: 00000000
  ESI: FEDCBA98  EDI: 76543210
  EBP: 0008FFE4  ESP: 0008FFDC
  EFLAGS: 00000202

System halted.

• README.md — This file (overview and quick start)
• TESTING.md — Comprehensive testing guide
• IMPLEMENTATION.md — Detailed implementation notes
• openspec/ — Specification-driven change proposals