Project SigmaBoot

SigmaBoot is a tiny 32-bit freestanding kernel that boots with GRUB and provides a basic text terminal layer.

Warning

This project is experimental alpha software. Breaking changes can happen between releases, features may be incomplete or unstable, and it is not intended for production or critical systems.

FAQ

Why does this project exist?

Project SigmaBoot exists as a learning-first bare metal kernel project. The goal is to build core OS components from scratch in small, understandable steps.

Who is this for?

Anyone learning low-level systems programming, x86 boot flow, interrupts, and early kernel architecture.

Is this production ready?

No. This is alpha-stage experimental software and is expected to change frequently.

Why date-style versions?

Date-style versions make milestone history easy to track and keep release progression clear during rapid iteration.

What can I do with it today?

You can boot in QEMU, use the shell commands, inspect lock state and uptime, and view the Multiboot memory map.

Features

• Multiboot-compliant boot path with GRUB.
• VGA text-mode terminal with color support.
• Newline, tab handling, and automatic scroll when output reaches the screen bottom.
• Small decimal and hexadecimal print helpers for kernel diagnostics.
• PS/2 keyboard input with basic US scancode translation.
• Caps Lock handling for alphabetic keys and Num Lock handling for keypad digits.
• Lock key LED synchronization for Caps Lock, Num Lock, and Scroll Lock.
• Persistent bottom-row lock status bar showing CAPS/NUM/SCRL states.
• Interrupt-driven keyboard input via IRQ1 using IDT + PIC remap.
• CPU exception ISRs (0-31) with fault diagnostics screen showing vector, name, error code, EIP, CS, and EFLAGS.
• PIT timer IRQ0 support with uptime display in the status bar.
• Tiny interactive shell commands: help, clear, version, locks, uptime, memmap, pmm, heap, history.
• Multiboot memory map viewer command (memmap) for physical layout inspection.
• Early physical memory manager (bitmap-based frame tracking) with pmm shell stats command.
• Heap allocator groundwork with kmalloc/kfree and heap shell stats command.
• Heap-backed dynamic shell input buffer with growth and last-command history (history).
• Kernel version string embedded at build time and shown on boot.

Versioning

• Canonical kernel version is stored in kernel/VERSION.
• Local builds use kernel/VERSION automatically.
• Release pipeline overrides with release tag so shipped assets match the tag exactly.
• Optional manual override:
  • make -C kernel all KERNEL_VERSION=v0.0.20260328.6

Project Website

• Source files are in site/.
• Open site/index.html locally to preview.
• Documentation page is site/docs.html.
• Architecture diagram is included in site/docs.html.
• GitHub Pages deployment is automated by .github/workflows/deploy-site.yml.

Project Layout

• kernel/src/boot.s: Multiboot header and assembly entrypoint.
• kernel/src/kernel.c: C kernel entry logic and boot demo output.
• kernel/src/terminal.c, kernel/src/terminal.h: VGA terminal driver.
• kernel/src/print.c, kernel/src/print.h: tiny printing helpers.
• kernel/src/keyboard.c, kernel/src/keyboard.h: PS/2 keyboard IRQ handling, queueing, and scancode mapping.
• kernel/src/interrupts.c, kernel/src/interrupts.h: IDT setup, PIC remap, and IRQ dispatch.
• kernel/src/timer.c, kernel/src/timer.h: PIT configuration and uptime counters.
• kernel/src/multiboot.h: Multiboot data structures used for boot-time memory map parsing.
• kernel/src/pmm.c, kernel/src/pmm.h: Physical memory manager bitmap and frame stats APIs.
• kernel/src/heap.c, kernel/src/heap.h: Heap allocator (kmalloc/kfree) and heap statistics.
• kernel/src/isr.s: interrupt service routine stubs.
• kernel/linker.ld: Links the kernel at 1 MiB.
• kernel/grub/grub.cfg: GRUB menu entry.
• kernel/Makefile: Build, ISO, and QEMU run targets.

Prerequisites

Install the following tools:

• i686-elf-gcc, i686-elf-as, i686-elf-ld
• grub-mkrescue
• xorriso
• qemu-system-i386

Build

make -C kernel all

Build Bootable ISO

make -C kernel iso

Run in QEMU

make -C kernel run

Quick Regression Checklist

• Boot reaches shell prompt and prints kernel version.
• help lists history in the command list.
• Enter more than 128 characters in one command without crashing (dynamic input growth).
• Use backspace during long input; cursor and command state remain in sync.
• Run several commands, then history prints recent commands in order.
• Run more than 16 commands; history keeps only the most recent entries.
• Status bar continues updating lock states and uptime while typing commands.

Clean

make -C kernel clean