Boot Process

Purpose: Complete boot sequence documentation

Overview

The FreeWorld OS boot process uses modern UEFI boot pipeline. Legacy BIOS boot is deprecated.

UEFI Migration Complete (2025): FreeWorld OS now uses UEFI boot exclusively. All hardware information comes from UEFI protocols.

UEFI Boot Sequence (Primary)

  1. UEFI Firmware Initialization
    • SEC Phase: Security, Cache-as-RAM, microcode updates
    • PEI Phase: Memory initialization, HOB creation
    • DXE Phase: Driver execution, GOP initialization, USB stack
    • BDS Phase: Boot device selection, finds ESP
    • TSL Phase: Transient System Load (bootloader execution)
  2. UEFI Bootloader (bootx64.efi)
    • UEFI loads bootx64.efi from EFI System Partition
    • Bootloader runs in 64-bit long mode
    • Bootloader retrieves UEFI data BEFORE ExitBootServices:
      • GOP framebuffer information
      • UEFI memory map
      • ACPI RSDP from UEFI System Table
    • Bootloader builds boot_params_t structure
    • Bootloader calls ExitBootServices()
    • Bootloader jumps to kernel_entry_uefi (passes boot_params_t in RDI)
  3. Kernel Entry (kernel_entry_uefi.asm)
    • Receives boot_params_t pointer in RDI
    • Extracts framebuffer, memory map, ACPI RSDP
    • Initializes framebuffer console (GOP-based)
    • Calls kernel_init_64_uefi
  4. Kernel Initialization (kernel_64_uefi.asm)
    • Sets up IDT
    • Initializes UEFI memory map-based PMM
    • Initializes ACPI using RSDP from UEFI
    • Initializes I/O APIC (disables legacy PIC)
    • Initializes HPET (replaces legacy PIT)
    • Initializes modern drivers (USB xHCI, NVMe, AHCI)
    • Continues with normal kernel initialization

Legacy BIOS Boot Sequence - ⚠️ DEPRECATED

⚠️ Deprecated: The following BIOS boot sequence is deprecated and no longer used. It is kept for reference only.
  1. BIOS Initialization
    • BIOS performs hardware initialization
    • BIOS loads boot sector from disk
  2. Stage 1 Bootloader (bootloader_stage1.asm)
    • BIOS loads boot sector (512 bytes) to 0x7C00
    • Stage 1 initializes segments, stack, and serial port (COM1)
    • Stage 1 initializes VGA text mode (80x25)
    • Stage 1 displays "Loading FreeWorld OS..." message
    • Stage 1 attempts LBA extended read (INT 0x13, AH=0x42) with fallback to CHS
    • Critical: Uses CHS sector 3 (physical sector 2) to load stage 2
    • Note: CHS sectors are 1-based, physical sectors are 0-based
    • Stage 1 verifies stage 2 signature ('OB' = 0x424F)
    • Stage 1 passes boot device number to stage 2
    • Stage 1 jumps to stage 2 at 0x0000:0x7E00
  3. Stage 2 Bootloader (bootloader_ui.asm)
    • Stage 2 starts at 0x7E00 (right after stage 1)
    • Stage 2 initializes segments and stack
    • Stage 2 initializes graphics mode (VESA or VGA)
    • Stage 2 loads graphics from disk:
      • Logo: CHS sector 7 (physical sector 6)
      • Background: CHS sector 15 (physical sector 14)
      • Selection highlight: CHS sector 25 (physical sector 24)
      • Progress bar: CHS sector 27 (physical sector 26)
      • Error icon: CHS sector 29 (physical sector 28)
      • Success icon: CHS sector 31 (physical sector 30)
    • Stage 2 displays boot menu with graphics
    • Stage 2 waits for user selection
    • Stage 2 loads kernel from CHS sector 33 (physical sector 33)
    • Stage 2 verifies kernel signature ('FREEWORL')
    • Stage 2 jumps to kernel entry point (0x1000:0x0000)
  4. BCD (Boot Configuration Data) - PLANNED
    • Status: Not yet implemented
    • Planned: freeload.exe will read BCD file
    • Planned: BCD will provide boot entry configuration
    • Planned: Will contain kernel and loader paths
  5. freeload.exe (OS Loader) - PLANNED
    • Status: Not yet implemented
    • Planned: Will load BCD configuration
    • Planned: Will load kernel (fwoskrnl.exe) into memory
    • Planned: Will load essential device drivers
    • Planned: Will transfer control to kernel
    • Current: BOOTMGR directly loads kernel from disk
  6. fwoskrnl.exe (Kernel Entry - kernel_entry.asm)
    • Kernel loaded at 0x1000:0x0000 (linear 0x10000)
    • Boot sequence: 16-bit real mode → 32-bit protected mode → 64-bit long mode
    • Verify kernel magic number ("FREEWORL")
    • Initialize hardware (serial port COM1)
    • Display kernel messages
    • Detect memory using INT 15h E820
    • Protected Mode Transition:
      • Disable interrupts (cli)
      • Load GDT (lgdt)
      • Enable A20 line (port 0x92)
      • Set CR0.PE bit (protected mode enable)
      • 32-bit far jump to protected_mode_start (0x10191)
    • Set up segment registers (DS, ES, FS, GS, SS = 0x10)
    • Set up stack (ESP = 0x90000)
    • Remap PIC (Programmable Interrupt Controller) - IRQ0-7 → INT 0x20-0x27
    • Set up full IDT (256 entries):
      • 0-31: Exception handlers (all 32 CPU exceptions)
      • 32 (0x20): Timer interrupt (IRQ0) handler
      • 33 (0x21): Keyboard interrupt (IRQ1) handler
      • 34-47: Other hardware interrupts (IRQ2-IRQ15)
      • 128 (0x80): System call handler
      • 129-255: Generic interrupt handlers
    • Configure PIT (Programmable Interval Timer) - ~100 Hz for testing
    • Unmask IRQ0 (timer) and IRQ1 (keyboard) in PIC
    • Initialize all 32-bit subsystems (memory, drivers, process, filesystem, graphics)
    • 64-bit Long Mode Transition:
      • Check CPUID for long mode support (EDX bit 29)
      • Disable paging temporarily (clear CR0.PG)
      • Set up 4-level page tables (PML4, PDPT, PD, PT)
      • Load 64-bit GDT (with L=1 bit for long mode)
      • Enable PAE (set CR4.PAE bit)
      • Enable long mode (set EFER.LME via MSR 0xC0000080)
      • Enable paging (set CR0.PG) - this activates long mode
      • 64-bit far jump to long_mode_entry (segment 0x08)
    • Set up 64-bit segment registers (DS, ES, FS, GS, SS = 0x10)
    • Set up 64-bit stack (RSP = 0x200000)
    • Initialize 64-bit subsystems
    • Enter 64-bit kernel main loop
  7. hal.dll (Hardware Abstraction Layer)
    • HAL initialization (hal_init)
    • Detect CPU
    • Detect memory
    • Detect devices
    • Initialize device drivers
  8. smss.exe (Session Manager)
    • Initialize user session
    • Load critical system processes
    • Start CSRSS
    • Start login manager
  9. csrss.exe (Client Server Runtime)
    • Initialize console subsystem
    • Initialize window manager
    • Start message loop
  10. freeworldlogon.exe (Login Manager)
    • Display login prompt
    • Authenticate user
    • Start user shell
  11. shell.exe (User Shell)
    • Display "FREE WORLD>" prompt
    • Accept user commands
    • Execute commands

