Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions Guide/src/user_guide/openvmm/snapshots.md
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,14 @@ fails (`E_PROFILE_HOST_UNKNOWN`). A host profile,
`intel.host.v1` or `amd.host.v1`, serves only the host's CPU model and
stepping, is not pinned, can change with the host's microcode, firmware,
or hypervisor, and costs a fingerprint of the backend at every cold boot.
Every profile, pinned or host, fixes the CPU time bits that the time ABI
requires: the hypervisor, TSC, RDTSCP, ARAT, and invariant-TSC bits set, and
no TSC-deadline timer, `IA32_TSC_ADJUST`, PDCM, performance monitoring leaf
`0xa`, or rate leaves `0x15` and `0x16`; OpenVMM refuses a profile that
violates them (`E_PROFILE_DIGEST`). Before a partition uses a pinned profile,
OpenVMM verifies the profile's built-in data, once per process: a valid
profile, CPU time bits included, whose built-in encoding, which snapshots
embed, is its canonical encoding (`E_PROFILE_DIGEST`).
Every boot checks that the backend
supports the profile (`E_PROFILE_UNSUPPORTED`) and that VP 0 observes its
effective CPUID (`E_CPU_SURFACE`); where `auto` fell back, such a failure
Expand All @@ -349,8 +357,8 @@ generation, because a host profile derives from what the backend supports.
A snapshot records the profile and the
effective CPUID. Restore requires the same profile, pinned in this OpenVMM with
the same digest, or, for a host profile, the snapshot's own copy of it, which
must match the recorded digest; a host of the profile's generation; and an
identical effective CPUID.
must be a valid profile, its CPU time bits included, with the recorded digest;
a host of the profile's generation; and an identical effective CPUID.
OpenVMM computes the effective CPUID, including its own leaves and the bits
it owns, such as the cache topology, so an OpenVMM build that computes it
differently rejects earlier snapshots with `E_CPU_SURFACE`.
Expand Down
255 changes: 209 additions & 46 deletions vmm_core/cpu_profile/src/catalog.rs

Large diffs are not rendered by default.

44 changes: 28 additions & 16 deletions vmm_core/cpu_profile/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -29,23 +29,35 @@
//! a pass-through backend (MSHV, WHP) must present zero there
//! ([`check_unlisted_cpuid`]), and KVM answers those entries from the
//! effective CPUID itself ([`CpuidPresentation`]).
//! - **Restore:** [`pinned_for_restore`] checks a snapshot's recorded profile
//! digest against the pinned constant, core compares the recorded document
//! with [`pinned_record`]'s encoding, and [`check_generation`] checks the
//! destination host. Core compares the effective CPUID record with the
//! recomputed [`EffectiveCpuid`]. A snapshot of a host profile carries the
//! only copy of its document, which [`host_profile_for_restore`] decodes
//! and checks against the recorded digest, and from which the restoring
//! VM worker's [`PartitionProfile`] takes it.
//! - **Restore:** [`pinned_for_restore`] verifies the snapshot's pinned
//! profile and checks its recorded digest against the pinned constant,
//! core compares the recorded document with [`pinned_record`]'s encoding,
//! and [`check_generation`] checks the destination host. Core compares the
//! effective CPUID record with the recomputed [`EffectiveCpuid`]. A
//! snapshot of a host profile carries the only copy of its document, which
//! [`host_profile_for_restore`] decodes and checks against the recorded
//! digest, and from which the restoring VM worker's [`PartitionProfile`]
//! takes it.
//! - **Pinned profile verification:** the first use of a pinned profile in a
//! process, by [`select`], [`pinned_for_restore`], [`pinned`], or
//! [`PartitionProfile::pinned`], verifies its static data before handing it
//! out: the profile is valid, CPU time bits included, and its constant
//! encoding, which snapshots embed, is its canonical encoding
//! (`E_PROFILE_DIGEST`). A cold boot or restore therefore verifies the one
//! profile that it selects, once per process, for which it encodes the
//! profile; [`select_auto`] verifies only the revision that it selects. The
//! constant digest is the profile's identity, which the tests check against
//! the golden digests, so a pinned profile's start hashes nothing.
//! - **Offline only:** the codecs and digests
//! ([`CpuProfile::encode`], [`CpuProfile::digest`],
//! [`CpuProfile::digest_string`], [`CpuProfile::decode`],
//! [`CpuProfile::from_pretty_json`], [`CpuProfile::to_pretty_json`],
//! [`EffectiveCpuid::encode`], [`EffectiveCpuid::digest`],
//! [`EffectiveCpuid::decode`], and [`EffectiveCpuid::decode_verified`])
//! and [`pinned_profiles`] parse, encode, or hash. They serve tools, tests,
//! and `--cpu-fingerprint`, never a cold boot or restore of a pinned
//! profile, whose profile work uses only constants. Only a host profile,
//! ([`CpuProfile::digest`], [`CpuProfile::digest_string`],
//! [`CpuProfile::decode`], [`CpuProfile::from_pretty_json`],
//! [`CpuProfile::to_pretty_json`], [`EffectiveCpuid::encode`],
//! [`EffectiveCpuid::digest`], [`EffectiveCpuid::decode`], and
//! [`EffectiveCpuid::decode_verified`]) and [`pinned_profiles`] parse,
//! encode, or hash. They serve tools, tests, and `--cpu-fingerprint`, never
//! a cold boot or restore of a pinned profile, which parses no JSON, hashes
//! nothing, and compares its records with constants; only its verification
//! encodes it ([`CpuProfile::encode`]), once per process. A host profile,
//! which has no constants, encodes and hashes at cold boot and decodes at
//! restore.
//!
Expand Down
40 changes: 36 additions & 4 deletions vmm_core/cpu_profile/src/pinned.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,19 @@
//! `pinned_data.rs` holds every pinned profile as Rust constants: its values,
//! its canonical encoding, and its golden digest. The `generate_pinned`
//! example generates the file from `profiles/<id>.json`. An OpenVMM start
//! therefore neither parses JSON nor hashes: the first use of a profile
//! copies its constants into a [`CpuProfile`], and snapshot records use the
//! precomputed encoding and digest. The tests check every constant against
//! the JSON files and the golden digests.
//! therefore neither parses JSON nor hashes: the first use of a profile in a
//! process copies its constants into a [`CpuProfile`] and verifies the profile
//! and its encoding ([`PinnedProfile::verify`]), as a partition's CPU profile
//! must be verified before the partition uses it, and snapshot records use the
//! precomputed encoding and digest. The tests check every constant against the
//! JSON files and the golden digests.

