QEMU on macOS

QEMU on macOS

Purpose

This page defines the first engineering target for OSAI.

Contents

• Why QEMU First
• Target Shape
• Bring-Up Scope
• Success Criteria

Why QEMU First

QEMU on macOS is for correctness only. It gives a reproducible target for boot architecture, kernel basics, device model, userspace lifecycle, and AI Cell API shape. No performance claims count from QEMU.

Target Shape

Initial target:

arch: x86-64
firmware: UEFI OVMF
machine: q35
memory: 2 GiB
smp: 4 cores
storage: EFI FAT image, later VirtIO block
network: VirtIO net with host port forwarding
console: serial stdio

Bring-Up Scope

The QEMU milestone includes:

• UEFI boot;
• serial console;
• memory map parsing;
• physical memory manager;
• page tables;
• exceptions and interrupts;
• timers;
• VirtIO block;
• VirtIO net;
• minimal shell or control plane;
• first AI Cell lifecycle shape;
• shared model arena MVP.

Success Criteria

The system boots in QEMU, prints deterministic serial logs, reaches kernel entry, loads a minimal init, discovers VirtIO block/network, and exposes a basic control path.

Exact acceptance gates:

• boot log appears on serial stdio;
• UEFI loader hands off to kernel.elf;
• PMM prints usable, reserved, and total memory;
• VMM maps kernel text read/execute, rodata read-only, and data read/write;
• controlled page fault is reported with address and error code;
• SMP starts all configured QEMU CPUs and records per-core state;
• minimal init logs through a syscall and exits cleanly;
• VirtIO block reads a known test block;
• VirtIO net exchanges a test packet;
• AI Cell can be created and destroyed in simulation;
• shared model arena MVP maps one read-only object into two simulated cells.

Risks

• macOS host tools differ by architecture and installation path.
• QEMU success does not prove real hardware performance.
• UEFI memory-map assumptions must be tested, not hardcoded.

Related Pages

• Build System
• Driver Model
• Implementation Plan
• Risk Register