QEMU Full OS Core Workdown

QEMU Full OS Core Workdown

Purpose

This page tracks the work required to move OSAI from a QEMU readiness gate to a real QEMU full OS core.

The QEMU hardware-readiness gate is useful, but it is not the same as a complete OS. Intel hardware work should not start until the QEMU core has stable process, userspace control-plane, persistence, networking, CPU-AI runtime, security, telemetry, and filesystem contracts.

Contents

• Completion Rule
• Phase Q1: Real Process Lifecycle
• Phase Q2: Real Userspace Control Plane
• Phase Q3: Real Filesystem and Persistence
• Phase Q4: Networking Depth
• Phase Q5: CPU-Only AI Runtime Depth
• Phase Q6: Security Enforcement
• Phase Q7: QEMU Release Candidate
• Phase Q8: Full Filesystem

Completion Rule

Do not start Intel hardware code until this QEMU workdown has a release candidate gate with stable ABI, telemetry, filesystem, process, security, and control-plane contracts.

Phase Q1: Real Process Lifecycle

Goal: stop treating /init as a one-way kernel-hosted test and make EL0 process execution return cleanly to kernel supervision.

Current status:

• Done: process states: empty, loaded, running, exited, failed.
• Done: process lifecycle transition counters.
• Done: sys_exit marks the current process exited or failed.
• Done: EL0 exit returns to a kernel continuation.
• Done: process lifecycle telemetry.
• Done: child service descriptor parsing from /etc/osai-init.conf.
• Done: /init defines, starts, and reports the child /svc/source-index service record through osctl.
• Done: invalid-transition and failed-exit lifecycle tests.

Definition of done: QEMU boot proves /init loads, runs, exits, and the kernel resumes after EL0. Telemetry includes loaded, running, exited, failed, transition counters, child service descriptor count, and service transition count.

Verification:

• make qemu-smoke
• make qemu-readiness-gate

Phase Q2: Real Userspace Control Plane

Goal: move policy decisions out of kernel fixtures and into userland service management.

Required work:

• Done: split userland into /init and /bin/service-manager payloads.
• Done: add /etc/services/source-index.svc as the first read-only service descriptor.
• Done: add descriptor-read and service status/start/stop/restart/rollback/update syscalls.
• Done: keep service operations behind capability checks.
• Done: prove missing rollback/update capabilities fail closed.
• Done: emit control-plane syscall, denial, and descriptor-read telemetry.

Definition of done: QEMU boot proves /bin/service-manager runs as a second EL0 process, reads the ROFS service descriptor, manages /svc/source-index, and reports control-plane telemetry.

Verification:

• make qemu-smoke
• make qemu-readiness-gate

Phase Q3: Real Filesystem and Persistence

Goal: replace metadata-only persistence with serialized state records and mutable VirtIO-backed state.

Required work:

• Done: mutable state region on the VirtIO test block image.
• Done: serialized boot, service, workspace, sandbox, and update records.
• Done: checksum and version validation for persistence records.
• Done: persisted records reload after a QEMU reboot.
• Done: rollback restores prior service and workspace records.
• Done: read-only system image and mutable state boundaries are explicit.

Definition of done: make qemu-persistence-reboot proves the same VirtIO state image survives a two-boot QEMU run, reports persistence_boot_loads, and validates rollback after reload.

Verification:

• make qemu-smoke
• make qemu-persistence-reboot
• make qemu-readiness-gate

Phase Q4: Networking Depth

Goal: move beyond parser smoke paths into queue-backed packet flow.

Required work:

• Done: queue-backed RX/TX packet ownership.
• Done: UDP flow table with queue/core ownership.
• Done: minimal TCP state machine with SYN timeout accounting.
• Done: packet lifetime/drop counters.
• Done: malformed packet tests remain enforced.
• Done: p50/p95/p99/p999 correctness telemetry.