use crate::Hex32;
use crate::Hex64;
use crate::cpuid::XsaveComponent;
use crate::derive::KnownGeneration;
use crate::error::ProfileError;
use crate::error::ProfileErrorCode;
use crate::profile::CpuProfile;
use crate::profile::CpuidLeafValue;
use crate::profile::PinnedMsr;
Expand Down Expand Up @@ -101,6 +105,34 @@ impl PinnedProfile {
digest: self.digest,
}
}

/// Verifies `profile`, the profile that [`Self::to_profile`] copies from
/// these constants, as a cold boot or restore must verify its CPU profile
/// before a partition uses it: the profile is valid, with its density,
/// ownership masks, and CPU time bits, and `encoding`, which snapshots
/// embed, is its canonical encoding.
///
/// A stale or malformed `pinned_data.rs` fails with `E_PROFILE_DIGEST`.
/// This encodes the profile but hashes nothing: `digest` is the profile's
/// identity, which the tests check against the golden digests, as they
/// check the static data against the reviewed JSON files.
pub(crate) fn verify(&self, profile: &CpuProfile) -> Result<(), ProfileError> {
let invalid = |message: String| {
ProfileError::new(
ProfileErrorCode::ProfileDigest,
format!("pinned CPU profile {} {message}", self.id),
)
};
profile
.validate()
.map_err(|message| invalid(format!("is invalid: {message}")))?;
if profile.encode() != self.encoding.as_bytes() {
return Err(invalid(
"differs from its constant canonical encoding".to_owned(),
));
}
Ok(())
}
}

/// The CPU profile record that a snapshot copies: the profile ID, the
Expand Down
157 changes: 153 additions & 4 deletions vmm_core/cpu_profile/src/profile.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@
//! Pinned profiles are stored as pretty canonical JSON. Decoding accepts only
//! the canonical bytes, so a profile has exactly one encoding and one digest.
//!
//! A valid profile is dense (it lists every leaf and subleaf in range), masks
//! exactly the bits that it does not own, and fixes the time ABI's CPU time
//! bits ([`TIME_BITS`]); every way to build or decode a profile checks this.
//!
//! Every serialized struct declares its fields in the byte order of their
//! keys, so serializing it directly gives the canonical form (tests check
//! this against the sorting encoder). Keep new fields in that order.
Expand All @@ -33,6 +37,8 @@ use crate::error::ProfileErrorCode;
use crate::fingerprint::IA32_ARCH_CAPABILITIES;
use crate::signature::HostCpuSignature;
use crate::signature::decode_signature;
use crate::surface::REGISTERS;
use crate::surface::bits_phrase;
use crate::vendor::CpuVendor;
use serde::Deserialize;
use serde::Serialize;
Expand All @@ -50,6 +56,39 @@ const MAX_SUBLEAF_IN_EAX_LEAVES: [u32; 6] = [0x7, 0x14, 0x17, 0x18, 0x1d, 0x24];
/// `CPUID.(7,0):EDX[29]`, the presence of `IA32_ARCH_CAPABILITIES`.
const LEAF7_EDX_ARCH_CAPABILITIES: u32 = 1 << 29;

