Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Hardware, Boot, And Storage Backlog

Detailed decompositions for hardware, boot packaging, block devices, and local storage. WORKPLAN.md links here but should not inline these subtasks.

Bootable Disk Image

  • Add make image for GPT + EFI System Partition.
  • Add make run-disk using OVMF.
  • Add initial cloud upload/run notes after QEMU disk boot works.

ACPI And PCIe Discovery

  • Request and map Limine RSDP.
  • Parse MADT enough to enumerate LAPIC/I/O APIC data.
  • Parse MCFG and add PCIe ECAM config-space access beside legacy QEMU I/O-port access.

Interrupt Infrastructure

Depends on ACPI and SMP Phase C LAPIC timer/IPI.

  • Add I/O APIC driver: route IRQs to LAPIC vectors and handle source overrides.
  • Add MSI/MSI-X setup: parse PCI capabilities and configure interrupt vectors.
  • Add interrupt routing table: map PCI devices to vectors.
  • Add optional x2APIC MSR backend for newer/high-core systems and firmware states where xAPIC is unavailable or undesirable.

PCI/PCIe Infrastructure

Promotes PCI enumeration from a networking substep to a reusable subsystem consumed by all device drivers.

  • Add PCI config space access via legacy I/O ports and PCIe ECAM.
  • Add bus enumeration for all buses/devices/functions.
  • Add BAR parsing and MMIO mapping.
  • Add capability list walking for MSI/MSI-X, virtio, and NVMe.

Reusable Block-Device Path

  • Factor shared virtio queue/transport helpers from virtio-net.
  • Add virtio-blk sector read/write smoke.
  • Define the first BlockDevice trait/capability boundary.

Local Disk Storage Milestone

Visible outcome: default storage-focused QEMU boots from a disk image, exposes a read-only directory from local disk, and proves one capnp object can be persisted and read back after reboot.

Ordered gates:

  • Add Store/Namespace plus file-I/O schema slices expected by the storage proposal.
  • Add a RAM-backed Store/Namespace proof so naming and cap-return semantics are verified before disk work.
  • Wire virtio-blk into the BlockDevice boundary and prove sector read/write in QEMU.
  • Add a read-only filesystem service over BlockDevice with a focused QEMU directory-list/open/read proof.
  • Add persistent Store backing over local disk and a reboot proof that stored capnp data survives.

Writable Local Storage Milestone

Visible outcome: a storage-focused QEMU image can create, overwrite, truncate, rename, and remove files through capability-scoped Directory/File caps, persist both file and store mutations across reboot, and recover to a consistent state after an unclean shutdown test.

Ordered gates:

  • Decide and document one fail-closed concurrent-writer policy for the first writable filesystem slice.
  • Add directory mutation operations and a focused QEMU proof for create/mkdir/remove/rename.
  • Add writable File paths with overwrite, append, truncate, explicit sync behavior, and a focused QEMU proof.
  • Persist writable filesystem metadata and data across reboot with verification that names, sizes, and contents survive.
  • Add persistent Store mutation verification on the same local disk path so object writes/deletes survive reboot alongside filesystem data.
  • Add one forced-poweroff or equivalent unclean-shutdown test and verify the filesystem and store recover without silent corruption.

Managed Cloud Store Bridge

Visible outcome: application services can persist bounded Cap’n Proto records through a cloud-backed capability while local QEMU tests exercise the same semantics through a fake bridge.

Ordered gates:

  • Define a provider-neutral CloudStoreBridge or app-specific SaveStore interface with put/get/compare-and-set/append operations, explicit size limits, profile or tenant scoping, schema version, and stale-write rejection.
  • Add a local fake-cloud bridge used by host tests and QEMU smokes. It must reject wrong-profile loads, stale mutable writes, oversized records, and ledger rewrites.
  • Add a GCP deployment note for Cloud Run bridge service, Firestore Native mode mutable indexes/profile summaries, Cloud Storage versioned blobs, and Secret Manager credentials.
  • Add Cloud KMS keying notes for managed game-world storage: key ring/key per world or shard, narrow encrypt/decrypt IAM authority, rotation, retired world revocation, and audit logging.
  • Keep provider credentials outside ordinary capOS clients. Only the bridge service receives cloud credentials; game/storage clients receive narrow capabilities.
  • Add lifecycle/retention/cost controls before writing real snapshots or evidence blobs to Cloud Storage.
  • Treat local disk-backed Store as the offline/QEMU baseline even when cloud persistence is available.

