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: AArch64
firmware: AArch64 UEFI
machine: virt
memory: 2 GiB
smp: 4 cores
storage: EFI FAT image plus VirtIO block initfs image
network: VirtIO net
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;
• split VirtIO transport, block, and network drivers;
• VirtIO-backed read-only initfs;
• real EL0 /init ELF loaded from initfs;
• syscall ABI for logging, service control, and exit;
• minimal control plane;
• first AI Cell lifecycle/resource enforcement shape;
• generic memory arena manager;
• shared read-only model arenas;
• private KV/cache, source-index, build-output, and log arenas;
• JSON-like boot telemetry.

Success Criteria

The system boots in QEMU, prints deterministic serial logs, reaches kernel entry, discovers VirtIO block/network, mounts the initfs from VirtIO block, loads a real /init ELF into EL0, and exposes a basic syscall-driven 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, data read/write, heap mappings, user ELF pages, and guarded user stack pages;
• controlled page fault is reported with address and error code;
• SMP starts all configured QEMU CPUs and records per-core state;
• /init is loaded from the VirtIO initfs as an ELF, logs through SVC, drives service state through osctl, and exits cleanly;
• VirtIO block reads a known test block, rejects out-of-range reads, and resets;
• VirtIO net exchanges a test packet, drops malformed packets, and resets;
• AI Cell can be created, prepared, started, stopped, and rejected on resource conflicts;
• shared model arena MVP maps one read-only object into two simulated cells;
• private AI Cell KV/cache, source-index, build-output, and log arenas are created and destroyed through the arena manager.

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