/// The CPU time bits of the NVX time ABI, which every profile fixes: for each
/// leaf and subleaf, the bits of `EAX`, `EBX`, `ECX`, and `EDX` that the time
/// ABI governs, and their values. A leaf that a profile does not list reads
/// as zero, so leaves `0x15` and `0x16` above the maximum basic leaf comply.
pub(crate) const TIME_BITS: [(u32, Option<u32>, [u32; 4], [u32; 4]); 8] = [
// The hypervisor and TSC bits, and neither the TSC-deadline timer nor
// PDCM.
(
0x1,
None,
[0, 0, 1 << 31 | 1 << 24 | 1 << 15, 1 << 4],
[0, 0, 1 << 31, 1 << 4],
),
// ARAT only.
(0x6, None, [!0; 4], [1 << 2, 0, 0, 0]),
// No `IA32_TSC_ADJUST`.
(0x7, Some(0), [0, 1 << 1, 0, 0], [0; 4]),
// No PMU.
(0xa, None, [!0; 4], [0; 4]),
// No TSC or processor frequency leaves.
(0x15, None, [!0; 4], [0; 4]),
(0x16, None, [!0; 4], [0; 4]),
// RDTSCP.
(
EXTENDED_LEAF_BASE + 1,
None,
[0, 0, 0, 1 << 27],
[0, 0, 0, 1 << 27],
),
// The invariant TSC only.
(EXTENDED_LEAF_BASE + 7, None, [!0; 4], [0, 0, 0, 1 << 8]),
];

/// The CPU generation that a profile serves.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
Expand Down Expand Up @@ -275,8 +314,9 @@ impl CpuProfile {

/// Returns the canonical encoding: compact canonical JSON.
///
/// Offline only, for tools and tests: a pinned profile's encoding is the
/// constant [`pinned_record`](crate::pinned_record) returns.
/// A pinned profile's encoding is the constant
/// [`pinned_record`](crate::pinned_record) returns, which the profile's
/// first use in a process compares with this, to verify the profile.
pub fn encode(&self) -> Vec<u8> {
canonical::to_compact_ordered(self)
}
Expand Down Expand Up @@ -401,7 +441,7 @@ impl CpuProfile {

/// Checks every structural invariant of a profile; see the module
/// documentation and [`SCHEMA`].
fn validate(&self) -> Result<(), String> {
pub(crate) fn validate(&self) -> Result<(), String> {
if self.schema != SCHEMA {
return Err(format!("schema {:?} is not {SCHEMA:?}", self.schema));
}
Expand All @@ -416,7 +456,7 @@ impl CpuProfile {
self.physical_address_width
));
}
Ok(())
self.validate_time_bits()
}

/// Checks the profile's identity and returns its vendor.
Expand Down Expand Up @@ -625,6 +665,37 @@ impl CpuProfile {
}
Ok(())
}

/// Checks the CPU time bits ([`TIME_BITS`]), naming every bit that
/// violates them.
fn validate_time_bits(&self) -> Result<(), String> {
let mut violations = Vec::new();
for (leaf, subleaf, governed, expected) in TIME_BITS {
let value = self.lookup(leaf, subleaf.unwrap_or(0));
for register in 0..4 {
let set = value[register] & governed[register] & !expected[register];
let clear = !value[register] & governed[register] & expected[register];
for (bits, state) in [(set, "set"), (clear, "clear")] {
if bits != 0 {
violations.push(format!(
"{} {} {} {state}",
describe_leaf(leaf, subleaf),
REGISTERS[register],
bits_phrase(bits.into())
));
}
}
}
}
if violations.is_empty() {
Ok(())
} else {
Err(format!(
"it violates the CPU time bits: {}",
violations.join("; ")
))
}
}
}

/// Returns whether `component` is a valid vendor or generation component of a
Expand Down Expand Up @@ -765,6 +836,21 @@ mod tests {
.unwrap()
}

/// Replaces `register` of the CPUID entry of `leaf` and `subleaf` in a
/// profile's JSON with what `edit` makes of it.
fn edit_register(
value: &mut Value,
leaf: u32,
subleaf: Option<u32>,
register: usize,
edit: impl FnOnce(u32) -> u32,
) {
let field = &mut entry(value, leaf, subleaf)["value"][register];
let old =
u32::from_str_radix(field.as_str().unwrap().trim_start_matches("0x"), 16).unwrap();
*field = json!(format!("{:#010x}", edit(old)));
}

fn assert_invalid(result: Result<CpuProfile, ProfileError>, expected: &str) {
let error = result.unwrap_err();
assert_eq!(error.code, ProfileErrorCode::ProfileDigest, "{error}");
Expand Down Expand Up @@ -956,6 +1042,69 @@ mod tests {
);
}

