Repository navigation
machine: a Spec says the files QEMU opens and what it uses beyond its guest - #434
Merged
Merged
Conversation
… guest spin built each QEMU's root from a release's whole firmware directory and bounded its cgroup at the guest's ceiling plus 768 MiB and 256 tasks. Both depend on the machine and its release. Spec.Files is what QEMU opens by name: its binary, the kernel, the initrd, and the BIOS, linuxboot_dma.bin and kvmvapic.bin. Start hands it everything else as a descriptor. Spec.Overhead is the memory and the tasks QEMU's cgroup holds beyond the guest's RAM at its ceiling, and Disk.Overhead each qcow2 image's caches at QEMU's defaults. task boot:overhead starts spin's shape as nobody in a root of Files and /dev/null alone, takes it to its ceiling while the guest fills its memory and works every disk, checkpoints it, and holds QEMU to both numbers. Measured on the laptop: 73 MiB and 27 tasks at the ceiling, 79 MiB and 34 tasks through the checkpoint, against 153 MiB and 223 tasks. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
spin-stack/machine owns a VM's lifecycle end to end, and spin keeps host policy. spin's runner still hard-codes two facts that depend on the machine and its release, not on spin's fleet. It links a release's whole firmware directory into each QEMU's chroot (
internal/runner/qemu/root.go). It also bounds each QEMU's cgroup at the guest's ceiling plus 768 MiB, and at its vCPU ceiling plus 256 tasks (internal/runner/qemu/bounds.go). This is the last lifecycle piece before a release. spin keeps building the root and applying the cgroup, and it asks the machine what goes in them.What
Spec.Files()lists the files QEMU opens by name: its binary, the kernel, the initrd, and fromFirmwarethe BIOS,linuxboot_dma.binandkvmvapic.bin. Start hands QEMU everything else as a descriptor. A root holding these and/dev/nullstarts the machine.efi-virtio.romis never opened, since every NIC hasromfile=. SeaBIOS is opened only whenBIOSnames it.Spec.Overhead() (Overhead{Memory, Tasks}, error)is what QEMU's cgroup holds beyond the guest's RAM at its ceiling, counting nothing the host can reclaim. Memory is 64 MiB of QEMU's own, the kernel's and the initrd's sizes (QEMU keeps a copy of each), 1 MiB a vCPU, 64 KiB a thread, and 1/256 of the ceiling for page tables (the host's and KVM's, at 4 KiB pages). Tasks are counted up to their most: one a vCPU slot, QEMU's four, a vhost worker for the vsock and each NIC, a checkpoint's 8 channels and their driver, QEMU's thread pool (64, and a thread it cannot start aborts QEMU) and io_uring's workers (the ring's 128 entries).Disk.Overhead()is each qcow2 image's L2 cache (its whole L2 table, up to 32 MiB) plus four clusters of refcounts, QEMU's defaults inread_cache_sizes. It reads each header through the image'sFile, so a hand-builtDiskworks too. A 64 GiB image of 64 KiB clusters costs 8.25 MiB.task boot:overhead(TestAMachineRunsInARootOfItsFilesWithinItsOverhead, root through sudo) holds both.Measured
Laptop, real KVM, v20261121.01, 2026-11-21, spin's shape: 1 of 16 vCPUs, 128 of 8192 MiB, 16 hotplug targets, a root and a home, a vsock and a NIC on a TAP. It ran as nobody in a root holding only
Filesand/dev/null, in a cgroup of its own.Overhead+Disk.OverheadThe threads by name were 16
CPU n/KVM,call_rcu,IO mon_iothread,kvm-nx-lpage-recovery, 2vhost, up to 5iou-wrk, 1 poolworker, and through a checkpointmig/src/mainand 8mig/src/send_. The lane counts QEMU's own memory fromsmaps, outside the guest's RAM mappings, plus the kernel's memory charged to the cgroup, less reclaimable slab. The cgroup'sanonoverstated it by 160 MiB once. A huge page the guest gave back in part stays charged until the kernel splits it under pressure.Not measured: a restore, and a QEMU that has run for days.
Found on the way
Continuenever reached the guest. The lane now plugs before it checkpoints.Verification
go tool task lint test mutate: coverage 80.6% (floor 80), mutate 40 refused, 0 survived.task boot:overheadpassed (laptop, real KVM).task boot:recordpassed.🤖 Generated with Claude Code