Skip to content

BOOT_GUIDE.md

Latest commit

 

History

History
170 lines (131 loc) · 6.43 KB

BOOT_GUIDE.md

File metadata and controls

170 lines (131 loc) · 6.43 KB
Raw

glowieStopper — Boot & Usage Guide

Current State

glowieStopper boots into a 32-bit protected mode kernel with:

  • VGA text console (80×25, hardware cursor)
  • PS/2 keyboard input with echo
  • Serial console (COM1, 38400 baud, 8N1)
  • PIC-remapped interrupts (IRQ0=timer @ 100 Hz, IRQ1=keyboard)
  • Ctrl+P panic shutdown (ACPI poweroff via port 0x604)
  • Shift for uppercase letters

Building

Requirements: none. No Python, no C compiler, no external assembler, no Make. The only build artifact needed is ./build/tools/seed — our own 331-byte hand-crafted x86_64 ELF. If it is missing, bootstrap it once from tools/hex2bin.hex and toolchain/seed/seed.hex (see tools/README.md).

cd /path/to/glowieStopper
./bootstrap.sh

Which is literally:

./build/tools/seed < boot/image.hex > build/glowieStopper.img

Output: build/glowieStopper.img — a raw disk image (MBR + 32-bit PM kernel).

What boot/image.hex contains

Region Offset Size Description
Sector 0 (MBR) 0x000 512 B Real mode: load kernel, enter PM
Sectors 1–4 0x200 2 KB 32-bit PM kernel code + data
Sectors 5–16 0xA00 6 KB Zero padding (BIOS reads 16 sectors)

Running in QEMU

qemu-system-x86_64 -drive file=build/glowieStopper.img,format=raw

With serial console

qemu-system-x86_64 -drive file=build/glowieStopper.img,format=raw -serial stdio

This mirrors all serial output to your terminal. Keyboard input in the QEMU window is echoed both on VGA and serial.

Headless (serial only)

qemu-system-x86_64 -drive file=build/glowieStopper.img,format=raw -display none -serial stdio

With specific display backend

# GTK (recommended on Linux)
qemu-system-x86_64 -drive file=build/glowieStopper.img,format=raw -display gtk -serial stdio

# SDL
qemu-system-x86_64 -drive file=build/glowieStopper.img,format=raw -display sdl -serial stdio

Keyboard Controls

Key Action
Any letter Echo to VGA + serial
Shift+letter Uppercase letter
Enter New line + prompt
Backspace Delete previous character
Tab Insert 4 spaces
Ctrl+P Shutdown the OS (ACPI off)

Memory Layout (after boot)

Address Size Purpose
0x7C00–0x7DFF 512 B MBR (sector 0)
0x7E00–0x85FF ~2 KB Kernel code + strings + scan table
0x9C00↓ ~1 KB Stack (grows down)
0xA000–0xA7FF 2 KB IDT (256 × 8-byte entries)
0xB000–0xB0FF 256 B Scan code lookup table (US QWERTY)
0xB100–0xB10F 16 B State: tick count, ctrl/shift, cursor
0xB110–0xB20F 256 B Keyboard ring buffer
0xB8000 4 KB VGA text framebuffer (80×25)

Boot Sequence

  1. BIOS loads MBR (sector 0) at 0x7C00
  2. MBR prints "glowieStopper booting..." via BIOS INT 10h
  3. MBR loads 16 sectors via BIOS INT 13h to 0x7E00
  4. MBR enables A20 line (fast method, port 0x92)
  5. MBR loads GDT (null + code32 + data32)
  6. MBR sets PE bit in CR0 → protected mode
  7. MBR far-jumps to 0x0008:0x7E00 (kernel entry)
  8. Kernel disables interrupts, sets segment registers + stack
  9. Kernel initializes COM1 serial (38400 8N1)
  10. Kernel remaps PIC (IRQs 0–15 → INT 32–47)
  11. Kernel programs PIT channel 0 at 100 Hz
  12. Kernel builds 256-entry IDT at 0xA000
  13. Kernel installs timer ISR (INT 32) and keyboard ISR (INT 33)
  14. Kernel copies scan code table to 0xB000
  15. Kernel clears VGA screen, prints banner
  16. Kernel sends banner to serial
  17. Kernel enables interrupts (STI)
  18. Main loop: HLT → process key buffer → echo → repeat

Enhancements Roadmap

Near-term

  • Scrollback buffer — keep history of scrolled-off lines
  • Command parsing — interpret typed lines as built-in commands
    • help — show available commands
    • mem — display memory map
    • uptime — show tick count
    • reboot — triple-fault reset
    • shutdown — same as Ctrl+P
  • More scan codes — F1–F12, arrow keys, Delete, Home/End
  • Color themes — toggle VGA color attributes via command
  • RTC clock — read CMOS RTC for date/time display

Mid-term

  • Long mode (64-bit) — page tables, 64-bit GDT, jump to kernel64
  • Physical memory manager — bitmap allocator for available RAM
  • Virtual memory — proper page fault handling
  • ATA PIO disk driver — read/write sectors in protected mode
  • Simple filesystem — flat file table on disk
  • Bootstrap assembler in hex — tasm_stage1.hex to bridge seed → tasm

Long-term

  • tLang compiler — self-hosting compiler (codegen ~90% done)
  • Preemptive multitasking — TSS, context switching, scheduler
  • Userspace — ring 3 processes, syscall interface
  • GUI — framebuffer graphics via VESA/VBE
  • Self-hosting — glowieStopper builds itself on glowieStopper

Architecture Files

File Purpose
boot/image.hex Full boot image as commented hex — fed to seed to produce build/glowieStopper.img
boot/boot.hex Original simple MBR (print + halt demo)
bootstrap.sh Thin POSIX-sh wrapper: seed < boot/image.hex > build/glowieStopper.img
boot/stage1.asm Reference: MBR design (NASM syntax)
boot/stage2.asm Reference: A20, E820, VESA, GDT, PM entry
boot/stage3.asm Reference: page tables, long mode, ATA PIO
build/tools/hex2bin 326-byte hex→binary converter
build/tools/seed 331-byte bootstrap assembler

No External Dependencies

Every byte in the boot image is stored verbatim in boot/image.hex and fed through seed (our own 331-byte ELF). There is no assembler (NASM/GAS), no linker, no C compiler, no Python, and no Make involved anywhere in the build chain. The .asm files are reference documentation only.

QEMU is used as a testing convenience — it is not part of the build chain.