guideXOS Server Boot and UEFI

Purpose: document the current UEFI-first flow, how it is built, and how it is commonly tested.

UEFI-first direction

The main build and run scripts in the current Server source tree are centered on a UEFI workflow. build.ps1 builds the bootloader, builds the selected kernel architecture, stages an ESP directory, and can immediately launch QEMU. run-qemu.bat and run-uefi.sh both boot through OVMF firmware and mount the local ESP/ directory as a FAT drive for QEMU.

Implemented

Current status: active UEFI-first build and test flow.
Known gaps: broader boot polish and equal maturity across non-UEFI paths are still evolving.
Back to /Wiki/Server

Current boot flow

Firmware (OVMF / UEFI) -> BOOTX64.EFI from ESP/EFI/BOOT -> guideXOSBootLoader -> kernel.elf -> BootInfo / memory-map handoff -> kernel_main -> framebuffer + desktop / subsystem init

In the current bootloader source, the UEFI loader is x86_64-oriented, uses GOP/ACPI/file-system protocols, prepares boot info, handles memory-map stability around ExitBootServices, and finally jumps into the ELF64 kernel entry.

What the bootloader is responsible for

  • Locate and open the kernel file from the EFI-accessible filesystem
  • Read graphics output information through GOP
  • Gather memory-map information and preserve it across boot-services exit
  • Prepare canonical BootInfo data for the kernel handoff
  • Transfer control through the handoff trampoline after boot services are gone
Implemented

Primary Windows workflow

powershell -ExecutionPolicy Bypass -File build.ps1 -RunQemu

This is the main repo-documented path for bootloader build, kernel build, ESP staging, and QEMU validation.

QEMU launch characteristics

  • Q35 machine type
  • OVMF firmware via pflash
  • FAT drive from ESP/
  • E1000 NIC with user-mode networking
  • Serial output to console
  • 1024 MB RAM by default

Kernel-side boot assumptions

In kernel/core/main.cpp, the kernel can still detect either Multiboot-style input or UEFI BootInfo input, but the documented and actively surfaced workflow is clearly the UEFI BootInfo path. Once inside the kernel, the current code initializes framebuffer rendering, desktop drawing, interrupts, timer setup, storage, VFS, networking, and feature reporting.

UEFI-first, with older boot compatibility still present in code

Boot polish and roadmap notes

  • Implemented today: real UEFI/QEMU workflow, serial diagnostics, framebuffer handoff, and boot-to-desktop subsystem initialization.
  • Partially implemented: some non-UEFI or architecture-specific boot routes still exist in parallel and are not equally documented.
  • Planned or evolving: broader boot polish, more architecture-specific boot maturity, and cleaner parity between hosted and bare-metal flows.