[Pedro Henrique Penna (ppenna)]

Part of #1232

What and why

#1232 asks for the virtio restore contract on both the PCI and MMIO
transports, with tests of re-save, reset, and removal before the first start.
Position 039 of the microVM chain, which restores a device's private state
into the stopped device for #1232, promises two parts of that contract on both
transports: a restore rejects an enabled queue of a DRIVER_OK device that
lacks its progress, before the device sees any state; and a save before the
first start returns the restored queue progress and private state. Only the
MMIO transport tested either for an active device. #1308 added the PCI
counterpart of the removal test, but not these. And the module documentation
of the virtio-net saved-state tests still described the deferred restore of
device-private state that position 039's rewrite retired. No product code is
wrong: this completes the tests and the documentation.

microsoft/openvmm#5016 is one commit on a8a0e3517, the head of
feature/microvm/dev:

• cd5cd3814, virtio: test PCI re-save before start and missing queue progress, adds pci_restore_rejects_missing_active_queue_progress and
  pci_resave_before_first_start_keeps_restored_state, and corrects the
  virtio-net test module's documentation. It changes only tests.

This pull request:

• openvmm: pin the PCI transport's restore tests moves the gitlink, and
  nothing else, from a8a0e3517, which openvmm: pin state changes that fail instead of panicking on a lost unit #1448 pins, to
  cd5cd38149419c99a31564631ce6cb6e149a2a7a, the head of
  [DO NOT REVIEW] virtio: test PCI re-save before start and missing queue progress openvmm#5016. The control-session vectors, source excerpts,
  contract versions, and CPU profiles that nvx-rs copies from OpenVMM match the
  revision's.
• doc: map the PCI restore tests in the OpenVMM roadmap maps position 246 as
  not yet assigned, as the roadmap maps position 213, whose tests of position
  039 it extends, and moves the pin there, 115 commits past the mapped tip. It
  conflicts with upstream main, which lacks both test modules, so it follows
  PR13 upstream.

#1232 after this pull request

Met on dev (705412fdd, OpenVMM a8a0e3517), as #1232's latest status
comment records, and since then:

• Awaited restore (acceptance 1): since openvmm: pin microVM v4.0, reorganized onto upstream main #1238, a device's private state, and
  the host resources that it refers to, restore into the stopped device on both
  virtio transports and through the chipset device workers, after the exact
  unit inventory check, so a restore that cannot complete fails before any vCPU
  runs, even for a VM restored paused.
