[Pedro Henrique Penna (ppenna)]

Summary

Retarget every NVX citation of the time ABI specification that #529 removed (doc/design/time-abi.md), fold the specification's remaining architecture-level detail into section 3.2 of the guide, leave its implementation detail to the code that defines it, and pin an OpenVMM revision whose time ABI documentation no longer depends on NVX's documents.

Fixes #562.

Why

#529 replaced doc/design/ with the architecture-only guide. NVX code, tests, and documentation, and OpenVMM's time ABI comments, still cited "the spec": its sections, the snapshot agent's and the restore's old step numbers, and conformance checks such as C3, C8, and C11, which no remaining document defines.

What changed

Folded into 3.2.10, Guest Obligations (doc/design/3.2-clock-and-time.md)

• Which checks capture and restore rerun, instead of "the relevant subset": capture reruns the clocksource, tick-device, and watcher checks; restore reruns them, checks the declared rate in the frequency MSR again, and checks the identity leaves, CPU time bits, and CPU flags of every processor that it brings online.
• What the state file reports.
• That restore repair and the discipline step the clock through the kernel, so a workload can observe each step with a timerfd armed with TFD_TIMER_CANCEL_ON_SET.

The rest of the specification's architecture-level content is already in the guide: the guest's fail-fast statuses (5.6), generations (5.5.6), the rejection of clock tokens in the command line (5.1), and capture rollback (5.3). Its implementation detail stays out of the documentation: the E_* and G_* codes, the check IDs, the NVX-TIME-ABI line formats, the state file's path and keys, the watcher's kernel log patterns, report-only mode, and the warp probe's method. guest/common/nvx-time.c now says that it defines them.

Snapshot-agent steps follow the guide

guest/common/nvx-time.c, guest/common/nvx-snapshot, and their tests number the steps as guest preparation (5.3.2) and guest repair (5.5.7) do:

Removed specification	Guide
Capture step 1	Preparation step 1
Capture steps 2 and 3	Preparation step 2
Capture step 4	Preparation step 3
Capture step 5	Preparation step 4
Restore steps 6 to 10	Repair steps 1 to 5
Restore step 11	Part of repair step 7
Restore step 12	Repair step 6
Restore step 13	Repair step 7

The step13 identifiers become deferred_restore ones, including nvx-time's test hook, now deferred-restore-cpu. The comment on repair_restore now names repair steps 2 and 3, because cmd_capture reads the status itself.

Retargeted citations, with no behavior change

• doc/build.md and doc/ci.md describe checks C8, C3, and C11 in words.
• scripts/nvx_tools/doctor.py runs its checks "in ID order", as the --checks help text now says.
• scripts/nvx_tools/microvm_tests.py, scripts/nvx_tools/time_abi.py, and scripts/test_time_abi.py cite doc/ci.md, the guide, or CHECK_CPU_BUDGET_US.
• scripts/test_guest_time.py: the restore packet and time sample fixtures follow the guide (5.5.5 and 3.2.9), and the exhaustive-check and state-file fixtures pin the formats that nvx-time.c defines.

OpenVMM pin

• Source: openvmm: make the time ABI documentation standalone nanvix/openvmm#136, "openvmm: make the time ABI documentation standalone".
• Pinned revision: c6d97c529986c0b3b1bf1fd7f00406654cdeee67, one SSH-signed commit directly on nanvix/openvmm main at 7f225e2cd635bbd1e1839e587e659996433396c8, the previous pin. git diff --submodule=log shows exactly that commit.
• Scope: comments and test names only. OpenVMM's time ABI comments cited the removed specification by path, by its "Backend obligations" table, by its step numbers, and as "the specification"; they now state what the code does and refer only to OpenVMM's own items, rather than being retargeted to NVX's guide. Three tests named after the specification are renamed. There is no behavior change.
• doc/openvmm-upstream-roadmap.md indexes the new pin as position 318.
• Merge order: merge openvmm: make the time ABI documentation standalone nanvix/openvmm#136 first, by fast-forward as the fork merges, so that c6d97c529 lands on main unchanged; then merge this PR. If Update OpenVMM to validate time-adjusted restores #136's commit changes before it merges, this PR needs the pin moved to the merged commit.

Validation

NVX:

• scripts/nvx.py verify at the new pin: the source tree and submodule metadata are consistent.
• Every relative link and anchor in the repository's Markdown files resolves, except one that was already broken in aci_edge_sandboxes/README.md.
• ruff check, ruff format --check, and pyright for Linux and Windows.
• The validate-nvx unit tests: 1,042 tests pass.
• On Linux, scripts/test_guest_time.py compiles nvx-time.c with -Werror, and 28 of its 29 tests pass; the musl build test skips without musl-gcc.
• shellcheck and shfmt on the guest scripts, with pip-installed versions rather than CI's pinned images.

OpenVMM, at c6d97c529:

• cargo clippy --all-targets and cargo doc --no-deps for every modified package, virt_whp on Windows and the other eight on Linux (WSL): no lints, and no documentation warnings from these packages.
• cargo nextest run --profile agent: 786 passed and 20 skipped on Linux; virt_whp's 45 passed and 17 skipped on Windows.
• cargo xtask fmt --fix: clean.

Head submitted to CI: 75ad88a09919ecbea05c43eab238935e8a06670b. Because the pin, guest/, and scripts/ changed, CI rebuilds OpenVMM and runs the full matrix; the KVM, MSHV, and WHP runtime gates are pending there.

[Copilot]

🟢 Approval recommended

The documentation matches the implementation, identifier updates are consistent, and no blocking issues remain.

0 open findings

What changed in this PR

Updates NVX references after #529 removed the time ABI specification, addressing the NVX portion of #562 while leaving OpenVMM changes separate.

Changes:

• Documents remaining architecture-level time obligations in the guide.
• Retargets comments and help text to current documentation or implementation definitions.
• Aligns snapshot step references and deferred-restore identifiers with the guide, without changing runtime behavior.

File	Description
scripts/​test_time_abi.py	Removes obsolete specification references from comments.
scripts/​test_microvm_tests.py	Aligns preparation-step comments with the guide.
scripts/​test_guest_time.py	Clarifies fixture sources and renames the deferred-restore test hook.
scripts/​nvx_tools/​time_abi.py	Updates CPU-profile and skew-bound citations.
scripts/​nvx_tools/​microvm_tests.py	Points scenario comments to CI documentation.
scripts/​nvx_tools/​doctor.py	Clarifies budget references and check-order help.
guest/​common/​nvx-time.c	Updates step comments and deferred-restore identifiers.
guest/​common/​nvx-snapshot	Aligns snapshot step comments with the guide.
doc/​design/​3.2-clock-and-time.md	Expands checks, state reporting, and clock-step obligations.
doc/​ci.md	Replaces obsolete check IDs with descriptions.
doc/​build.md	Describes stall-detector requirements without obsolete IDs.

🧠 Review effort: Balanced

---

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

[Copilot]

🔵 Needs a closer look

The prerequisite OpenVMM merge and reported pending cross-platform runtime gates require confirmation before approval.

0 open findings

🧠 Review effort: Balanced