QEMU on macOS

QEMU on macOS

Purpose

This page defines the first engineering target for XAI OS.

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;
• syscall table, process/capability metadata, user pointer validation, and bad syscall tests;
• userspace service-manager policy for restart denial, status reporting, and serial logs;
• build/test sandbox metadata, build artifact arena reservation, and rollback state;
• 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 versioned read-only filesystem from VirtIO block, parses the service config manifest, 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;
• a non-boot CPU can be leased as an AI hot core, rejects duplicate/CPU 0 leases, and reports zero migration and involuntary context switches;
• /init is selected from the filesystem config manifest, loaded from the VirtIO read-only filesystem as an ELF, logs through SVC, drives service state through osctl, and exits cleanly;
• /init exercises unknown-syscall and bad-user-pointer rejection before normal service startup;
• /init configures service-manager restart/log policy, emits manager logs, and verifies denied restart behavior;
• sandbox manifest validation rejects invalid paths/network access and logs build-start, build-finish, and rollback transitions;
• 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
• Hardware Readiness Gate
• QEMU CPU Test Matrix
• Implementation Plan
• Risk Register