doc: sync cold boot with the single virtio-fs slot

[Pedro Henrique Penna (ppenna)]

Summary

The OpenVMM pin moved to 7bf0ee28b826374a2d386067df0456b81bcae818, which includes nanvix/openvmm 3072d7a91 ("microVM: share several host directories through one virtio-fs slot"). That commit removed the second virtio-fs slot (fs:microvm1, 0xd0008000, IRQ 13), made several host directories share the one slot as an aggregate, and reserved the virtfs_aggregate= bootstrap token. Machine and device ABI already describes the single slot, but Cold boot still described the two-slot layout and left the new reserved token out of its list. This PR fixes doc/design/cold-boot.md only.

Changes

Statement in doc/design/cold-boot.md	Correction	Evidence (pinned OpenVMM)
Memory-layout diagram: reserved virtio-mmio slots span 0xd0000000 through 0xd0008fff	0xd0000000 through 0xd0007fff	MICROVM_VIRTIO_MMIO_BASES in openvmm/openvmm_defs/src/microvm.rs lists eight slots, the last at 0xd000_7000 (length 0x1000). Its tests assert that 0xd000_8000 is not a slot. At the previous pin (f12dcf5e8), that array had nine entries and included MICROVM_VIRTIO_FS1_MMIO_BASE = 0xd000_8000.
Discovery-token order names "the first filesystem slot"	"the filesystem slot"	MICROVM_FILESYSTEM_SLOTS has one entry (fs:microvm0). append_microvm_virtio_discovery emits network, filesystem slot, boot console, sandbox blocks, then the control console followed by nvx_control_tty=hvc2.
The list of tokens callers may not supply omits virtfs_aggregate=	Add virtfs_aggregate=	build_microvm_command_line_inner rejects user tokens that start with virtfs_aggregate=. validate_microvm_command_line counts it among the profile-owned tokens. MicrovmFilesystemConfig::command_line_fragment appends virtfs_aggregate=1 for an aggregate.

The rest of the chapter matches the pinned code: the token order in build_effective_microvm_command_line, the 64-KiB limit, the boot reservations (six page tables at 0x4000, MP config table 180 + 20 * vCPUs at 0x400, command line at 0x20000, status page at 0x30000), and the base command lines.

OpenVMM SHA: 7bf0ee28b826374a2d386067df0456b81bcae818. Base: dev at 165677e358093c1311ccd297331e72d0f51cbf86.

Follow-ups

These are out of scope here, and the first two are in files that open PRs change:

• doc/design/integrated-implementation-status.md still says "nine reserved virtio-mmio slots" (now eight). Adopt bind-once microVM image slots #406 changes this line but keeps "nine" and still describes a second virtio-fs slot, so it needs the same correction when it rebases onto the current pin.
• Adopt bind-once microVM image slots #406 also describes fs:microvm1 at 0xd0008000 in machine-and-device-abi.md, which predates the one-slot pin. Its rebase should reconcile that too.
• doc/openvmm-upstream-roadmap.md records the fork tip 2728f33ea. The pinned revision is 139 commits past it, so its commit-to-PR mapping is stale. Refreshing it needs a new fork-chain analysis, which is too large for a doc-sync slice.
• scripts/setup/README.md is documentation outside doc/. Moving it means editing links in doc/setup.md and doc/ci.md, which test-microvm: pause and resume a microVM through OpenVMM state control #405 and Adopt bind-once microVM image slots #406 change, and updating the path list in scripts/test_nvx_tools.py, so I left it in place.

Validation

• python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests: Ran 110 tests, OK (skipped=1).
• A throwaway link checker outside the repo covered every relative link and anchor in doc/design/cold-boot.md and the 5 files that link to it, one H1 and balanced code fences in the changed file, and that doc/design.md links every chapter in doc/design/: OK.
• git diff --check: clean.
• python scripts\nvx.py verify: passes, and the submodule HEAD equals the gitlink.
• Every changed path matches ^(doc/|.*\.md$), so CI treats this as documentation-only.

[Copilot]

🟢 Approval recommended

The documentation changes accurately match the pinned OpenVMM implementation.

0 open findings

What changed in this PR

Aligns cold-boot documentation with the pinned OpenVMM single virtio-fs slot ABI.

Changes:

• Corrects the reserved virtio-mmio range.
• Updates filesystem-slot terminology.
• Documents virtfs_aggregate= as host-reserved.

File	Description
doc/​design/​cold-boot.md	Synchronizes memory-layout and command-line documentation.

🧠 Review effort: Balanced

---

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