#[test]
fn validation_rejects_profiles_that_violate_the_cpu_time_bits() {
// Every pinned profile fixes them, those whose maximum basic leaf is
// below 0x15 included.
for profile in crate::pinned_profiles() {
profile.validate_time_bits().unwrap();
}
for (leaf, subleaf, register, set, clear, expected) in [
(0x1, None, 2, 0, 1 << 31, "CPUID 0x1 ECX bit 31 is clear"),
(0x1, None, 2, 1 << 24, 0, "CPUID 0x1 ECX bit 24 is set"),
(0x1, None, 2, 1 << 15, 0, "CPUID 0x1 ECX bit 15 is set"),
(0x1, None, 3, 0, 1 << 4, "CPUID 0x1 EDX bit 4 is clear"),
(
0x6,
None,
0,
0x73,
1 << 2,
"CPUID 0x6 EAX bits 0, 1, 4, 5, 6 are set; CPUID 0x6 EAX bit 2 is clear",
),
(0x6, None, 2, 1 << 3, 0, "CPUID 0x6 ECX bit 3 is set"),
(0x7, Some(0), 1, 1 << 1, 0, "CPUID 0x7.0 EBX bit 1 is set"),
(0xa, None, 0, 1, 0, "CPUID 0xa EAX bit 0 is set"),
(0x15, None, 2, 1 << 5, 0, "CPUID 0x15 ECX bit 5 is set"),
(0x16, None, 0, 1 << 11, 0, "CPUID 0x16 EAX bit 11 is set"),
(
0x8000_0001,
None,
3,
0,
1 << 27,
"CPUID 0x80000001 EDX bit 27 is clear",
),
(
0x8000_0007,
None,
3,
1 << 9,
1 << 8,
"CPUID 0x80000007 EDX bit 9 is set; CPUID 0x80000007 EDX bit 8 is clear",
),
] {
assert_invalid(
decode_edited(|value| {
edit_register(value, leaf, subleaf, register, |old| (old | set) & !clear)
}),
&format!(
"profile \"{ICELAKE}\" is invalid: it violates the CPU time bits: {expected}"
),
);
}

// Every violation is named.
assert_invalid(
decode_edited(|value| {
edit_register(value, 1, None, 2, |ecx| ecx | 1 << 24);
edit_register(value, 0x8000_0001, None, 3, |edx| edx & !(1 << 27));
}),
"it violates the CPU time bits: CPUID 0x1 ECX bit 24 is set; \
CPUID 0x80000001 EDX bit 27 is clear",
);
}

#[test]
fn masks_leave_the_vm_and_runtime_fields_to_openvmm() {
for vendor in CpuVendor::ALL {
Expand Down
4 changes: 2 additions & 2 deletions vmm_core/cpu_profile/src/surface.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ use crate::unlisted::unlisted_cpuid_error;
use crate::unlisted::unlisted_cpuid_violations;

/// The register names, for messages.
const REGISTERS: [&str; 4] = ["EAX", "EBX", "ECX", "EDX"];
pub(crate) const REGISTERS: [&str; 4] = ["EAX", "EBX", "ECX", "EDX"];

/// The CPU surface a backend supports on this host, which it reports through
/// `supported_cpu_surface()` and which the CPU fingerprint records.
Expand Down Expand Up @@ -375,7 +375,7 @@ pub(crate) fn field_value(value: u32, shift: u32, width: u32) -> u32 {
}

/// Returns `bit 16 is` or `bits 3, 7 are`.
fn bits_phrase(bits: u64) -> String {
pub(crate) fn bits_phrase(bits: u64) -> String {
let list = (0..64)
.filter(|bit| bits & (1 << bit) != 0)
.map(|bit| bit.to_string())
Expand Down
2 changes: 1 addition & 1 deletion vmm_core/cpu_profile/src/test_support.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ use crate::signature::decode_signature;

/// Returns the pinned profile `id`.
pub(crate) fn profile(id: &str) -> &'static CpuProfile {
crate::pinned(id).unwrap_or_else(|| panic!("profile {id} is not pinned"))
crate::pinned(id).unwrap_or_else(|error| panic!("{error}"))
}

/// Returns a profile's CPUID values as fingerprint entries.
Expand Down
2 changes: 1 addition & 1 deletion vmm_core/virt_mshv/src/x86_64/profile_features.rs
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,7 @@ mod tests {
];

fn profile(id: &str) -> &'static CpuProfile {
cpu_profile::pinned(id).unwrap_or_else(|| panic!("profile {id} is not pinned"))
cpu_profile::pinned(id).unwrap_or_else(|error| panic!("{error}"))
}

fn has(features: &HvFeatures, word: HvFeatureWord, mask: u64) -> bool {
Expand Down
Loading