diff --git a/doc/ci.md b/doc/ci.md index 32292fbce..09bef180f 100644 --- a/doc/ci.md +++ b/doc/ci.md @@ -808,8 +808,9 @@ Each also runs the ignored `nvx-rs` test `tests/openvmm_vectors.rs`, which compares the submodule's control-session protocol vectors, and the lines of its platform allowlist of kernel command-line tokens, with the copies that the protocol and template 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 packets with those of `nvx::contract`; +OpenVMM, the versions of OpenVMM's snapshot format, saved-state schema, +time ABI, and restore packets with those of `nvx::contract`, and the bound of +the restore packet's activation record with that of `nvx::activation`; 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 diff --git a/doc/design/1.5-compatibility-and-versioning-model.md b/doc/design/1.5-compatibility-and-versioning-model.md index 01097f645..261360934 100644 --- a/doc/design/1.5-compatibility-and-versioning-model.md +++ b/doc/design/1.5-compatibility-and-versioning-model.md @@ -17,7 +17,7 @@ contract carries its own version or identity, independent of the others. | Device-private schemas | Saved queue and device state that must be understood before a device can resume. | | Snapshot format | Persisted machine contract, manifest, state inventory, memory geometry, attachment requirements, and artifact identity. | | RAM expansion capability | Recorded RAM capacity, memory-block size, and expansion ranges that restore may activate. | -| Restore packet | Layout and meaning of the one-time record that gives a restored guest its generation, downtime, rate deviation, activation targets, and fresh entropy. | +| Restore packet | Layout and meaning of the one-time record that gives a restored guest its generation, downtime, rate deviation, activation targets, fresh entropy, and a platform clone's activation record. | | Control protocol | Authenticated sessions between the host and the guest agents, request framing, operation semantics, and lifecycle epochs. | | Management RPC machine profile | Identity of the microVM machine profile in the management RPC. | diff --git a/doc/design/5.5-restore-protocol.md b/doc/design/5.5-restore-protocol.md index adcdfca3a..b1edb272b 100644 --- a/doc/design/5.5-restore-protocol.md +++ b/doc/design/5.5-restore-protocol.md @@ -208,7 +208,9 @@ flags. Every restore exposes one restore packet through the byte channel, for every tier and for untiered snapshots. The packet is version 1. A restore that installs a new network policy on a snapshot without a tier sets its `NETWORK` flag, and its network byte and DNS server carry the policy's settings; every -other restore leaves both zero. +other restore leaves both zero. A platform restore that hands its clone an +activation record sets the `ACTIVATION` flag, and the packet ends with the +record; every other packet ends with the DNS server. ```text offset size field @@ -224,6 +226,8 @@ offset size field 24 16*n ranges n x { u64 gpa_start, u64 length }, LE 24+16n 64 entropy 88+16n 16 dns_server zero unless NETWORK +104+16n 4 activation_length u32, little-endian, 1 to 1024; only with ACTIVATION +108+16n L activation_record L = activation_length bytes; only with ACTIVATION ``` **Figure 5.7.** Restore packet layout. @@ -237,12 +241,14 @@ offset size field | 2 | `ACK_REQUIRED` | Host input is gated, and the guest must acknowledge through the snapshot port after repair | | 3 | `TEST_HOOKS` | Host overrides of the downtime, UTC, rate deviation, host clock rate, time samples, or CPU profile are active | | 4 | `NETWORK` | The network byte and the DNS server carry network settings | -| 5-7 | | Zero; the guest rejects a packet with any of them set | +| 5 | `ACTIVATION` | The packet ends with a platform clone's activation record | +| 6-7 | | Zero; the guest rejects a packet with any of them set | Every field is sealed before the first restored processor runs. The packet carries no host UTC: the guest takes a [time sample](3.2-clock-and-time.md#329-time-samples) after it, which pairs host UTC -with the guest TSC on the host. A packet without ranges is 104 bytes. The packet +with the guest TSC on the host. A packet without ranges or an activation record +is 104 bytes, and an activation record of `L` bytes adds `4 + L`. The packet is authoritative, and the status bits mirror it; the acknowledgement flag spares the guest from inferring gating from the tier and targets. A VM process exposes at most one packet, and reading its last byte consumes it, so a guest captured @@ -265,6 +271,22 @@ ingress or explicit host-loopback access. Such a restore always sets `ACK_REQUIRED`, so the guest applies the settings before host input reaches it. +The `ACTIVATION` flag marks the activation record of a platform snapshot's +clone, which the launcher supplies with +`--restore-activation-record`: the settings of the clone's own launch, in the +canonical encoding of an activation record, which the host and the guest share +through `nvx::activation`. OpenVMM reads the record before any processor runs +and passes its bytes through without interpreting them, so the record carries +no secret: secrets and host mapping tables stay on the authenticated control +channel. Its length, 1 to 1,024 bytes, precedes it as a `u32`, which keeps the +record aligned to the guest's four-byte reads, and the guest rejects a length +outside those bounds. Each four bytes of the record cost the guest one more +port access, as every byte of the packet does. The flag was a reserved bit, +which a guest that predates it rejects, so such a guest fails a restore that +hands it a record rather than ignore the record, and restores without a record +are unchanged. Such a restore always sets `ACK_REQUIRED`, so the guest has read +the record before host input reaches it. + ## 5.5.6 Generations - The generation counter `g` is zero in a cold-booted process and the captured @@ -288,8 +310,8 @@ runs before the acknowledgement: 1. Read the byte-channel status, whose restore-packet bit is always set after a restore. 2. Select the packet, read it four bytes per access, and validate its magic, - version, reserved bits, counts, network settings, generation, and - generation ID. + version, reserved bits, counts, network settings, activation record's + length, generation, and generation ID. 3. Set the wall clock: in the same port transaction as the packet, take up to three [time samples](3.2-clock-and-time.md#329-time-samples) of the packet's generation, until one pairs host UTC with the guest TSC within diff --git a/doc/openvmm-upstream-roadmap.md b/doc/openvmm-upstream-roadmap.md index ce94e5d1e..a8524e317 100644 --- a/doc/openvmm-upstream-roadmap.md +++ b/doc/openvmm-upstream-roadmap.md @@ -8,10 +8,11 @@ reorganization kept it there; see [Upstream status](#upstream-status). - Mapped fork tip: `7677ad8d56a59864475012b63b6f01a22575c30d`, position 131. The graph, PR summary, and commit mapping below cover positions 001-131. -- NVX's pinned OpenVMM revision: `6cb6ba87cfb6707078d19f09ec81d9a78fcd1ede`, position 232, the - head of microsoft/openvmm#4995, whose commit follows position 231, `98e5b3ca5`, the head of - `feature/microvm/dev`, which microsoft/openvmm#4994 merged with position 230 after position 229, - `ed8fc0713`, which microsoft/openvmm#4993 merged after position 228, `d6addf8c1`, which +- NVX's pinned OpenVMM revision: `d501e50660136000ec93412aea78fdafb9cf391c`, position 233, the + head of microsoft/openvmm#4996, whose commit follows position 232, `6cb6ba87c`, the head of + `feature/microvm/dev`, which microsoft/openvmm#4995 merged after position 231, `98e5b3ca5`, + which microsoft/openvmm#4994 merged with position 230 after position 229, `ed8fc0713`, which + microsoft/openvmm#4993 merged after position 228, `d6addf8c1`, which microsoft/openvmm#4992 merged after position 227, `154548a0e`, which microsoft/openvmm#4991 merged after position 226, `881619911`, which microsoft/openvmm#4989 merged after position 225, `99aac19b3`, which @@ -25,8 +26,8 @@ position 221 into positions 035 and 036, and combined v5.1 positions 222 and 223, the two commits of microsoft/openvmm#4984, into position 220. Positions 001-147 keep their positions, v5.1 positions 149-220 are positions 148-219, and the tree of position 220 is the tree of - `3f2ab4c2f`; see [The v6.0 reorganization](#the-v60-reorganization). The pin is 101 commits past - the mapped tip on the same first-parent chain. Positions 132-232 are not yet assigned to PRs; see + `3f2ab4c2f`; see [The v6.0 reorganization](#the-v60-reorganization). The pin is 102 commits past + the mapped tip on the same first-parent chain. Positions 132-233 are not yet assigned to PRs; see [Commits after the mapped tip](#commits-after-the-mapped-tip). - Upstream main: `ba105dd7f00499acc1862456c179c0930cb2c8f7` (2026-11-06), the fork base itself; see [Upstream main past the fork base](#upstream-main-past-the-fork-base). @@ -986,7 +987,8 @@ ba105dd7f -> earlier snapshot formats refused before decoding [230] -> manifest fields reserved for upstream [231] -> unknown paired-scratch restore mode refused [232] - -> 6cb6ba87c (NVX pin) + -> clone's activation record carried in the restore packet [233] + -> d501e5066 (NVX pin) ``` For upstream review, PR01-PR06 and PR14 can be rebased independently onto current upstream main, @@ -1002,13 +1004,13 @@ reorganization folded the PR20 and PR12 fixups into the commits that they fix; s ## Commits after the mapped tip -The NVX pin extends the chain past position 131 without merges. None of the 101 later commits is a +The NVX pin extends the chain past position 131 without merges. None of the 102 later commits is a fixup of a mapped PR, and none is yet classified or assigned to PRs. Each of positions 132-186 combines the v2.4 commits that the table lists, as v3.0 positions 145-160 and 162-200 did, which developed one concept; "(part)" marks a v2.4 fixup that split across commits. Positions 187-191 followed the v3.0 reorganization, positions 192-205 are the ABI restart of the v4.0 reorganization, positions 206-211 followed it, positions 212-218 followed the v5.0 -reorganization, positions 219 and 220 followed the v5.1 rebase, and positions 221-232 followed the +reorganization, positions 219 and 220 followed the v5.1 rebase, and positions 221-233 followed the v6.0 reorganization, so they combine none, apart from position 220, which combines v5.1 positions 222 and 223. Each commit has the position that it had in v5.1 through position 147, and one less from v5.1 position 149 on; see @@ -1118,6 +1120,7 @@ at `e1ca353eb`, whose first 210 commits are those of `feature/microvm/release/v4 | 230 | `8a994544a` | - | - | - | - | openvmm_helpers: refuse earlier snapshot formats before decoding them (microsoft/openvmm#4994) | | 231 | `98e5b3ca5` | - | - | - | - | openvmm_helpers: reserve the manifest fields that upstream assigns (microsoft/openvmm#4994) | | 232 | `6cb6ba87c` | - | - | - | - | openvmm_helpers: refuse an unknown paired-scratch restore mode (microsoft/openvmm#4995) | +| 233 | `d501e5066` | - | - | - | - | microvm: carry a clone's activation record in the restore packet (microsoft/openvmm#4996) | The remarks that say whether commits apply to upstream main record what the v3.0 reorganization found on its base, `b2676222b`, at the positions that the commits have now. @@ -1222,7 +1225,14 @@ fields 18-20 for upstream's SaveVM and RestoreVM, microsoft/openvmm#4553. Positi restore-mode match that position 166 adds to the capture-tier check of PR19's position 093: restore runs that check before the machine contract's shape check, so the match now refuses a mode that it does not know with the shape check's error, where it panicked on the assumption that the -shape check had refused the mode. +shape check had refused the mode. Position 233 lets a platform restore end the restore packet with +its clone's activation record: it defines bit 5 of the packet's flags, which position 193 reserved +when it restarted the packet at version 1, beside the network settings of position 181; adds +`--restore-activation-record`, which the restore preparation of PR17's position 079 reads before +any vCPU runs, only for the platform tier of PR19's position 093, and with the post-restore gate of +PR20's position 095; adds the field that the management RPC's conversion of position 228 turns into +that option, in the protocol that PR25's position 124 extends; and adds a test of the restore +packet that the portb device of PR15's position 060 serves since position 137. Assigning the later commits therefore means revisiting those PRs, not only appending new ones. Position 177, by contrast, changes only `disk_blob`, which upstream main and the fork base @@ -1429,6 +1439,17 @@ claim of position 093. Replaying it on upstream main conflicts in both of its fi lacks the microVM snapshot module of position 074 and the tiers and paired scratch that positions 092, 093, and 166 add to the restore, so it follows PR17 and PR19 upstream. +Position 233 changes the restore packet of the time ABI series in `chipset_resources`, which +position 132 adds and positions 160, 181, and 193 change, and adds a test to the portb device that +serves it, which PR15's positions 060 and 061, PR17's position 071, PR19's position 092, PR20's +positions 094, 095, 097, and 099, PR24's position 119, and positions 137, 139, 147, 160, 181, 193, +195, 208, and 226 also change. It changes the microVM CLI of PR15's position 064, the restore +preparation of PR17's position 079, the management RPC's microVM conversion of position 228 and +the protocol of PR25's position 124, and their Guide pages. Replaying it on upstream main +conflicts in all nine of its files: upstream main lacks the time ABI series, the microVM CLI and +restore of PR15 and PR17, and the conversion of position 228, so it follows that series, PR15, +PR17, PR19, PR20, and PR25 upstream. + ## PR summary Each count is of v6.0 commits, which include the fixups that the v3.0, v4.0, v5.0, and v6.0 diff --git a/nvx-rs/README.md b/nvx-rs/README.md index 5afe4d844..4cce113fd 100644 --- a/nvx-rs/README.md +++ b/nvx-rs/README.md @@ -2862,10 +2862,12 @@ NVX_BUNDLE=skip cargo test --locked --all-features --lib -- \ `tests/openvmm_vectors.rs` is an ignored test that compares the copies of OpenVMM's vectors in `tests/vectors/openvmm/` with the files of the OpenVMM -submodule, which the `nvx-rs` job cannot check out, and the versions of +submodule, which the `nvx-rs` job cannot check out, the versions of OpenVMM's snapshot format, saved-state schema, time ABI, and restore packets in -`nvx::contract` with the submodule's. The NVX CLI jobs run it once they check -the submodule out, and so does an OpenVMM pin promotion; see +`nvx::contract` with the submodule's, and the bound of an activation record, +`nvx::activation::MAX_RECORD_BYTES`, with that of the restore packet's. The NVX +CLI jobs run it once they check the submodule out, and so does an OpenVMM pin +promotion; see [OpenVMM's vectors](tests/vectors/README.md#openvmms-vectors). `tests/openvmm_cpu_profiles.rs` is an ignored test that compares `src/host/cli/cpu_generations.json`, the identities of the built-in CPU diff --git a/nvx-rs/public-api/linux.txt b/nvx-rs/public-api/linux.txt index 0ed170a5e..af619d838 100644 --- a/nvx-rs/public-api/linux.txt +++ b/nvx-rs/public-api/linux.txt @@ -1600,6 +1600,7 @@ method nvx::guest::time::MemoryRange::length method nvx::guest::time::MemoryRange::start struct nvx::guest::time::Restore method nvx::guest::time::Restore::acknowledgement_required +method nvx::guest::time::Restore::activation_record method nvx::guest::time::Restore::finished method nvx::guest::time::Restore::generation_id method nvx::guest::time::Restore::memory_ranges diff --git a/nvx-rs/src/contract.rs b/nvx-rs/src/contract.rs index 1f95e9560..52fe8d284 100644 --- a/nvx-rs/src/contract.rs +++ b/nvx-rs/src/contract.rs @@ -89,7 +89,11 @@ pub const TIME_ABI_VERSION: u64 = 1; /// /// Version 1 carries no host UTC: the guest takes a time sample to set its clock. A restore that /// replaces the network policy of a snapshot without a tier flags the packet's network: the new -/// policy's DNS server, and whether the guest announces its listeners under it. +/// policy's DNS server, and whether the guest announces its listeners under it. A platform +/// restore may flag an activation record, which then ends the packet: the settings of the clone's +/// own launch, which its launcher supplied. The flag was a reserved bit, which a guest that +/// predates it refuses, so a packet that sets it fails on such a guest, and a packet that does not +/// keeps the version's layout and meaning. pub const RESTORE_PACKET_VERSION: u64 = 1; /// Returns how the `openvmm` section of an NVX `SOURCE-MANIFEST.json` departs from the contracts diff --git a/nvx-rs/src/guest/time/api.rs b/nvx-rs/src/guest/time/api.rs index ced0a0263..976c33763 100644 --- a/nvx-rs/src/guest/time/api.rs +++ b/nvx-rs/src/guest/time/api.rs @@ -583,6 +583,8 @@ pub struct Restore { memory_ranges: Vec, /// The network settings that the restore packet carries, if any. network: Option, + /// The activation record that the restore packet ends with, if any, undecoded. + activation: Option>, /// Whether the call finished the restore. finished: bool, /// The restore's fresh entropy, in the in-memory mode, until the caller takes it. @@ -657,6 +659,15 @@ impl Restore { pub fn network(&self) -> Option { self.network } + + /// Returns the activation record that the restore packet ends with: the bytes, 1 to + /// [`MAX_RECORD_BYTES`](crate::activation::MAX_RECORD_BYTES) of them, that the host handed a + /// platform clone with its restore, which the time ABI does not decode, or `None` for a + /// restore that handed over none. A clone decodes them with + /// [`ActivationRecord::decode`](crate::activation::ActivationRecord::decode). + pub fn activation_record(&self) -> Option<&[u8]> { + self.activation.as_deref() + } } /// The network settings of a restore that replaced the network policy of a snapshot without a @@ -869,7 +880,13 @@ fn read_packet(runtime: &Runtime<'_>, ports: &PortAccess<'_>, recorded: u32) -> } let mut body = vec![0_u8; header.body_size()]; portb_read(ports, Port::PortbData, &mut body); - let packet = RestorePacket::parse(header, &body); + // The activation record follows the body, which ends with its length, a multiple of four + // bytes after the header, so its reads start on a four-byte boundary of the packet. + let packet = RestorePacket::parse(header, &body, |size| { + let mut record = vec![0_u8; size]; + portb_read(ports, Port::PortbData, &mut record); + record + }); // The packet owns its entropy now, in the seed's allocation. sys::zeroize(&mut body); PacketRead::Packet(packet.map(|packet| { @@ -940,6 +957,7 @@ fn repair_restore( ranges, entropy, network, + activation, } = packet; let generation_id = entropy.generation_id(); if generation_id == target.previous_id { @@ -1022,6 +1040,7 @@ fn repair_restore( .map(|&(start, length)| MemoryRange { start, length }) .collect(), network, + activation, finished, seed, })) diff --git a/nvx-rs/src/guest/time/api/tests.rs b/nvx-rs/src/guest/time/api/tests.rs index e606320aa..772f2981f 100644 --- a/nvx-rs/src/guest/time/api/tests.rs +++ b/nvx-rs/src/guest/time/api/tests.rs @@ -22,6 +22,7 @@ impl Restore { generation_id, memory_ranges: Vec::new(), network: None, + activation: None, finished: false, seed: None, } @@ -39,6 +40,13 @@ impl Restore { self } + /// Returns the restore whose packet ends with the activation record `record`. + pub(crate) fn with_activation_record(mut self, record: &[u8]) -> Self { + self.flags |= decoders::PACKET_ACTIVATION; + self.activation = Some(record.to_vec()); + self + } + /// Returns the restore that asks for `count` online processors. pub(crate) fn with_processor_target(mut self, count: u8) -> Self { self.online_vp_count = count; @@ -388,6 +396,7 @@ fn requests_and_restores_carry_the_abi_values() { generation_id: GenerationId::from_bytes([7; GenerationId::LENGTH]), memory_ranges: vec![range], network: None, + activation: None, finished: false, seed: None, }; @@ -420,6 +429,10 @@ fn requests_and_restores_carry_the_abi_values() { assert!(!plain.acknowledgement_required() && !plain.memory_target()); assert!(plain.finished()); assert_eq!(plain.processor_target(), None); + assert_eq!(plain.activation_record(), None); + let activated = plain.with_activation_record(&[0xa1, 0xa2, 0xa3]); + assert_eq!(activated.activation_record(), Some(&[0xa1, 0xa2, 0xa3][..])); + assert_eq!(activated.flags(), decoders::PACKET_ACTIVATION); } #[test] @@ -479,6 +492,7 @@ fn a_restore_hands_over_its_seed_once_and_formats_none_of_it() { generation_id: seed.generation_id(), memory_ranges: Vec::new(), network: None, + activation: None, finished: false, seed: Some(seed), }; @@ -522,10 +536,27 @@ fn the_file_mode_writes_the_entropy_and_the_in_memory_mode_returns_it() { /// reads, and then port B's status, with the time window, and a time sample of the /// generation, within the bound. fn restore_input(generation: u32, entropy: &[u8; Seed::LENGTH]) -> Vec { - let mut packet = [0_u8; PACKET_HEADER_SIZE + Seed::LENGTH + PACKET_DNS_SIZE]; + restore_input_with(generation, entropy, None) +} + +/// Returns the port input of [`restore_input`], whose packet ends with the activation record +/// `record`, if any. +fn restore_input_with( + generation: u32, + entropy: &[u8; Seed::LENGTH], + record: Option<&[u8]>, +) -> Vec { + let mut packet = vec![0_u8; PACKET_HEADER_SIZE + Seed::LENGTH + PACKET_DNS_SIZE]; packet[..4].copy_from_slice(b"OVR\x01"); packet[8..12].copy_from_slice(&generation.to_le_bytes()); packet[PACKET_HEADER_SIZE..][..Seed::LENGTH].copy_from_slice(entropy); + if let Some(record) = record { + packet[4] |= decoders::PACKET_ACTIVATION; + packet.extend_from_slice(&u32::try_from(record.len()).unwrap().to_le_bytes()); + packet.extend_from_slice(record); + // The device's last read of the packet returns bytes past it, which the guest ignores. + packet.resize(packet.len().next_multiple_of(size_of::()), 0xee); + } let words = packet .chunks(size_of::()) .map(|word| u32::from_ne_bytes(word.try_into().unwrap())); @@ -543,6 +574,28 @@ fn restore_input(generation: u32, entropy: &[u8; Seed::LENGTH]) -> Vec { .collect() } +#[test] +fn a_packet_read_takes_its_activation_record_before_the_time_sample() { + let entropy: [u8; Seed::LENGTH] = std::array::from_fn(|index| index as u8 + 2); + // Records whose last read is whole, and partial. + for record in [&[0xa1, 0xa2, 0xa3, 0xa4][..], &[0xb1; 7][..]] { + // Without port B's status, which the capture reads before the packet. + let input = restore_input_with(1, &entropy, Some(record))[1..].to_vec(); + let ops = FakeOps::new(input); + let runtime = Runtime::new(&ops, true); + let ports = runtime.open_ports().unwrap(); + let read = read_packet(&runtime, &ports, 0); + ports.release().unwrap(); + // The time sample after the record decodes only if the packet's reads took the record + // whole, and nothing past it. + let PacketRead::Packet(Ok((packet, Ok(_)))) = read else { + panic!("the packet with a record of {} bytes failed", record.len()); + }; + assert_eq!(packet.activation.as_deref(), Some(record)); + assert!(ops.input.lock().unwrap().is_empty()); + } +} + /// Returns whether a file below `directory` holds `secret`, as bytes or in hexadecimal. fn holds(directory: &Path, secret: &[u8]) -> bool { let hex = decoders::format_hex(secret); diff --git a/nvx-rs/src/guest/time/decoders.rs b/nvx-rs/src/guest/time/decoders.rs index 232be34e8..a3e157782 100644 --- a/nvx-rs/src/guest/time/decoders.rs +++ b/nvx-rs/src/guest/time/decoders.rs @@ -64,8 +64,18 @@ pub(crate) const PACKET_ACK_REQUIRED: u8 = 0x04; /// at a restore that replaces the network policy of a snapshot without a tier. Without it, both /// are zero. pub(crate) const PACKET_NETWORK: u8 = 0x10; +/// Restore flag indicating that the packet ends with a platform clone's activation record: its +/// length, then its bytes. +pub(crate) const PACKET_ACTIVATION: u8 = 0x20; /// Mask of restore flags defined by the ABI. -const PACKET_KNOWN_FLAGS: u8 = 0x1f; +const PACKET_KNOWN_FLAGS: u8 = 0x3f; +/// Encoded length of the activation record's length, a little-endian `u32`, which follows the DNS +/// server in a packet with an [activation record](PACKET_ACTIVATION), and keeps the record's bytes +/// aligned to the guest's four-byte reads. +pub(crate) const PACKET_ACTIVATION_LENGTH_SIZE: usize = 4; +/// The most bytes of a packet's activation record: as many as a record's encoding holds, +/// [`MAX_RECORD_BYTES`](crate::activation::MAX_RECORD_BYTES). +pub(crate) const PACKET_ACTIVATION_MAX: usize = crate::activation::MAX_RECORD_BYTES; /// The online VP counts that a restore packet may give. const PACKET_ONLINE_VP_COUNTS: [u8; 5] = [0, 1, 2, 4, 8]; /// The time-sample version. @@ -198,6 +208,9 @@ pub(crate) enum PacketError { /// not zero when the network byte names no DNS server or the packet carries no network /// settings. DnsServer, + /// The length of the packet's activation record is 0, or more than + /// [`PACKET_ACTIVATION_MAX`]. + ActivationLength(u32), } impl Display for PacketError { @@ -241,6 +254,11 @@ impl Display for PacketError { Self::IncompleteBody => formatter.write_str("restore packet body is incomplete"), Self::Range(index) => write!(formatter, "restore memory range {index} is invalid"), Self::DnsServer => formatter.write_str("restore packet DNS server is invalid"), + Self::ActivationLength(length) => write!( + formatter, + "restore packet activation record length {length} is not 1 to \ + {PACKET_ACTIVATION_MAX}" + ), } } } @@ -319,9 +337,24 @@ impl PacketHeader { Ok(header) } - /// Returns the length of the body that follows the header. + /// Returns the length of the body that follows the header: the memory ranges, the entropy, + /// the DNS server, and the length of the packet's activation record, if it has one, whose + /// bytes follow the body. pub(crate) fn body_size(&self) -> usize { - usize::from(self.range_count) * PACKET_RANGE_SIZE + PACKET_ENTROPY_SIZE + PACKET_DNS_SIZE + let activation = if self.activation() { + PACKET_ACTIVATION_LENGTH_SIZE + } else { + 0 + }; + usize::from(self.range_count) * PACKET_RANGE_SIZE + + PACKET_ENTROPY_SIZE + + PACKET_DNS_SIZE + + activation + } + + /// Returns whether the packet ends with a platform clone's activation record. + pub(crate) const fn activation(&self) -> bool { + self.flags & PACKET_ACTIVATION != 0 } /// Returns whether the packet asks the guest to apply network settings: a DNS server, or the @@ -361,12 +394,19 @@ pub(crate) struct RestorePacket { pub(crate) entropy: Seed, /// The network settings of a packet that carries them. pub(crate) network: Option, + /// The activation record that the packet ends with, if any: its bytes, undecoded. + pub(crate) activation: Option>, } impl RestorePacket { /// Decodes and validates the memory ranges, the entropy, and the DNS server that follow - /// `header` in `body`. - pub(crate) fn parse(header: PacketHeader, body: &[u8]) -> Result { + /// `header` in `body`, and, for a packet with an activation record, the record's length, + /// with which `read_record` reads the record's bytes, which follow the body. + pub(crate) fn parse( + header: PacketHeader, + body: &[u8], + read_record: impl FnOnce(usize) -> Vec, + ) -> Result { let mut fields = Fields::new(body, PacketError::IncompleteBody); let ranges = (0..usize::from(header.range_count)) .map(|index| { @@ -387,11 +427,22 @@ impl RestorePacket { None if dns_server == [0; PACKET_DNS_SIZE] => None, None => return Err(PacketError::DnsServer), }; + let activation = if header.activation() { + let length = fields.u32()?; + let size = usize::try_from(length) + .ok() + .filter(|size| (1..=PACKET_ACTIVATION_MAX).contains(size)) + .ok_or(PacketError::ActivationLength(length))?; + Some(read_record(size)) + } else { + None + }; Ok(Self { header, ranges, entropy: Seed::copy_from(entropy), network, + activation, }) } diff --git a/nvx-rs/src/guest/time/decoders/tests.rs b/nvx-rs/src/guest/time/decoders/tests.rs index 30961e13a..a20a2e28d 100644 --- a/nvx-rs/src/guest/time/decoders/tests.rs +++ b/nvx-rs/src/guest/time/decoders/tests.rs @@ -17,6 +17,11 @@ fn plain_body(entropy: &[u8]) -> Vec { [entropy, &[0; PACKET_DNS_SIZE]].concat() } +/// Reads the activation record of a packet that has none. +fn unread(_: usize) -> Vec { + unreachable!("the packet has no activation record") +} + #[test] fn packets_decode_their_header_then_their_body() { let header = PacketHeader::parse(&valid_header()).unwrap(); @@ -24,11 +29,11 @@ fn packets_decode_their_header_then_their_body() { assert_eq!(header.body_size(), PACKET_ENTROPY_SIZE + PACKET_DNS_SIZE); let entropy: Vec = (0..64).collect(); let body = plain_body(&entropy); - let packet = RestorePacket::parse(header, &body).unwrap(); + let packet = RestorePacket::parse(header, &body, unread).unwrap(); assert_eq!(packet.entropy.bytes().as_slice(), entropy); assert_eq!(packet.generation_id(), &entropy[..GENERATION_ID_SIZE]); assert_eq!( - RestorePacket::parse(header, &body[1..]).unwrap_err(), + RestorePacket::parse(header, &body[1..], unread).unwrap_err(), PacketError::IncompleteBody ); assert_eq!( @@ -54,7 +59,7 @@ fn packet_errors_name_the_invalid_field() { let mut body = [0; PACKET_RANGE_SIZE + PACKET_ENTROPY_SIZE + PACKET_DNS_SIZE]; body[..8].copy_from_slice(&u64::MAX.to_le_bytes()); body[8..16].copy_from_slice(&1_u64.to_le_bytes()); - let error = RestorePacket::parse(header, &body).unwrap_err(); + let error = RestorePacket::parse(header, &body, unread).unwrap_err(); assert_eq!(error.to_string(), "restore memory range 0 is invalid"); } @@ -105,11 +110,11 @@ fn network_packets_carry_their_network_settings() { assert_eq!(header.network_repair(), network != 0); assert_eq!(header.body_size(), PACKET_ENTROPY_SIZE + PACKET_DNS_SIZE); let body = [entropy.as_slice(), &dns_server].concat(); - let packet = RestorePacket::parse(header, &body).unwrap(); + let packet = RestorePacket::parse(header, &body, unread).unwrap(); assert_eq!(packet.entropy.bytes().as_slice(), entropy); assert_eq!(packet.network, Some(expected), "{network:#04x}"); assert_eq!( - RestorePacket::parse(header, &body[1..]).unwrap_err(), + RestorePacket::parse(header, &body[1..], unread).unwrap_err(), PacketError::IncompleteBody ); } @@ -119,7 +124,7 @@ fn network_packets_carry_their_network_settings() { let header = PacketHeader::parse(&valid_header()).unwrap(); assert_eq!(header.network, None); assert!(!header.network_repair()); - let packet = RestorePacket::parse(header, &plain_body(&entropy)).unwrap(); + let packet = RestorePacket::parse(header, &plain_body(&entropy), unread).unwrap(); assert_eq!(packet.network, None); } @@ -151,7 +156,7 @@ fn packets_refuse_malformed_network_settings() { let mut body = plain_body(&[0; PACKET_ENTROPY_SIZE]); body[PACKET_ENTROPY_SIZE] = 10; assert_eq!( - RestorePacket::parse(header, &body).unwrap_err(), + RestorePacket::parse(header, &body, unread).unwrap_err(), PacketError::DnsServer ); @@ -169,12 +174,84 @@ fn packets_refuse_malformed_network_settings() { ] { let header = PacketHeader::parse(&network_header(network)).unwrap(); let body = [&[0; PACKET_ENTROPY_SIZE][..], &dns_server].concat(); - let error = RestorePacket::parse(header, &body).unwrap_err(); + let error = RestorePacket::parse(header, &body, unread).unwrap_err(); assert_eq!(error, PacketError::DnsServer, "{network:#04x}"); assert_eq!(error.to_string(), "restore packet DNS server is invalid"); } } +/// Returns a valid packet header with an activation record, without memory ranges, of +/// generation 1. +fn activation_header() -> [u8; PACKET_HEADER_SIZE] { + let mut bytes = valid_header(); + bytes[4] = PACKET_ACTIVATION | PACKET_ACK_REQUIRED; + bytes +} + +#[test] +fn packets_end_with_their_activation_record() { + let header = PacketHeader::parse(&activation_header()).unwrap(); + assert!(header.activation() && header.acknowledgement_required()); + // The body ends with the record's length, so the record starts on a four-byte boundary. + assert_eq!( + header.body_size(), + PACKET_ENTROPY_SIZE + PACKET_DNS_SIZE + PACKET_ACTIVATION_LENGTH_SIZE + ); + assert_eq!((PACKET_HEADER_SIZE + header.body_size()) % 4, 0); + let entropy: Vec = (0..64).collect(); + for length in [1, 3, 602, PACKET_ACTIVATION_MAX] { + let record: Vec = (0..length).map(|index| index as u8 ^ 0x5a).collect(); + let body = [plain_body(&entropy), (length as u32).to_le_bytes().to_vec()].concat(); + let mut requested = None; + let packet = RestorePacket::parse(header, &body, |size| { + requested = Some(size); + record.clone() + }) + .unwrap(); + assert_eq!(requested, Some(length)); + assert_eq!(packet.activation.as_deref(), Some(record.as_slice())); + assert_eq!(packet.entropy.bytes().as_slice(), entropy); + } + // A packet without the flag has none, and reads none. + let header = PacketHeader::parse(&valid_header()).unwrap(); + assert!(!header.activation()); + let packet = RestorePacket::parse(header, &plain_body(&entropy), unread).unwrap(); + assert_eq!(packet.activation, None); +} + +#[test] +fn packets_refuse_activation_records_beyond_the_bounds() { + let header = PacketHeader::parse(&activation_header()).unwrap(); + for length in [0, PACKET_ACTIVATION_MAX as u32 + 1, u32::MAX] { + let body = [ + plain_body(&[0; PACKET_ENTROPY_SIZE]), + length.to_le_bytes().to_vec(), + ] + .concat(); + let error = RestorePacket::parse(header, &body, unread).unwrap_err(); + assert_eq!(error, PacketError::ActivationLength(length)); + assert_eq!( + error.to_string(), + format!("restore packet activation record length {length} is not 1 to 1024") + ); + } + // A body that ends within the record's length. + let body = plain_body(&[0; PACKET_ENTROPY_SIZE]); + assert_eq!( + RestorePacket::parse(header, &[body.as_slice(), &[1, 0]].concat(), unread).unwrap_err(), + PacketError::IncompleteBody + ); + // The bits after the activation flag, which no version defines. + for flags in [0x40, 0x80] { + let mut bytes = valid_header(); + bytes[4] = flags; + assert_eq!( + PacketHeader::parse(&bytes), + Err(PacketError::ReservedFlags(flags)) + ); + } +} + #[test] fn samples_decode_every_field() { assert_eq!( diff --git a/nvx-rs/src/guest/time/test_mode.rs b/nvx-rs/src/guest/time/test_mode.rs index 7e096a52b..bfc324a52 100644 --- a/nvx-rs/src/guest/time/test_mode.rs +++ b/nvx-rs/src/guest/time/test_mode.rs @@ -151,13 +151,15 @@ fn test_packet(arguments: &[&[u8]], out: &mut dyn Write) -> Result<(), CommandEr return Ok(()); } let body = record(&bytes, PACKET_HEADER_SIZE, header.body_size()); - let packet = match RestorePacket::parse(header, &body) { - Ok(packet) => packet, - Err(error) => { - let _ = writeln!(out, "error {} {error}", ViolationCode::RepairPacket); - return Ok(()); - } - }; + let record_offset = PACKET_HEADER_SIZE + header.body_size(); + let packet = + match RestorePacket::parse(header, &body, |size| record(&bytes, record_offset, size)) { + Ok(packet) => packet, + Err(error) => { + let _ = writeln!(out, "error {} {error}", ViolationCode::RepairPacket); + return Ok(()); + } + }; if packet.generation_id() == previous { let _ = writeln!( out, @@ -191,6 +193,9 @@ fn test_packet(arguments: &[&[u8]], out: &mut dyn Write) -> Result<(), CommandEr u8::from(network.announces_listeners()) ); } + if let Some(activation) = &packet.activation { + let _ = write!(out, " activation={}", decoders::format_hex(activation)); + } let _ = writeln!(out); Ok(()) } diff --git a/nvx-rs/tests/guest_tools.rs b/nvx-rs/tests/guest_tools.rs index 1b4a02467..f57ff7ad6 100644 --- a/nvx-rs/tests/guest_tools.rs +++ b/nvx-rs/tests/guest_tools.rs @@ -1989,6 +1989,64 @@ fn time_test_mode_decodes_the_network_settings() { } } +/// Returns `packet`, a packet of [`time_packet`] without an activation record, as one that ends +/// with `record`: with the activation flag, and, after its DNS server, the record's length +/// `length`, a little-endian `u32`, and the record. +#[cfg(target_arch = "x86_64")] +fn time_activation_packet(mut packet: Vec, length: u32, record: &[u8]) -> Vec { + packet[4] |= 0x20; + packet.extend_from_slice(&length.to_le_bytes()); + packet.extend_from_slice(record); + packet +} + +#[test] +#[cfg(target_arch = "x86_64")] +fn time_test_mode_decodes_the_activation_record() { + let directory = tempfile::tempdir().unwrap(); + let previous = "ffffffffffffffffffffffffffffffff"; + let base = time_packet(0x04, 0, &[], 1, 0, 0); + for (index, record) in [vec![0xa1, 0xa2, 0xa3], vec![0x5a; 1024]] + .into_iter() + .enumerate() + { + let packet = time_activation_packet(base.clone(), record.len() as u32, &record); + let output = run_time_packet( + directory.path(), + &format!("activation-{index}"), + &packet, + "0", + previous, + ); + let text = String::from_utf8_lossy(&output.1); + assert_eq!(output.0, Some(0), "case {index}: {text:?}"); + let hex: String = record.iter().map(|byte| format!("{byte:02x}")).collect(); + assert!( + text.starts_with("ok flags=36 ") && text.ends_with(&format!(" activation={hex}\n")), + "case {index}: {text:?}" + ); + } + for (index, length) in [0, 1025, u32::MAX].into_iter().enumerate() { + let packet = time_activation_packet(base.clone(), length, &[0x5a; 1025]); + let output = run_time_packet( + directory.path(), + &format!("activation-rejected-{index}"), + &packet, + "0", + previous, + ); + assert_eq!(output.0, Some(0)); + assert_eq!( + String::from_utf8_lossy(&output.1), + format!( + "error G_REPAIR_PACKET restore packet activation record length {length} is not \ + 1 to 1024\n" + ), + "case {index}" + ); + } +} + #[test] #[cfg(target_arch = "x86_64")] fn time_test_mode_covers_checks_events_records_and_workers() { diff --git a/nvx-rs/tests/openvmm_vectors.rs b/nvx-rs/tests/openvmm_vectors.rs index ee254c512..af1cf01a7 100644 --- a/nvx-rs/tests/openvmm_vectors.rs +++ b/nvx-rs/tests/openvmm_vectors.rs @@ -1,6 +1,7 @@ //! Compares what `nvx-rs` copies from OpenVMM with the OpenVMM submodule: the control-session -//! protocol vectors and the excerpts of OpenVMM's sources in `tests/vectors/openvmm/`, and the -//! versions of OpenVMM's contracts in `nvx::contract`. +//! protocol vectors and the excerpts of OpenVMM's sources in `tests/vectors/openvmm/`, the +//! versions of OpenVMM's contracts in `nvx::contract`, and the bound of an activation record, +//! which a restore packet carries. //! //! The protocol's tests read the copies, and the unit tests of `nvx::host::template` compile or //! read the excerpts, because the `nvx-rs` job cannot check out the submodule, whose deploy key @@ -10,7 +11,7 @@ use std::fs; use std::path::Path; -use nvx::contract; +use nvx::{activation, contract}; /// The files of OpenVMM's `vm/devices/virtio/virtio_console/test_data/` that /// `tests/vectors/openvmm/` copies. @@ -58,6 +59,14 @@ const VERSIONS: [(&str, &str, u64); 4] = [ ), ]; +/// The bound of an activation record, [`activation::MAX_RECORD_BYTES`], which OpenVMM's restore +/// packet shares: the file of the OpenVMM submodule that defines OpenVMM's, and the start of the +/// line that defines it, up to its value. +const ACTIVATION_BOUND: (&str, &str) = ( + "vm/devices/chipset_resources/src/microvm_time.rs", + "pub const MAX_RESTORE_ACTIVATION_LEN: usize = ", +); + #[test] #[ignore = "needs the OpenVMM submodule, which the NVX CLI jobs check out"] fn the_copies_match_the_submodules_files() { @@ -139,3 +148,28 @@ fn the_contract_versions_are_the_submodules() { ); } } + +#[test] +#[ignore = "needs the OpenVMM submodule, which the NVX CLI jobs check out"] +fn the_activation_bound_is_the_submodules() { + let (file, definition) = ACTIVATION_BOUND; + let openvmm = Path::new(env!("CARGO_MANIFEST_DIR")).join("../openvmm"); + let source = fs::read_to_string(openvmm.join(file)).unwrap_or_else(|error| { + panic!( + "cannot read {file} of the OpenVMM submodule, which `scripts/nvx.py init` checks out: \ + {error}" + ) + }); + let values: Vec<&str> = source + .lines() + .filter_map(|line| line.trim().strip_prefix(definition)?.strip_suffix(';')) + .collect(); + assert_eq!( + values, + [activation::MAX_RECORD_BYTES.to_string()], + "{file} of the OpenVMM submodule does not define `{definition}{};` once: change \ + nvx::activation::MAX_RECORD_BYTES with OpenVMM's bound of a restore packet's activation \ + record, and the guest's decoder of the restore packet", + activation::MAX_RECORD_BYTES + ); +} diff --git a/nvx-rs/tests/vectors/README.md b/nvx-rs/tests/vectors/README.md index 8bc07a854..98d1ca8c2 100644 --- a/nvx-rs/tests/vectors/README.md +++ b/nvx-rs/tests/vectors/README.md @@ -107,8 +107,10 @@ read the copies instead, and the ignored test `tests/openvmm_vectors.rs` compares the copies with the submodule's files, and finds each excerpt among the lines of its file. It also checks that the versions of OpenVMM's snapshot format, saved-state schema, time ABI, and restore packets in `nvx::contract` are -the submodule's. The NVX CLI jobs, which check out the submodule, run it, and -so does an OpenVMM pin promotion, from the repository's root: +the submodule's, and that the bound of an activation record, +`nvx::activation::MAX_RECORD_BYTES`, is that of the submodule's restore packet. +The NVX CLI jobs, which check out the submodule, run it, and so does an OpenVMM +pin promotion, from the repository's root: ```bash cargo test --locked --manifest-path nvx-rs/Cargo.toml --no-default-features \ diff --git a/openvmm b/openvmm index 6cb6ba87c..d501e5066 160000 --- a/openvmm +++ b/openvmm @@ -1 +1 @@ -Subproject commit 6cb6ba87cfb6707078d19f09ec81d9a78fcd1ede +Subproject commit d501e50660136000ec93412aea78fdafb9cf391c