Memory Layout During Boot

0x0000 - 0x03FF  : Interrupt Vector Table (IVT)
0x0400 - 0x04FF  : BIOS Data Area
0x0500 - 0x7BFF  : Available
0x7C00 - 0x7DFF  : Stage 1 Bootloader (512 bytes)
0x7E00 - 0x9FFF  : Stage 2 Bootloader (~2KB)
0x8000 - 0x8FFF  : Graphics Index Table
0x9000 - 0x9FFF  : Logo Graphics Buffer
0xA000 - 0xAFFF  : Background Graphics Buffer
0xB000 - 0xB7FF  : Selection Highlight Buffer
0xB800 - 0xBFFF  : Progress Bar Buffer
0xC000 - 0xC1FF  : Error Icon Buffer
0xC200 - 0xC3FF  : Success Icon Buffer
0xA000 - 0xBFFF  : Video Memory (VGA)
0xC000 - 0xFFFF  : BIOS ROM
0x1000:0x0000    : Kernel Entry Point (linear 0x10000)
0x1000:0x2000    : Memory Map Buffer (E820 results)
0x8000          : IDT (Interrupt Descriptor Table)
0x90000          : Stack (protected mode)

64-bit Long Mode Memory Layout

After transitioning to 64-bit long mode, the memory layout uses 48-bit virtual addressing:

0x0000000000000000 : Null page (unmapped)
0x0000000000100000 : Kernel base (1MB)
0x0000000000200000 : 64-bit stack (2MB)
0x0000000000201000 : PML4 table
0x0000000000202000 : PDPT table
0x0000000000203000 : Page Directory
0x0000000000204000 : Page Table
0x00007FFFFFFFFFFF : Maximum 48-bit user space address
0xFFFF800000000000 : Kernel space start
0xFFFFFFFFFFFFFFFF : Maximum 64-bit address

Protected Mode Memory Layout

