microVM: opt in to read-only distro with RAM overlay upper

[esaurez]

Summary

• Permit a microVM with exactly one read-only distro block and no scratch block only when the kernel command line contains exactly one nvx_overlay_upper=ramfs token.
• Reject other scratchless layouts, malformed (including bare) or duplicate overlay tokens, and snapshot/restore for this profile. Existing scratch-backed layouts retain their behavior.
• Exercise both the machine-contract and CLI validation paths.
• Document the layout, its token, and its snapshot/restore restriction in the Guide's run page and CLI reference.

This replaces #112, which carried the same change on a historical base that predates the CPU profiles. On main it needed two adjustments: validate_microvm_command_line keeps main's validate_microvm_filesystem_devices check next to the sandbox-block check, and the new test passes &[] for the virtio-fs list that append_microvm_virtio_discovery now takes.

It is now rebased onto 96e2363, the current main and the revision that microsoft/nvx's dev pins. Since the previous base it adds the WHP CPUID fix, generation-bound microVM snapshots, scratch binding by file identity, and the fallback from --cpu-profile auto to a host profile. The change applied without conflicts.

Validation

• At f12dcf5, on Windows with Rust 1.95.0: cargo clippy --all-targets, cargo doc --no-deps, and cargo nextest run --profile agent (20 and 184 tests) pass for openvmm_defs and openvmm_entry, and cargo xtask fmt --fix passes. The review fixes add regression cases for bare and repeated tokens to the two new tests.
• cargo test --locked -p openvmm_defs -p openvmm_entry with Rust 1.95.0: 20 and 184 tests on Windows, and 20 and 217 on Linux, including the two new ones.
• With a Windows release build, the dependent NVX native-host guest suite passes on an AMD EPYC 7763 WHP host, which amd.milan.v1 serves. Its 25 tests cover the lifecycle, streamed executions, robustness, image registration, host paths, network policies, the proxy, forwarded ports, and exec environments. NVX's openvmm_e2e suite (7 tests) passes too.
• With a Linux build, the same suites pass on an AMD EPYC 9V74 MSHV host with the host CPU profile. On that host --cpu-profile auto selects amd.genoa.v1, which the hypervisor cannot present (E_PROFILE_UNSUPPORTED: it lacks tsa_l1_no_support and tsa_sq_no_support), so the fallback does not apply.
• The guests boot NVX's Linux 6.18.38 kernel and tick on the LAPIC timer, as the time ABI requires.

The dependent opt-in consumer is microsoft/nvx#418.

[Copilot]

🟡 Changes recommended

Malformed bare overlay tokens bypass the new validation.

2 open findings

• Reject bare or duplicate nvx_overlay_upper tokens · New
• Document ramfs overlay layout and snapshot restrictions · New

What changed in this PR

Adds an opt-in RAM-backed overlay for microVMs with one read-only distro block and no scratch device.

Changes:

• Adds shared overlay-token and block-layout validation.
• Rejects snapshot/restore options for this profile.
• Adds machine-contract and CLI validation tests.

File	Description
openvmm/​openvmm_entry/​src/​cli_args/​microvm.rs	Enforces CLI restrictions and adds validation tests.
openvmm/​openvmm_defs/​src/​microvm.rs	Adds overlay parsing, permits the distro-only layout, and tests discovery.

🧠 Review effort: Balanced

---

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.