• Nothing runs early (acceptance 2): a restore starts no queue and
  generates no queue notification; removal and reset before the first start
  are covered on both transports (openvmm: pin virtio-net queue starts that fail without endpoint queues #1308), and with this pull request so are a
  re-save before the first start and the rejection of an active queue without
  its progress.
• Pause and resume keep queue progress on both transports, without a
  restore (openvmm: pin virtio-net queue starts that fail without endpoint queues #1308; acceptance 3, in part).
• A partially activated VM never reports success (openvmm: pin device starts confirmed before the VM runs #1316 and openvmm: pin virtio-net queue starts that fail without endpoint queues #1308;
  acceptance 4, in part): each device confirms its start before the VM runs,
  and virtio-net fails a queue start whose endpoint cannot create its queues.
• Failed-save recovery rolls back in dependency order, without a deadline,
  as openvmm: drop the snapshot quiesce timeout and microsoft/openvmm#4625 #1260 decided (openvmm: pin the snapshot quiesce without a deadline #1288; acceptance 5).
• An ordinary resume cannot bypass the rollback (openvmm: snapshot quiesce and boundary release allow ordinary Resume to bypass rollback #1170, fixed by openvmm: pin the rollback as the only way to run a quiesced microVM #1430;
  acceptance 5).
• Later lifecycle requests fail instead of panicking on a unit in a
  terminal state (openvmm: an uncertain snapshot quiesce makes teardown or a later lifecycle request panic #1148, fixed by openvmm: pin the handling of state units in a terminal state #1435) and on a unit whose task has ended
  (openvmm: stop, save, reset or restore panics if a state unit's task has exited #1363, fixed by openvmm: pin state changes that fail instead of panicking on a lost unit #1448; acceptance 5).
• Superseded proposals, error propagation, and documentation: the roadmap
  records state_unit: make unit start fallible and roll back partial starts openvmm#4619, #4622, and #4623 as closed in favor of openvmm: refactor device restoration onto upstream async save/restore #1232;
  the command-line launch, the REPL, the management RPC's resume, and petri
  report a failed resume; OpenVMM's guides and NVX's lifecycle specification
  describe the confirmed start (openvmm: pin device starts confirmed before the VM runs #1316, doc: specify that a failed device start fails the VM's start #1350).

Left open, each blocked outside this repository:

• The restore, prepare, and activate contract with the authors of
  virtio_net: preserve queues across pause and restore from saved cursors openvmm#4713 and virtio_net: separate vhost-user ring enable from start and stop openvmm#4729, both drafts: the retained
  pause, as distinct from the stop that releases queue ownership; restore-time
  reconstruction of the queue cursors; PCI and MSI-X notifications deferred
  until the start; and queue progress across a pause for a virtio-net NIC
  without a static identity (work items 1 to 3, acceptance 3). microVM NICs
  have one, and keep their progress across a pause through position 048's
  save.
• Restore-time interrupt lines: vmcore: synchronize interrupt lines with VM lifecycle openvmm#4855, a draft (work item
  3, acceptance 2). The MMIO transport still sets its interrupt line while the
  VM restores.
• RestoreVM with and without an automatic resume: ttrpc: add SaveVM and RestoreVM APIs openvmm#4553,
  open, and openvmm: add eager-copy snapshot restore to ttrpc RestoreVM openvmm#4676, a draft. Their resume callers must handle
  the fallible resume when they land.
• The final architecture, in the roadmap and with the fork's restoration
  plumbing removed, waits on the above (work item 9, acceptance 7). The chain
  stopped staging device state for activation in its v4.0 reorganization.

Outside the microVM's reach: upstream's remote chipset device proxy still
panics when its device worker ends during a stop or a reset. Only the TPM uses
a remote device worker.

Decisions:

• Scope. Chosen: the tests and documentation that openvmm: refactor device restoration onto upstream async save/restore #1232 asks for and that
  this repository can add now. Alternative: port virtio_net: preserve queues across pause and restore from saved cursors openvmm#4713,
  #4729, #4855, or #4676 into the chain. Reason: each is an upstream draft whose
  contract review may still change, and porting one is a design decision for
  the maintainers. Recommendation: adopt each when it lands upstream, at the
  chain's next rebase, rather than port a draft.
• One commit. Chosen: both tests and the documentation fix in one commit,
  in one OpenVMM pull request. Alternative: separate commits or stacked pull
  requests, as openvmm: pin virtio-net queue starts that fail without endpoint queues #1308 used. Reason: all three align position 039's tests and
  documentation with its contract, and none changes product code.
• An unassigned position. Chosen: map position 246 as not yet assigned, as
  the roadmap maps position 213. Alternative: a PR13 fixup, to fold into
  positions 039 and 048 at the next reorganization.

Landing order: land microsoft/openvmm#5016 first, by fast-forwarding
feature/microvm/dev to the exact pinned revision,
cd5cd38149419c99a31564631ce6cb6e149a2a7a, since OpenVMM's merge button
squashes and would leave the pin off the branch; then merge this pull request.

Validation

Locally, on Windows, OpenVMM at the pin:

• cargo check, cargo clippy --all-targets, cargo doc --no-deps with
  RUSTDOCFLAGS=-D warnings, and cargo nextest run --profile agent for
  -p virtio -p virtio_net: 226 passed and 1 skipped, without warnings;
  cargo xtask fmt --fix changed nothing.
• The new tests fail, as their MMIO counterparts do, when the restore no
  longer requires the progress of an enabled DRIVER_OK queue
  (validate_restored_state), or when a stop before the first start drops
  the restored progress of a queue that never started (capture_stop).
• python scripts\local_gates.py --base origin/dev --run: test-changes (0
  changes to existing tests), markdown-links, test-layout, openvmm-vectors,
  and openvmm-cpu-profiles passed. nvx-cli ran 2188 tests, skipping 88, and
  7 subtests of two guest-script tests in scripts/test_microvm_tests.py,
  test_host_loopback_allow_script_checks_publication_and_traffic and
  test_private_network_ingress_script_checks_policy_and_traffic, hit their
  10-second limit under Git's sh on this loaded machine. They time out the
  same way at origin/dev there, and this pull request changes no script.
  openvmm-ci is left to CI.
• python scripts\openvmm_pin.py check-branch --topic and
  check-roadmap --worktree, and python scripts\nvx.py verify, passed.
• A code-review agent found one problem, an overclaim in the OpenVMM commit's
  message, which was fixed before the commit was pushed.

Hosts, OpenVMM's virtio and virtio_net tests:

Profile	Backend	Host type	Before, at a8a0e3517	After, at the pin
nvx-kvm-test	kvm	virtual-machine	neither PCI test exists	226 passed, 1 skipped
nvx-mshv-test	mshv	virtual-machine	not run: same Linux tests as on nvx-kvm-test, without a hypervisor	not run
nvx-whp-test	whp	virtual-machine	not run: same Windows tests as locally, without a hypervisor	not run

No microVM scenario is affected: the change has no product code, so the
openvmm binary at the pin behaves as at a8a0e3517. Left to CI: the full
matrix that a gitlink change selects, and openvmm-ci, which requires OpenVMM's
CI of the pin.

check_test_changes.py lists no change to existing NVX tests. In OpenVMM, only
the module documentation of the virtio-net saved-state tests changes, and no
existing test.

[Copilot]

🟢 Approval recommended

No active review issues are reported for the roadmap update documenting PCI restore test coverage and its upstream dependency.

No open issues 🎉

What changed in this PR

Updates the OpenVMM roadmap to track the test-only revision that adds PCI restore coverage for #1232, without changing product behavior.

Changes:

• Records pin cd5cd3814 at position 246, 115 commits beyond the mapped tip.
• Documents the PCI tests for missing active-queue progress and re-saving before first start, plus the virtio-net test documentation correction.
• Records position 246’s dependency on PR13 for upstreaming.

File	Description
doc/​openvmm-upstream-roadmap.md	Updates the pin, chain counts, and position 246 mapping with its test scope and upstream dependencies.

_{Review effort: Balanced}