Definition of done: make qemu-smoke proves packets move through queue metadata, creates a UDP flow, expires a TCP SYN flow, and reports packet lifecycle/drop counters plus p999 latency telemetry.

Verification:

• make qemu-smoke
• make qemu-readiness-gate

Phase Q5: CPU-Only AI Runtime Depth

Goal: turn the deterministic CPU-AI stub into real boundaries that can later host actual CPU-only model code.

Required work:

• Done: model-loader interface and manifest format.
• Done: tokenizer/runtime boundary.
• Done: shared read-only model weights.
• Done: private KV/cache arenas per AI Cell.
• Done: multi-cell shared-weight tests.
• Done: model load failure tests.
• Done: GPU acceleration remains outside the runtime contract.

Definition of done: make qemu-smoke requires model load, load failure, tokenizer, runtime, KV/cache write, shared-weight bind, and GPU rejection telemetry.

Verification:

• make qemu-smoke
• make qemu-readiness-gate

Phase Q6: Security Enforcement

Goal: make capability policy enforce service, filesystem, Git/workspace, update, rollback, and build/test permissions.

Required work:

• Complete: extend capability checks across service operations.
• Complete: enforce filesystem read/write boundaries.
• Complete: enforce Git workspace write and patch permissions.
• Complete: enforce build/test sandbox permissions.
• Complete: strengthen signed update validation beyond the current stub.
• Complete: add rollback authorization tests.
• Complete: ensure secrets are rejected from logs, updates, and benchmark records.

Definition of done: denied operations fail closed and emit telemetry counters for capability, filesystem, workspace, sandbox, rollback, update-policy, credential, and signature rejection paths.

Verification:

• make qemu-smoke
• make qemu-readiness-gate

Phase Q7: QEMU Release Candidate

Goal: freeze the QEMU full OS core contract.

Required work:

• Complete: expand make qemu-readiness-gate to include CPU matrix tiers.
• Complete: freeze syscall ABI.
• Complete: freeze telemetry schema.
• Complete: freeze filesystem format.
• Complete: freeze persistence record format.
• Complete: freeze service descriptor format.
• Complete: document what remains out of scope for Intel bring-up.

Definition of done: a single QEMU release-candidate gate proves process, userspace control, persistence, networking, CPU-AI runtime, security, CPU matrix, and documentation contracts are stable enough to start Intel Desktop work.

Release-candidate contract:

• contracts/qemu-rc-v1.json
• schema: osai.qemu.release_candidate_contract.v1
• generated CPU report: build/qemu-cpu-matrix-report.json

Phase Q8: Full Filesystem

Goal: move beyond the read-only boot filesystem and single-sector persistence records toward a real mutable filesystem area.

Required work:

• Complete: reserve a separate VirtIO-backed mutable filesystem sector range.
• Complete: add checksum-protected filesystem metadata.
• Complete: add explicit read-write mount policy.
• Complete: add create/update/read/delete file operations.
• Complete: add commit and rollback boundaries for mutable files.
• Complete: add QEMU smoke and benchmark gates for mutable filesystem telemetry.
• Complete: add a real block allocator instead of fixed one-sector file slots.
• Complete: add directory records and path traversal beyond fixed prefixes.
• Complete: add larger files spanning multiple sectors.
• Complete: add crash-consistency transaction replay.
• Complete: connect service, workspace, and update state to the mutable filesystem.

Definition of done: QEMU proves mutable filesystem mount, mutation, checksum validation, allocation, directory records, multi-sector files, journal replay, delete behavior, reboot load, and rollback behavior without weakening the read-only boot filesystem boundary. A later production-ready filesystem can add a POSIX-like surface and larger storage area, but the QEMU contract no longer depends on fixed one-sector file slots.

Related Pages

• QEMU on macOS
• QEMU CPU Test Matrix
• Hardware Readiness Gate
• Filesystem and Storage
• Implementation Plan
• Roadmap