Documentation

Kernel Docs ALPHA

Technical reference for startup flow, interrupt model, keyboard handling, and release pipeline behavior.

Warning: Experimental alpha software. APIs, behavior, and docs may change frequently.

Repository Back to Landing

Architecture Snapshot

Boot Layer

src/boot.s defines Multiboot header, initializes stack, and jumps to kernel_main.

Kernel Core

src/kernel.c initializes terminal, interrupt subsystem, lock-state UI updates, shell command dispatch, memmap rendering, PMM/heap diagnostics (including integrity, compact triage, stress, fragmentation, histogram, and leak-trace views), and dynamic shell buffering via shared formatting utilities.

Display

src/terminal.c handles text output, scrolling, cursor behavior, and fixed-row status rendering.

Input + IRQ

src/interrupts.c remaps PIC and loads IDT. src/drivers/keyboard.c handles IRQ scancodes and key queue, while src/drivers/mouse.c handles IRQ12 packet decode/state.

Timing

src/timer.c programs PIT channel 0 and tracks uptime ticks consumed by the status bar.

Architecture Diagram

High-level flow from bootloader handoff to interrupt-driven subsystems and user command handling.

Interrupt Flow Diagram

Detailed interrupt routing for exceptions, PIT timer ticks, and keyboard events.

Boot and Input Flow

  1. GRUB loads kernel using Multiboot and transfers control to _start.
  2. Assembly startup sets stack and calls kernel_main.
  3. Kernel initializes terminal, sets IDT, remaps PIC, and enables interrupts.
  4. Timer IRQ0 increments uptime counters and updates periodic UI state.
  5. Multiboot metadata is retained for shell-level memory map inspection (`memmap`).
  6. CPU exceptions (vectors 0-31) dispatch to a fault screen with diagnostic register output.
  7. Keyboard IRQ1 enters isr_keyboard, dispatches to C handler, sends EOI.
  8. Translated characters are queued and consumed by the prompt loop.

IRQ Path (summary)

IRQ1 (vector 0x21)
  -> isr_keyboard (src/isr.s)
  -> interrupts_handle_keyboard_irq()
  -> keyboard_handle_irq()
  -> queue char + update lock LEDs/UI
  -> PIC EOI

Build, Test, Release

Local Build

make -C kernel test
make -C kernel all CROSS_COMPILE=
make -C kernel iso CROSS_COMPILE=
qemu-system-i386 -cdrom kernel/build/kernel.iso

GitHub Actions

  • build-kernel.yml: compile + upload artifacts
  • release-kernel.yml: attach assets to releases
  • deploy-site.yml: publish static docs/landing to Pages

Source Map

Path Purpose
kernel/src/boot.s Multiboot header and stack setup
kernel/src/isr.s Assembly ISR entry stubs
kernel/src/interrupts.c IDT init, PIC remap, IRQ dispatch
kernel/src/drivers/keyboard.c Scancode handling, lock states, input queue
kernel/src/drivers/mouse.c PS/2 mouse init plus IRQ12 packet and button/position tracking
kernel/src/terminal.c VGA text rendering and status row support
kernel/src/timer.c PIT setup and uptime tick counters
kernel/src/multiboot.h Multiboot structs and flags for memory map parsing
kernel/src/pmm.c Bitmap-based physical memory manager and frame statistics
kernel/src/heap.c Kernel heap allocator (`kmalloc`/`kfree`) with integrity checks, fragmentation stats, size histogram telemetry, and leak-trace reporting
kernel/src/heap_diag.c Heap diagnostics telemetry backend for counters, histograms, and allocation trace snapshots
kernel/src/stats_util.c Shared stats and diagnostics line-format utility module
kernel/Makefile Build, host-side test, and coverage rules (including LCOV output)

FAQ

Why does this project exist?

Project SigmaBoot is built to teach kernel fundamentals through small, testable milestones.

Is it production ready?

No. It is alpha-stage experimental software intended for learning and iteration.

How stable is test coverage?

The host-side suite currently sits at a 100% coverage milestone for heap allocator and diagnostics utility paths tracked in CI.

What can I try now?

Boot in QEMU, run shell commands, inspect uptime/lock/mouse status-bar activity, and try mouse, memmap, heapcheck, heaptriage, heapfrag, heapstress, heaphist, and heapleaks.

How are releases versioned?

Date-style tags are used to keep chronological milestones clear while development moves quickly.