User-Owned Browser Save Transport

Visible outcome: private user data can be backed up through the user’s browser to Google Drive or Firebase as encrypted capsules while capOS never receives provider tokens.

Completed policy and host-test gates:

  • Define provider-neutral browser transport policy for opaque encrypted save capsules, opaque provider handles, capsule metadata, and wrapped-DEK metadata without plaintext, token, key-capability, or KMS grant authority.
  • Add fake Drive and fake Firebase adapters for host tests. They model user deletion, duplicate writes, stale versions, rollback attempts, missing network, non-opaque handles, authenticated-user mismatch, and Firebase auth UID path-segment injection.
  • Add Google Drive appDataFolder notes using the narrow drive.appdata scope for app-private user backup files.
  • Add Firebase/Firestore notes for per-user encrypted capsule documents and offline cache/sync behavior, with the limitation that encrypted game semantics cannot be validated by backend rules.
  • Document that GCP-backed world capsules are encrypted with game-world Cloud KMS envelope encryption, while local-only capsules use local capOS-host key material.
  • Record that browser OAuth/Firebase tokens stay in the browser companion or web terminal host and must not enter ordinary capOS clients, game services, or QEMU transcripts.
  • Record that game-world key capabilities and KMS decrypt/unwrap grants are not exposed to the browser; the browser may transport ciphertext, provider handles, capsule metadata, and wrapped-DEK handles only.

Future real-provider integration gates:

  • Implement real Google Drive and Firebase browser-companion adapters after the provider-token boundary is exercised outside ordinary capOS clients.
  • Reuse the existing save-capsule restore rejection tests as the acceptance gate for real provider adapters: tampered, wrong-profile, stale, oversized, unknown-content, and unsigned capsules must still fail before provider bytes can mutate save state.
  • Add real-provider failure-mode coverage for deletion, duplicate writes, stale versions, rollback attempts, offline cache/sync replay, and missing network using the same semantics as the fake adapters.

Boot Binary ISO Layout

Move ELF payloads out of the Cap’n Proto manifest blob and into the ISO 9660 filesystem as plain files, read on demand through a minimal kernel ISO driver. On-demand ISO reads eliminate the manifest size limit, keep the manifest as pure topology, and decouple binary file changes from manifest rebuilds.

Ordered gates:

  • Minimal ATA PIO CD-ROM read path: identify the ATAPI device on the primary or secondary IDE bus, implement READ(12) packet commands in PIO mode, and surface a bounded read_sectors(lba, count, buf) interface used only during binary loading.
  • Read-only ISO 9660 driver: parse the primary volume descriptor, walk the directory tree to /boot/bins/, implement open_file(name) -> (lba, size), and validate sector reads are in-bounds before use.
  • mkmanifest copies ELF files to iso_root/boot/bins/ and leaves NamedBlob.data empty; the manifest carries names only.
  • Kernel run_init() opens the ISO driver, validates all manifest binary names are present under /boot/bins/, and stores (name, lba, size) entries as the BootBinary registry. ProcessSpawnerCap reads ELF sectors on demand; BootPackage.readBinaryChunk serves bytes from the ISO driver. Retire NamedBlob.data from all kernel paths.
  • Update BOOT_MANIFEST_MAX_BYTES docs and add per-binary Makefile copy targets so only changed files are re-copied on incremental make.

Cloud Device Tracks

  • Add NVMe controller init: admin queue pair and identify controller/namespace.
  • Add NVMe I/O queue pair: submission/completion rings and doorbell writes.
  • Add NVMe read/write commands with PRP-based DMA transfers.
  • Implement BlockDevice for NVMe.
  • Add QEMU NVMe testing via -device nvme.
  • GCP NIC path: virtio-net first, then gVNIC.
  • AWS NIC path: ENA driver.
  • Azure NIC path: MANA driver.