Snapi-OS

Snapi-OS is a from-scratch x86-64 hobby operating system written entirely in Rust.

Milestone 1 is complete. The current target is Milestone 2: Freestanding Runtime.

This repository uses:

• Rust for the whole project
• x86-64 as the only target architecture
• UEFI as the only boot entry path
• a freestanding kernel runtime for the current milestone
• Trunk-Based Development with protected main
• Test-First Development as soon as possible
• QEMU + OVMF first, then generic x86-64 UEFI hardware

Current state

Milestone 1 delivered a working UEFI-hosted shell environment.

That means the current repository already has:

• direct boot as \EFI\BOOT\BOOTX64.EFI
• a working shell prompt
• basic Unix-like file and directory commands
• a simple persistent filesystem image at \SNAPIOS\ROOTFS.IMG
• QEMU acceptance tests
• real-hardware validation on x86-64 UEFI hardware

Milestone 2 does not repeat that work. It builds on it.

What milestone 2 is

Milestone 2 is a UEFI-first but no longer UEFI-hosted runtime.

That means:

• firmware still loads BOOTX64.EFI directly
• BOOTX64.EFI becomes a loader, not the full runtime
• the loader loads a freestanding kernel from \SNAPIOS\KERNEL.ELF
• the loader gathers boot information and calls ExitBootServices()
• after that point, Snapi-OS continues running as its own freestanding kernel
• normal runtime behavior no longer depends on UEFI Boot Services

This is the milestone that moves Snapi-OS from a hosted pre-boot environment into a standalone OS runtime.

Milestone 2 goal

Boot the same packaged ESP image in both:

1. QEMU with OVMF
2. real x86-64 UEFI hardware

Then:

• load the freestanding kernel
• exit UEFI boot services successfully
• continue running under Snapi-OS control
• execute shell commands after handoff
• prove in the transcript that command execution happened after ExitBootServices()

Milestone 2 scope

Milestone 2 includes only what is necessary to cross the standalone-runtime bar.

In scope

• UEFI loader + freestanding kernel split
• freestanding kernel target on x86_64-unknown-none
• shared boot handoff contract between loader and kernel
• successful ExitBootServices() transition
• kernel-owned runtime after handoff
• serial-first console for QEMU and early bring-up
• startup-script execution after handoff
• reuse of the current shell, VFS, and fs_v1 logic after handoff
• RAM-backed root filesystem created from a preloaded ROOTFS.IMG
• deterministic QEMU acceptance tests that prove post-handoff execution
• generic real-hardware smoke validation on x86-64 UEFI hardware

Out of scope

These are intentionally excluded from milestone 2:

• persistent write-back across reboot
• raw block-device access
• native SATA / AHCI / NVMe drivers
• PS/2 keyboard support as a milestone requirement
• USB keyboard support as a milestone requirement
• multitasking
• scheduler
• user/kernel mode separation
• system calls
• networking
• GUI
• ext4
• page-table redesign beyond what is strictly necessary for bring-up
• user program loading

Milestone 2 success criteria

Milestone 2 is complete when all of the following are true:

1. BOOTX64.EFI loads \SNAPIOS\KERNEL.ELF successfully.
2. The loader gathers the final memory map and exits boot services successfully.
3. The freestanding kernel prints a stable post-handoff marker such as KERNEL: POST_EBS OK.
4. The shell runs after that marker, not before it.
5. The existing milestone-1 command set still works after handoff against a RAM-backed root filesystem.
6. sleep no longer depends on UEFI stall.
7. exit no longer returns to the hosted UEFI shell runtime; it halts or reboots from the freestanding kernel.
8. sync succeeds against the volatile in-memory filesystem image and clearly communicates that the result is not yet durable across reboot.
9. The QEMU acceptance suite passes.
10. Real x86-64 UEFI hardware can boot into the freestanding kernel and run a startup script after handoff.

Shell command set for milestone 2

The command set carried into milestone 2 is:

• help
• echo
• sleep
• pwd
• ls
• cd
• mkdir
• rmdir
• touch
• cat
• rm
• mv
• cp
• sync
• exit

Notes:

