doc: add CPU profiles and the RAM overlay to the configuration boundary

[Pedro Henrique Penna (ppenna)]

Summary

The configuration boundary design chapter was last edited on 2026-09-28. Since then, OpenVMM made the time ABI the microVM's only time path, added CPU profiles, and added the scratchless nvx_overlay_upper=ramfs block layout. The chapter's existing claims are still correct, but it doesn't mention any of these inputs, and its block paragraph implies that blocks always end with scratch. This PR adds them to the chapter and links to the chapters that define them instead of repeating their detail.

OpenVMM source of truth: pinned submodule 3796991d52ce07d88b5dba25e4d1e8deaff6fd95 (origin/dev 57b4a428218951778794931b18d10f99b8ee7583).

Changes

All paths below are in the pinned openvmm/ submodule.

Statement added to doc/design/configuration-boundary.md	Evidence
The microVM requires the time ABI as its only time path, with one CPU profile	openvmm/openvmm_defs/src/microvm.rs validate_machine_config ("the microVM profile requires the NVX time ABI parameters"); openvmm_defs/src/time_abi.rs TimeAbiParameters ("Time ABI parameters of every microVM worker", carrying cpu_profile); OpenVMM commit 12b4f6083 "make the NVX time ABI the only microVM time path"
Cold boot selects the CPU profile with --cpu-profile: a pinned ID, auto (the default), or host	openvmm_entry/src/cli_args/microvm.rs (--cpu-profile doc comment); openvmm_entry/src/microvm/config.rs (unwrap_or("auto"))
The management RPC always uses auto	openvmm_entry/src/ttrpc/microvm.rs (None => ("auto".to_owned(), 0) for cold boot)
auto falls back with a warning to a host profile only on an Intel or AMD CPU that no pinned profile serves	openvmm_core/src/worker/dispatch/time_abi.rs falls_back, FALLBACK_MARKER; vmm_core/cpu_profile/src/derive.rs supports_host_profiles
Restore always uses the snapshot's profile, never falls back, and requires the host's CPU to belong to its generation; an explicit --cpu-profile must be auto, the snapshot's ID, or host for a host-profile snapshot	openvmm_helpers/src/snapshot/time.rs preflight_time_abi_restore (the E_PROFILE_UNKNOWN check and check_generation); openvmm_entry/src/microvm/config.rs (restore takes record.id)
Blocks end with scratch unless nvx_overlay_upper=ramfs is passed. That token requires exactly one read-only distro block and no scratch, and it rules out snapshot capture and restore	openvmm_defs/src/microvm.rs ramfs_overlay_requested, validate_microvm_sandbox_blocks; openvmm_entry/src/cli_args/microvm.rs ("microVM RAM-backed overlay does not support snapshot or restore")

I also re-checked the chapter's existing claims against the pin and found no errors. They cover management-RPC profile value 2 (values 1, 3, and 4 reserved), the 1/2/4/8-vCPU topology, 128-MiB RAM alignment, the rejection of unroled --virtio-blk, raw-file block requirements, the capture rule of "at least one lower layer and scratch", the management RPC's single microvm virtio-fs share with no NIC or blocks, and restore's rejection of --net, workload-identity, and lifecycle options.

Conservative choices:

• The full CPU-profile selection rules stay in Time ABI, CPU profiles, and the RAM-overlay token stays in Cold boot, Effective command line. This chapter only summarizes them and links there.

Follow-ups (out of scope)

• doc/design/machine-and-device-abi.md still says that scratch is the required final writable role, which contradicts the ramfs layout. This was raised in doc: sync cold boot with the second share and RAM overlay #442's review. The file is changed by open PRs test-microvm: pause and resume a microVM through OpenVMM state control #405 and Adopt bind-once microVM image slots #406, so this PR leaves it alone.
• --snapshot-scratch-restore-mode (private-copy, copy-on-write, direct-claimed), from OpenVMM commits 92205a8ce and 0eccda895, isn't documented anywhere in doc/. It belongs in doc/design/snapshot-and-restore.md, which open PRs Adopt bind-once microVM image slots #406 and Support filesystem-only streamed microVM snapshots #417 change.
• doc/guests/ubuntu-guest.md and doc/design/sandbox-filesystem-and-agent-architecture.md list the workload's private mount, PID, and UTS namespaces but don't say that it shares the guest's IPC namespace. guest/alpine/nvx-container-launch runs unshare --mount --pid --uts. This was raised in doc: describe the implemented Ubuntu guest instead of its proposal #453's last review.
• scripts/setup/README.md is documentation outside doc/. Moving it requires editing its links in doc/ci.md and doc/setup.md, which open PRs test-microvm: pause and resume a microVM through OpenVMM state control #405 and Adopt bind-once microVM image slots #406 change.
• doc/openvmm-upstream-roadmap.md describes OpenVMM fork tip 2728f33ea, which is 133 commits behind the current pin. It needs a full regeneration, not a doc-sync edit.

Validation

• python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests: Ran 110 tests, OK (skipped=1).
• A throwaway checker outside the repository checked the changed file and the files that link to it (doc/design.md, doc/design/time-abi.md). Every relative link and anchor resolves, the changed file has one H1 and balanced code fences, and doc/design.md links every chapter in doc/design/. Result: OK.
• git diff --check: clean.
• python scripts\nvx.py verify: passed. The submodule is at the pinned 3796991d.
• Every changed path matches ^(doc/|.*\.md$), so CI treats this PR as documentation-only.

[Copilot]

🟡 Changes recommended

The restore rule conflicts with the linked detailed CPU-profile contract.

1 open finding

• Update CPU-profile contract to document accepted auto restore value · New

What changed in this PR

Updates the configuration boundary to reflect current OpenVMM CPU-profile, time ABI, and RAM-overlay behavior.

Changes:

• Documents CPU-profile selection and restore constraints.
• Adds the scratchless RAM-overlay block layout.

File	Description
doc/​design/​configuration-boundary.md	Expands the documented microVM configuration contract.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.