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 stats, and dynamic shell buffering.

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/keyboard.c handles IRQ scancodes and key queue.

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 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/keyboard.c Scancode handling, lock states, input queue
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`) and allocation statistics
kernel/Makefile Build and ISO generation rules

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.

What can I try now?

Boot in QEMU, run shell commands, inspect uptime and lock states, and use the memmap command.

How are releases versioned?

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