[Pedro Henrique Penna (ppenna)]

Summary

doc/design/cold-boot.md predates two OpenVMM pins, and its fresh-boot
contract no longer matches the submodule:

• The second microVM virtio-fs slot (fs:microvm1, tag microvm1,
  0xd0008000, IRQ 13; pinned in b0ba778) extends the reserved
  virtio-mmio window and the effective command line. The chapter still
  showed eight slots and one filesystem.
• The newest pin (82d944a, microVM: opt in to read-only distro with RAM overlay upper nanvix/openvmm#121) adds the caller kernel
  token nvx_overlay_upper=ramfs, which no NVX document covered.

This PR corrects the memory-layout diagram and the fresh-boot token order,
and documents the overlay token alongside the other command-line rules. It
changes one file and touches nothing outside doc/.

Changes

All evidence paths are in the pinned submodule unless noted.

Statement in doc/design/cold-boot.md	Was	Now	Evidence
Memory-layout diagram, reserved virtio-mmio slots	0xd0000000 through 0xd0007fff	0xd0000000 through 0xd0008fff	MICROVM_VIRTIO_MMIO_BASES lists nine 4-KiB slots, the last at MICROVM_VIRTIO_FS1_MMIO_BASE = 0xd000_8000; validate_microvm_virtio_reservations checks them (openvmm/openvmm/openvmm_defs/src/microvm.rs). Matches "All nine fixed address slots" in doc/design/machine-and-device-abi.md.
Fresh-boot token order, item 4 (discovery)	network, filesystem, boot console, sandbox blocks, control console + nvx_control_tty=hvc2	Adds the second filesystem slot after nvx_control_tty=hvc2, only when a second HostFs export is attached	append_microvm_virtio_discovery writes the first slot after network, then the control console, then slots take(filesystem_slots).skip(1); microvm_filesystem_slot_count returns attached.max(1). The worker check validate_microvm_command_line requires the same order (same file).
Fresh-boot token order, item 5 (bootstrap)	Filesystem bootstrap tokens "for an active HostFs export"	Filesystem bootstrap tokens for each attached HostFs export, in slot order, linking to the triplet in machine-and-device-abi.md#filesystem	The same function zips filesystems with MICROVM_FILESYSTEM_SLOTS. Both launchers bootstrap every attached share on a fresh boot: openvmm/openvmm/openvmm_entry/src/microvm/config.rs (filesystem_bootstrap = !filesystems.is_empty()) and openvmm/openvmm/openvmm_entry/src/ttrpc/microvm.rs (filesystem_bootstrap = true when a share is added).
New paragraph: nvx_overlay_upper	(not documented)	nvx_overlay_upper=ramfs, passed exactly once, requires exactly one read-only distro block and no other block, and supports neither capture nor restore. Any other nvx_overlay_upper token, including a bare or repeated one, is rejected.	ramfs_overlay_requested and validate_microvm_sandbox_blocks (openvmm_defs/src/microvm.rs, applied both in discovery and in worker validation). validate_microvm_options rejects --snapshot-destination and --restore-snapshot with the token (openvmm_entry/src/cli_args/microvm.rs). Covered by test_microvm_ramfs_overlay_requires_one_distro_and_no_snapshot and ramfs_overlay_allows_only_a_read_only_distro_without_scratch. Introduced in f12dcf5e8.
New sentence: the NVX init agent keeps its overlay upper on scratch	(not stated)	Links to the implemented filesystem bootstrap	guest/common/nvx-init-agent (NVX tree) stops with "a scratch device is required"; no NVX guest, script, or crate passes nvx_overlay_upper (git grep returns no matches).

I left the rest of the chapter unchanged after re-checking it against the
pin, including the loader steps, the boot-reservation table (MP table
44 + 17×8 + 20×N bytes, six page-table pages, command line at
0x20000..0x2ffff), the base and caller-reserved tokens, the host-owned
token order (build_effective_microvm_command_line, then finish), the
64-KiB limit, and the SHA-256 recorded in the machine contract.

OpenVMM SHA: f12dcf5e8f2ea60cc15899dd16852320530670bd, the gitlink
on dev at 3ab4bac9d25dd40669b8b3f48956f998d5d5099d.

Follow-ups

These are out of scope here or blocked by other branches:

• doc/design/machine-and-device-abi.md still says "any nonempty
  topology ends with scratch", and its role table calls scratch "Required
  writable final role when blocks are present". Both should allow the
  RAM-backed overlay layout. I didn't touch the file because open PRs Support filesystem-only streamed microVM snapshots #417,
  Adopt bind-once microVM image slots #406, and test-microvm: pause and resume a microVM through OpenVMM state control #405 modify it. The snapshot chapters, also in open PRs, may want
  to note that the layout cannot be captured.

• PR Adopt bind-once microVM image slots #406 (ABI 3 image slots) changes the fixed MMIO inventory. When it
  or any later pin lands, recheck this chapter's reserved-slot range and
  discovery order.

• doc/project-structure.md has drifted:

  • The submodule entry says it is pinned to microvm/mshv, but
    .gitmodules tracks main.
  • It omits the aci_edge_sandboxes/model/ crate
    (aci_edge_sandboxes_model) and the src/agent/ backend.
  • The doc/ tree omits usage.md, contribute.md, guests/, and
    openvmm-upstream-roadmap.md, and the workflow list is incomplete.

  I left it alone because the unopened branch doc-sync/project-structure
  already targets it.

• doc/contribute.md lacks the contribution workflow, branch, commit,
  and PR conventions, Draft vs Ready, quality gates, and pin promotion. The
  unopened branches doc-sync/contribute-standards and
  doc-sync/contributing-guide target it.

• scripts/setup/README.md is documentation outside doc/. Moving it
  requires editing 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 modify.

• doc/openvmm-upstream-roadmap.md has no inbound links. It needs an
  index entry, or removal if it is obsolete.

• Suspected stray file, not documentation: unittest_results.txt
  (50 KB of unittest output, tracked since the initial commit). Consider
  removing it in a code PR.

Validation

• python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests:
  Ran 110 tests, OK (skipped=1). The skipped test needs a Linux
  pseudo-terminal, and this ran on Windows.
• Throwaway checker kept outside the repo. It covered
  doc/design/cold-boot.md and the files that link to it (doc/design.md,
  doc/design/configuration-boundary.md, and 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: 0 errors. I confirmed the checker reports planted
  broken links and anchors, a duplicate H1, an unclosed fence, and an
  unindexed chapter.
• git diff --check: clean.
• python scripts/nvx.py verify: passes.
• python scripts/nvx.py classify-ci-changes --event-name pull_request on
  this diff: "Only documentation files changed", and every suite is false.
• The only changed path, doc/design/cold-boot.md, matches
  ^(doc/|.*\.md$). The openvmm gitlink and the submodule contents are
  unchanged.

[Copilot]

🟡 Changes recommended

The new scratchless layout contradicts the linked machine ABI documentation.

1 open finding

• Update ABI documentation to remove contradictory scratch layout requirements · New

What changed in this PR

Updates cold-boot documentation to match the pinned OpenVMM contract.

Changes:

• Extends the reserved virtio-MMIO range for the second filesystem slot.
• Documents filesystem token ordering and RAM-backed overlays.

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

🧠 Review effort: Balanced

---

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