GPT-OS

GPT-OS is a minimal x86_64 UEFI operating system experiment. The current stage of the project focuses on establishing a reliable UEFI boot flow that surfaces detailed firmware diagnostics before exiting boot services and transferring control to a kernel stub that continues execution without firmware assistance.

This iteration replaces third-party UEFI crates with a self-contained FFI layer so the boot code can be compiled offline with nothing more than the Rust toolchain. The boot component now transitions cleanly out of firmware while preserving the captured memory map for later kernel stages. A GitHub Actions workflow continuously builds a bootable ISO (complete with an ESP image) on every push and pull request and publishes it as an artifact so you always have a fresh image to test.

Project layout

• boot/ – A Rust-based UEFI application that serves as the first-stage boot component. It now produces a colourised diagnostic dashboard summarising firmware metadata and the physical memory map, including the largest conventional memory regions. After diagnostics complete, the stage exits boot services, retains the resulting memory map, and transfers execution to an early kernel stub running without firmware services.
• .cargo/config.toml – Configures Cargo to always build the project for the x86_64-unknown-uefi target using the bundled rust-lld linker.

Building

1. Install the Rust toolchain and the UEFI compilation target (no additional crates are required):

   rustup target add x86_64-unknown-uefi

2. Build the UEFI application:

   cargo build --release

   The resulting EFI binary will be available at target/x86_64-unknown-uefi/release/boot.efi.

3. (Optional) Produce a bootable ISO locally. Install mtools and xorriso (e.g. sudo apt-get install mtools xorriso) and run:

   ./scripts/build_iso.sh

   The finished image is written to target/gpt-os.iso and mirrors the artifact published by CI.

Running in QEMU

You can copy the resulting EFI binary into a FAT-formatted disk image and boot it using a UEFI-compatible firmware. The following example uses ovmf and a temporary disk image:

# Create a blank FAT image and copy the EFI application
truncate -s 64M disk.img
mformat -i disk.img ::
mmd -i disk.img ::/EFI
mmd -i disk.img ::/EFI/BOOT
mcopy -i disk.img boot/target/x86_64-unknown-uefi/release/boot.efi ::/EFI/BOOT/BOOTX64.EFI

# Launch QEMU with OVMF
qemu-system-x86_64 \
  -drive file=disk.img,if=ide,format=raw \
  -bios /usr/share/OVMF/OVMF_CODE.fd

When launched, GPT-OS prints firmware metadata, analyses the full memory map, highlights the most significant conventional regions, and then exits boot services. Control passes to a kernel stub that stores the boot information for later stages, reports the captured memory summary over the 16550-compatible serial port, demonstrates a simple physical frame allocator, and idles the CPU with interrupts disabled. You can either attach the generated ISO directly as a virtual optical disk or follow the steps above to create a FAT disk image manually.

Kernel serial diagnostics

After the boot stage relinquishes firmware services the kernel stub now provides its own diagnostics pipeline via COM1. This keeps post-firmware debugging viable even though the UEFI console is gone.

The kernel stub also spins up a straightforward physical frame allocator derived from the retained memory map. Up to 32 conventional memory segments are tracked and served as 4 KiB frames so later kernel stages have a ready source of physical pages. In addition to the serial console, the boot stage now captures the active UEFI graphics output mode and the kernel paints a simple splash screen directly into the framebuffer so you can verify that post-firmware drawing works.

The sample QEMU invocation above already routes the serial device to a log file. Once the kernel takes over you should see entries similar to:

GPT-OS kernel stub online
Descriptors: 117
Usable regions: 11
Physical memory: 136365211648 bytes
Usable memory: 486325248 bytes
Top conventional regions:
   1: 0x0001780000 - 0x001BB6BFFF (107500 pages, 440320000 bytes)
   2: 0x001BB8C000 - 0x001DF4FFFF (9156 pages, 37502976 bytes)
Frame allocator captured 11 regions (118764 frames tracked)
  frame  1: 0x0001780000
  frame  2: 0x0001781000
  frame  3: 0x0001782000
  frame  4: 0x0001783000
Frames remaining after demo: 118760
Painted framebuffer demo scene.

These serial diagnostics mirror the information shown before exiting boot services so that subsequent kernel development can rely on a consistent debugging experience while also showcasing the allocator state.

Framebuffer splash

GPT-OS queries the UEFI Graphics Output Protocol (GOP) during boot, records the active mode, and exposes that framebuffer to the kernel after exiting boot services. The kernel stub draws a coloured gradient with a checkerboard accent to confirm that the framebuffer can be safely accessed with firmware gone. If GOP is unavailable on a platform the boot logs will mention it and the kernel will fall back to serial-only diagnostics.

Boot diagnostics

The boot stage keeps boot services active for the duration of the diagnostic output. This makes it easier to inspect the memory map from within firmware consoles such as OVMF's built-in shell. Once diagnostics finish, boot services are cleanly exited and the kernel stub takes ownership of the captured BootInfo record. Future iterations will use this information to initialise paging and launch richer kernel functionality.