• sleep remains sleep N with whole seconds only.
• echo continues to support echo text > file.
• sync in milestone 2 is volatile only. It updates the in-memory serialized rootfs image but does not yet guarantee durability across reboot.
• exit halts or reboots the freestanding kernel. It no longer means “return to the hosted UEFI runtime”.

Milestone 2 console and storage strategy

To keep the milestone lean, Snapi-OS uses this runtime model after handoff:

• serial-first output for QEMU and early bring-up
• startup-script-first execution for automated testing and hardware smoke tests
• RAM-backed root filesystem seeded from a preloaded \SNAPIOS\ROOTFS.IMG

This means:

• the loader reads \SNAPIOS\ROOTFS.IMG before ExitBootServices()
• the loader reads \SNAPIOS\STARTUP before ExitBootServices()
• the kernel receives both as memory buffers in boot info
• the kernel does not depend on UEFI file services after handoff

Milestone 2 deliberately favors a freestanding runtime over persistent storage.

Milestone 2 delivery checkpoints

This milestone is delivered as a sequence of small vertical slices.

Checkpoint A: loader/kernel split ✅

• add a freestanding kernel target
• keep BOOTX64.EFI as the loader
• package \SNAPIOS\KERNEL.ELF on the ESP
• define a shared boot info contract

Checkpoint B: post-UEFI handoff proof ✅

• load the kernel
• gather the final memory map
• call ExitBootServices()
• jump to kernel entry
• print a stable post-handoff marker
• halt cleanly

Checkpoint C: freestanding bring-up essentials ✅

• serial output works after handoff
• panic path works after handoff
• the kernel owns a minimal allocator

Checkpoint D: shell after handoff ✅

• reuse runtime, shell, vfs, and fs_v1
• mount a RAM-backed root filesystem from the preloaded image
• run STARTUP after handoff
• support the milestone-1 command set after handoff

Checkpoint E: acceptance tests and polish ✅

• all TESTING.md minimum acceptance scenarios pass as QEMU tests
• make-esp includes a demo startup script
• sync updates the in-memory serialized image buffer
• mutating commands keep the RAM image consistent
• docs and transcript output clearly state that persistence across reboot is not yet part of the milestone

Checkpoint F: hardware smoke

• boot the same packaged image on real x86-64 UEFI hardware
• prove that the post-handoff marker appears
• run a startup script after handoff
• verify visible equivalence with QEMU for the scripted path

Checkpoints A through E are complete. Checkpoint F is a manual real-hardware validation step.

Planned repository shape for milestone 2

.
├── README.md
├── ARCHITECTURE.md
├── TESTING.md
├── SAFETY.md
├── AGENTS.md
├── docs/
│   └── adr/
│       ├── 0001-uefi-first.md
│       └── 0002-freestanding-runtime.md
├── .github/
│   └── copilot-instructions.md
├── apps/
│   ├── bootx64/
│   └── kernel/
├── crates/
│   ├── bootinfo/
│   ├── elf_loader/
│   ├── platform/
│   ├── platform_uefi/
│   ├── platform_freestanding/
│   ├── runtime/
│   ├── shell/
│   ├── vfs/
│   └── fs_v1/
└── xtask/

Developer prerequisites

The following must be installed before building or testing.

Rust toolchain

The nightly toolchain remains pinned in rust-toolchain.toml.

Add both targets once:

rustup target add x86_64-unknown-uefi
rustup target add x86_64-unknown-none

System packages

Install via your package manager (example for Ubuntu/Debian):

sudo apt install mtools ovmf qemu-system-x86

These remain the baseline milestone-2 host tools.

Cargo tools

cargo install cargo-audit

Standard developer commands

These command names remain the repository contract:

cargo xtask build-efi
cargo xtask make-esp
cargo xtask run-qemu
cargo xtask test-host
cargo xtask test-qemu

For milestone 2, these commands evolve as follows:

• build-efi builds the loader and any artifacts it directly owns
• make-esp packages the loader, kernel, and milestone assets onto the ESP image
• run-qemu boots the freestanding path, not the old hosted-only path
• test-host remains the fast host-side validation loop
• test-qemu becomes the authoritative freestanding acceptance suite

Do not rename these commands unless there is a strong reason to do so.