nvx-rs: derive the compatibility keys of templates

.gitattributes

@@ -20,5 +20,7 @@ scripts/setup/tool-versions.conf text eol=lf
 # of its commit only if they are checked out unchanged: check nvx-rs out with LF line endings on
 # every platform, whatever core.autocrlf says.
 nvx-rs/** text=auto eol=lf
+# OpenVMM wrote these template manifests: they are bytes, never text.
+nvx-rs/tests/fixtures/template/**/manifest.bin binary
 
 .github/workflows/*.lock.yml linguist-generated=true

.github/workflows/ci.yml

@@ -139,7 +139,8 @@ jobs:
 
       # nvx-rs's protocol tests read copies of OpenVMM's control-session
       # protocol vectors, because the nvx-rs job cannot check out OpenVMM.
-      # This job can, so it compares the copies with the submodule's files.
+      # This job can, so it compares the copies with the submodule's files,
+      # and nvx::contract's versions of OpenVMM's contracts with OpenVMM's.
       - name: Compare OpenVMM's protocol vectors
         shell: bash
         run: >-

doc/ci.md

@@ -574,7 +574,9 @@ for the curl shim test and the `nvx-rs` build. Each job first builds the
 microVM test and platform jobs of its operating system, as described above.
 Each also runs the ignored `nvx-rs` test `tests/openvmm_vectors.rs`, which
 compares the submodule's control-session protocol vectors with the copies that
-the protocol tests read in the `nvx-rs` job, which cannot check out OpenVMM;
+the protocol tests read in the `nvx-rs` job, which cannot check out OpenVMM,
+and the versions of OpenVMM's snapshot format, saved-state schema, time ABI,
+and restore packet with those of `nvx::contract`;
 see [OpenVMM's vectors](../nvx-rs/tests/vectors/README.md#openvmms-vectors).
 The ignored test `tests/openvmm_cpu_profiles.rs` likewise compares the
 submodule's built-in CPU profiles with the copy of their identities from which

nvx-rs/src/contract.rs

@@ -25,6 +25,26 @@
 //! A release declares the microVM ABI version, the control session version, and the control
 //! contract revision of its artifacts in its `SOURCE-MANIFEST.json`.
 //!
+//! The compatibility key of a template, `nvx::host::template::TemplateKey`, holds the boot and
+//! control versions, and the versions of the contracts through which a template's clones are
+//! restored, which no runtime identity records:
+//!
+//! - [`SNAPSHOT_FORMAT_VERSION`] is the version of OpenVMM's snapshot format: the manifest of a
+//!   capture, and the artifacts that it describes. It changes with the version of OpenVMM's
+//!   snapshot manifest, which refuses a snapshot of any other.
+//! - [`DEVICE_STATE_SCHEMA_VERSION`] is the version of the schema of the saved state of a
+//!   snapshot's devices, which OpenVMM records in its manifest. It changes with it.
+//! - [`TIME_ABI_VERSION`] is the version of the time ABI: the guest's clocks and timers, and their
+//!   repair after a restore. It changes with the time ABI version of OpenVMM's time contract.
+//! - [`RESTORE_PACKET_VERSION`] is the version of the restore packet that OpenVMM gives a
+//!   restored guest, and that the guest decodes. It changes with the packet's layout or meaning.
+//!
+//! Each of these four must match the pinned OpenVMM's, which the ignored test
+//! `tests/openvmm_vectors.rs` checks in the jobs that check out the OpenVMM submodule. The key
+//! also holds the version of the activation contract,
+//! [`activation::VERSION`](crate::activation::VERSION), through which each clone receives the
+//! settings of its own launch.
+//!
 //! The build script includes this file to check bundled artifacts, so it must not depend on the
 //! rest of the crate.
 
@@ -40,6 +60,21 @@ pub const BOOT_CONTRACT_VERSION: u64 = 3;
 pub const CONTROL_SESSION_PROTOCOL_VERSION: u64 = 1;
 /// Control contract revision this crate speaks.
 pub const CONTROL_CONTRACT_REVISION: &str = "nvx-microvm-v2-control-v2";
+/// Version of OpenVMM's snapshot format that this crate reads: the manifest of a capture, and the
+/// artifacts that it describes. It must match `MANIFEST_VERSION` in OpenVMM's
+/// `openvmm/openvmm_helpers/src/snapshot.rs`.
+pub const SNAPSHOT_FORMAT_VERSION: u64 = 6;
+/// Version of the schema of a snapshot's saved device state that this crate reads. It must match
+/// `SAVED_STATE_SCHEMA_VERSION` in OpenVMM's `openvmm/openvmm_helpers/src/snapshot/format.rs`.
+pub const DEVICE_STATE_SCHEMA_VERSION: u64 = 1;
+/// Version of the time ABI that this crate speaks: the guest's clocks and timers, and their repair
+/// after a restore. It must match `TIME_ABI_VERSION` in OpenVMM's
+/// `vmm_core/virt/src/time_abi/mod.rs`.
+pub const TIME_ABI_VERSION: u64 = 1;
+/// Version of the restore packet that OpenVMM gives a restored guest, and that this crate's guest
+/// decodes. It must match `RESTORE_PACKET_VERSION` in OpenVMM's
+/// `vm/devices/chipset_resources/src/microvm_time.rs`.
+pub const RESTORE_PACKET_VERSION: u64 = 4;
 
 /// Returns whether the `openvmm` section of an NVX `SOURCE-MANIFEST.json` declares this contract.
 #[cfg(feature = "host")]

nvx-rs/src/guest/time/decoders.rs

@@ -26,8 +26,14 @@ pub(crate) const GENERATION_ID_SIZE: usize = 16;
 
 /// The magic number that starts every restore packet.
 const PACKET_MAGIC: [u8; 3] = *b"OVR";
-/// The restore-packet version of time ABI version one.
-const PACKET_VERSION: u8 = 4;
+/// The restore-packet version of time ABI version one,
+/// [`RESTORE_PACKET_VERSION`](crate::contract::RESTORE_PACKET_VERSION), which a template's
+/// compatibility key records.
+const PACKET_VERSION: u8 = {
+    let version = crate::contract::RESTORE_PACKET_VERSION;
+    assert!(version <= u8::MAX as u64);
+    version as u8
+};
 /// Restore flag indicating that the downtime came from the host's UTC clock.
 const PACKET_DOWNTIME_UTC: u8 = 0x01;
 /// Restore flag indicating that memory ranges follow.

nvx-rs/src/host/mod.rs

@@ -20,6 +20,10 @@
 //!   with a bounded forced step on request, and reattaches to it after the orchestrator restarts
 //!   within the same host boot. The private `spawn` module, whose items `supervisor` re-exports,
 //!   starts the VMM detached, with no other descriptor or handle of the caller's.
+//! - [`template`] holds the metadata of templates, captures from which clones are restored: the
+//!   compatibility key of a template, [`TemplateKey`](template::TemplateKey), which it derives
+//!   from the [`CaptureClass`](template::CaptureClass) of the capture and the capture's
+//!   [`TemplateManifest`](template::TemplateManifest).
 //! - [`session`] speaks NVX's control protocol, `NVXC`, over [`nvxs`], which runs the host's role
 //!   of the NVXS session for it and for any other application protocol, over a platform
 //!   transport. [`platform`] holds the primitives of Linux and Windows hosts. Other hosts compile
@@ -74,5 +78,6 @@ pub mod supervisor;
 #[cfg(unix)]
 #[allow(unsafe_code)]
 mod sys;
+pub mod template;
 #[cfg(test)]
 mod test_support;