3.4 KiB
Existing Docker-host KVM diagnostic
This manual-only diagnostic checks whether the existing Ubuntu runner's Docker daemon can expose its already-existing /dev/kvm and successfully initialize QEMU's KVM accelerator. It does not install or load host modules, change the host, or request infrastructure. A prior container configured with KVM=N and no device mappings cannot answer this question.
The entry point is the .NET 10 file-based app tools/ci/ExistingKvmDiagnostic.cs. From the repository root:
dotnet run --file tools/ci/ExistingKvmDiagnostic.cs -- --help
dotnet run --file tools/ci/ExistingKvmDiagnostic.cs -- --run --output artifacts/existing-kvm
dotnet run --file tools/ci/ExistingKvmDiagnostic.cs -- --cleanup --output artifacts/existing-kvm
--run requires an empty output directory, the existing Docker CLI/daemon and Git. It records the source commit/helper SHA-256, Docker context/server identity, exact image metadata, commands, raw stdout/stderr, exit/state evidence, result and cleanup receipts. The workflow .gitea/workflows/macos-kvm-diagnostic.yaml is dispatched manually and always uploads these files. --help invokes no Docker command.
The image is pinned to qemux/qemu:7.50@sha256:e7f6fda52503a546fd649670ba46e4bc23dc6dcef275bc3fac48877fbbc430df; if absent it may be pulled into the existing daemon's cache. One random-name/label container invokes /usr/bin/qemu-system-x86_64 directly with KVM only, -cpu host, -S, no default devices, no display and HMP on stdin. It attaches no OS, disk or volume and never continues the paused CPU. The only host device mapping is /dev/kvm:/dev/kvm:rw. The filesystem is read-only, network is none, all Linux capabilities are dropped, and no-new-privileges is set. Limits are 0.5 CPU, 256 MiB container RAM/no additional swap, 32 PIDs, and 64 MiB paused guest RAM. There are no binds, ports, privileged mode, added capabilities or host networking.
The helper has a 95-second operation budget and a separate 20-second cleanup budget, plus at most two seconds to drain killed command output. The workflow permits five minutes including SDK setup, compilation and upload. Cleanup checks the saved random name/label and exact full container ID before stopping or removing that container. An interrupted create can recover its ID only from the saved random name with the exact ownership label. Cleanup does not remove images, prune resources, or touch another container.
kvm_usable requires QEMU to report both kvm support: enabled and VM status: paused, followed by clean monitor/container exit after quit. A device path alone is insufficient. Other receipts distinguish a Docker-reported missing daemon-host device, observed access denial, an unavailable QEMU KVM backend, an initialization error, and inconclusive evidence. These categories describe the observed output; they do not diagnose BIOS, nested virtualization, policy or hardware causes. All failures remain failed workflow runs with retained raw evidence. Even a usable result proves only this blank paused KVM initialization, not macOS boot, installation, native build or tests.
The CLI and monitor behavior follow the primary QEMU command-line reference and QEMU monitor reference. Device/container options follow the Docker create reference.