After transitioning to protected mode (before long mode), the memory layout uses flat addressing:

  • 0x00000000 - 0x000FFFFF: Real mode compatibility (first 1MB)
  • 0x00010000: Kernel entry point
  • 0x00008000: IDT (256 entries × 8 bytes = 2048 bytes)
  • 0x00090000: Stack pointer (grows downward)
  • 0xFFFFFFFF: Maximum 32-bit address (4GB limit)

JMP Instructions

Location Instruction Purpose
BOOTMGR jmp 0x1000:0x0000 Far jump to kernel entry point (16-bit real mode)
BOOTMGR (print_string) jz done Conditional jump if end of string
BOOTMGR (print_string) jmp print_string Unconditional jump to continue loop
Kernel (enter_protected_mode) db 0x66, 0xEA; dd 0x00010191; dw 0x08 32-bit far jump to protected mode entry point (0x10191, segment 0x08)
Kernel (protected_mode_start) call setup_minimal_idt Call to set up IDT (after segment registers)
Note: The 32-bit far jump uses opcodes 0x66 0xEA followed by a 32-bit offset and 16-bit segment selector. This is required because the target address (0x10191) exceeds 64KB.

Disk Layout

The boot disk is organized as follows:

Physical Sector 0  : Stage 1 Bootloader (MBR, 512 bytes)
Physical Sector 1  : Unused
Physical Sector 2  : Stage 2 Bootloader start (CHS sector 3)
Physical Sectors 2-5: Stage 2 Bootloader (4 sectors, ~2KB)
Physical Sector 6  : Graphics start (Logo, CHS sector 7)
Physical Sectors 6-32: Graphics resources
Physical Sector 33 : Kernel start (CHS sector 33)
Important: CHS (Cylinder-Head-Sector) addressing uses 1-based sector numbering, while physical sectors are 0-based. This means:
  • Physical sector 0 = CHS sector 1 (MBR)
  • Physical sector 2 = CHS sector 3 (Stage 2 start)
  • Physical sector 6 = CHS sector 7 (Graphics start)
  • Physical sector 33 = CHS sector 33 (Kernel start)

Boot Sector Format

  • Size: 512 bytes (exactly)
  • Boot Signature: 0xAA55 at bytes 510-511
  • Load Address: 0x7C00
  • Mode: 16-bit real mode
  • Disk Access: LBA extended read (INT 0x13, AH=0x42) with CHS fallback

Current Implementation Status

Note: FreeWorld OS currently uses a simplified two-stage boot process. Advanced boot stages (BCD, freeload.exe) are planned but not yet implemented.

Implemented Stages

  • ✅ Stage 1 Bootloader (bootloader_stage1.asm): Fully functional MBR bootloader
  • ✅ Stage 2 Bootloader (bootloader_ui.asm): Graphical bootloader with menu
  • ✅ Graphics Loader (graphics_loader.asm): Loads boot graphics from disk
  • ✅ Kernel Entry (kernel_entry.asm): Fully functional kernel initialization

Planned Stages (Not Yet Implemented)

  • ⏳ BCD (Boot Configuration Data): Boot configuration database
  • ⏳ freeload.exe: Advanced OS loader with BCD support

Boot Process Details

Stage 1 Bootloader (bootloader_stage1.asm):

  • Loaded by BIOS at 0x7C00 (512 bytes, MBR)
  • Initializes serial port (COM1 at 0x3F8) for debugging
  • Initializes VGA text mode (80x25)
  • Checks for LBA extended read support (INT 0x13, AH=0x41)
  • Uses LBA extended read (INT 0x13, AH=0x42) if supported, falls back to CHS
  • Loads stage 2 from CHS sector 3 (physical sector 2) to 0x0000:0x7E00
  • Verifies stage 2 signature ('OB' = 0x424F)
  • Passes boot device number to stage 2
  • Jumps to stage 2 at 0x0000:0x7E00

Stage 2 Bootloader (bootloader_ui.asm):

  • Starts at 0x7E00 (loaded by stage 1)
  • Initializes graphics mode (VESA or VGA)
  • Loads graphics resources from disk using CHS addressing
  • Displays graphical boot menu
  • Waits for user selection (keyboard input)
  • Loads kernel from CHS sector 33 (physical sector 33) to 0x1000:0x0000
  • Verifies kernel magic number "FREEWORL"
  • Jumps to kernel entry point (0x1000:0x0000)
Key Discovery: The bootloader was fixed to correctly handle CHS sector addressing. Physical sectors are 0-based, but CHS sectors are 1-based. This means physical sector 2 corresponds to CHS sector 3, not CHS sector 2.

Kernel Entry (kernel_entry.asm):

  • Starts in 16-bit real mode at 0x1000:0x0000
  • Initializes hardware (serial port COM1, FIFO disabled for reliability)
  • Detects memory using INT 15h E820
  • Transitions to 32-bit protected mode
  • Sets up GDT, IDT, PIC remapping, PIT configuration
  • Enters main kernel loop