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
5 changes: 3 additions & 2 deletions Guide/src/dev_guide/tests/vmm.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,9 @@ the partition and bind its single VP before invoking the function. Cases have
names such as `time::kvm::initial_frozen` and `time::whp::clock_restore`.
Fixtures default to unenlightened; `hv1: true` enables Hv1, using native
enlightenment offload on WHP. A contract that only KVM owes, such as its refusal
of a restored `EFER.SVME` for a guest whose CPUID has no SVM, registers with
`kvm_only` and has a case for KVM alone.
of a restored `EFER.SVME` for a guest whose CPUID has no SVM, or of a restored
APIC timer whose delivery mode is not Fixed, registers with `kvm_only` and has a
case for KVM alone.
The clock contracts also have separately named Hv1-enabled cases:
`initial_frozen_hv1`, `freeze_thaw_hv1`, `reset_clocks_hv1`, and
`clock_restore_hv1`. These reuse the unenlightened contracts to check reference
Expand Down
10 changes: 10 additions & 0 deletions Guide/src/reference/architecture/timekeeping.md
Original file line number Diff line number Diff line change
Expand Up @@ -341,6 +341,16 @@ no expiry while the VP is outside guest mode, so the backend saves a
timer that had expired at the read as KVM reports it, and a restored
timer that the guest already took an interrupt from fires once more.

KVM also delivers the expiry of an unmasked timer in the delivery mode
of its LVT entry, which a guest cannot set, since KVM masks its writes
to the entry. So the backend refuses to restore a LAPIC state whose
unmasked timer entry has a delivery mode other than Fixed. Five of the
seven other modes would give the VP an INIT, a startup IPI, an NMI, or
an SMI, or wake it from halt, none of which the saved state holds, and
lowest priority and ExtINT, which KVM delivers as a fixed interrupt or
ignores, are refused too, since no save holds them either. A masked
entry delivers nothing, and is accepted.

KVM's synthetic-timer snapshot path saves config/count MSRs, but cannot
preserve timer adjustment or undelivered expiration-message state.

Expand Down
67 changes: 67 additions & 0 deletions vmm_core/virt_kvm/src/arch/x86_64/vp_state.rs
Original file line number Diff line number Diff line change
Expand Up @@ -483,6 +483,10 @@ impl AccessVpState for KvmVpStateAccess<'_, '_> {
}

fn set_apic(&mut self, value: &vp::Apic) -> Result<(), Self::Error> {
// Refuse the page before any state changes, so that a refusal leaves
// the VP's APIC, and the timer that it stopped with, as they were.
check_restorable_apic_timer(value.registers().lvt_timer)?;

// The VP's timer is no longer the one that it stopped with.
self.vp.timer_at_stop = None;

Expand Down Expand Up @@ -765,8 +769,34 @@ pub(super) fn kvm_lapic_page(registers: &vp::ApicRegisters) -> [u8; 1024] {
registers.as_page()
}

/// Refuses an APIC page whose LVT timer entry is unmasked and has a delivery
/// mode other than Fixed.
///
/// `KVM_SET_LAPIC` starts the timer again from the page's counts, and KVM
/// delivers its expiries through the entry's delivery mode. A timer that has
/// expired, as a one-shot timer whose current count is 0 has, fires at once:
/// inside the ioctl when APICv is active, and at the next `KVM_RUN` otherwise.
/// Most modes other than Fixed would give the restored VP an INIT, a startup
/// IPI, an NMI, or an SMI, or wake it from halt (remote read), none of which
/// the saved state holds. A guest cannot write the timer's delivery mode, since
/// KVM masks its writes to the entry, so a save never holds one, and only a
/// damaged or crafted saved state does. Lowest priority and ExtINT, which KVM
/// delivers as a fixed interrupt or ignores, are refused too. A masked entry
/// delivers nothing until the guest writes it, which clears its delivery mode,
/// so it is accepted.
fn check_restorable_apic_timer(lvt_timer: u32) -> Result<(), KvmError> {
let lvt = x86defs::apic::Lvt::from(lvt_timer);
if !lvt.masked() && lvt.delivery_mode() != x86defs::apic::DeliveryMode::FIXED.0 {
return Err(KvmError::InvalidState(
"an unmasked APIC timer whose delivery mode is not Fixed",
));
}
Ok(())
}

#[cfg(test)]
mod tests {
use super::check_restorable_apic_timer;
use super::check_restored_efer;
use super::kvm_lapic_page;
use crate::KvmError;
Expand All @@ -779,6 +809,9 @@ mod tests {
use x86defs::X64_EFER_NXE;
use x86defs::X64_EFER_SCE;
use x86defs::X64_EFER_SVME;
use x86defs::apic::DeliveryMode;
use x86defs::apic::Lvt;
use x86defs::apic::TimerMode;
use zerocopy::FromZeros;

const VECTOR: u32 = 0x40;
Expand Down Expand Up @@ -874,6 +907,40 @@ mod tests {
}
assert_eq!(kvm_initial_count(VECTOR, (0, 0), true), 0);
}

#[test]
fn an_unmasked_timer_that_is_not_fixed_is_refused() {
// KVM masks a guest's writes to the entry, so the guest never sets a
// delivery mode, whatever the timer's mode.
for timer_mode in [
TimerMode::ONE_SHOT,
TimerMode::PERIODIC,
TimerMode::TSC_DEADLINE,
] {
let fixed = Lvt::new()
.with_vector(VECTOR as u8)
.with_timer_mode(timer_mode.0);
assert_eq!(fixed.delivery_mode(), DeliveryMode::FIXED.0);
check_restorable_apic_timer(fixed.into()).unwrap();
check_restorable_apic_timer(fixed.with_masked(true).into()).unwrap();

for mode in 1..=7 {
let lvt = fixed.with_delivery_mode(mode);
assert!(
matches!(
check_restorable_apic_timer(lvt.into()),
Err(KvmError::InvalidState(_))
),
"timer mode {}, delivery mode {mode}",
timer_mode.0
);
// A masked entry delivers nothing.
check_restorable_apic_timer(lvt.with_masked(true).into()).unwrap();
}
}
// The reset value is masked.
check_restorable_apic_timer(MASKED).unwrap();
}
}

/// Restores of one-shot LAPIC timers through `KVM_SET_LAPIC`, with a real-mode
Expand Down
84 changes: 84 additions & 0 deletions vmm_tests/vmm_tests/tests/virt_backend_tests/apic.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

//! Guest-free contract tests of the APIC state that a backend restores.

use super::native::backend_test;
use hvdef::Vtl;
use virt::Partition;
use virt::Processor;
use virt::vp;
use virt::vp::AccessVpState as _;
use x86defs::apic::ApicBase;
use x86defs::apic::DeliveryMode;
use x86defs::apic::Lvt;
use x86defs::apic::TimerMode;

const TIMER_VECTOR: u8 = 0x40;
const INITIAL_COUNT: u32 = 1_000_000;

/// Returns `apic` with a one-shot timer that has expired: its initial count is
/// not 0, and its current count is. KVM fires such a timer as soon as it
/// restores the state, in the delivery mode of the timer's LVT entry, unless
/// the entry is masked.
fn expired_timer(apic: &vp::Apic, delivery_mode: DeliveryMode, masked: bool) -> vp::Apic {
let mut registers = *apic.registers();
registers.svr = 0x1ff;
registers.lvt_timer = Lvt::new()
.with_vector(TIMER_VECTOR)
.with_delivery_mode(delivery_mode.0)
.with_masked(masked)
.with_timer_mode(TimerMode::ONE_SHOT.0)
.into();
registers.timer_dcr = 0xb;
registers.timer_icr = INITIAL_COUNT;
registers.timer_ccr = 0;
vp::Apic::new(
ApicBase::from(apic.apic_base).with_enable(true),
registers,
apic.auto_eoi,
)
}

// KVM delivers the expiry of an unmasked timer in the delivery mode of its LVT
// entry, so most modes other than Fixed would give a restored VP an INIT, a
// startup IPI, an NMI, or an SMI, or wake it from halt, which the saved state
// does not hold; lowest priority and ExtINT, which KVM delivers as a fixed
// interrupt or ignores, would not. The guest cannot write the mode, so a save
// never holds an unmasked timer in any mode but Fixed, and the restore must
// refuse one.
backend_test!(restore_refuses_a_non_fixed_apic_timer, kvm_only, requires: []);
fn restore_refuses_a_non_fixed_apic_timer(
_partition: &impl Partition,
processor: &mut impl Processor,
) -> anyhow::Result<()> {
let mut state = processor.access_state(Vtl::Vtl0);
let reset = state.apic()?;

let mut accepted = Vec::new();
let mut changed = Vec::new();
for mode in (1..=7).map(DeliveryMode) {
if state.set_apic(&expired_timer(&reset, mode, false)).is_ok() {
accepted.push(mode.0);
state.set_apic(&reset)?;
} else if state.apic()? != reset {
changed.push(mode.0);
}
}
anyhow::ensure!(
accepted.is_empty(),
"the restore accepted an expired timer in the delivery modes {accepted:?}"
);
anyhow::ensure!(
changed.is_empty(),
"the refused restore changed the APIC state, for the delivery modes {changed:?}"
);

// What a save holds restores: an expired Fixed timer, and masked timers,
// which deliver nothing.
state.set_apic(&expired_timer(&reset, DeliveryMode::FIXED, false))?;
for mode in (0..=7).map(DeliveryMode) {
state.set_apic(&expired_timer(&reset, mode, true))?;
}
Ok(())
}
2 changes: 2 additions & 0 deletions vmm_tests/vmm_tests/tests/virt_backend_tests/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@

//! Native hypervisor contract tests without VM boot or guest artifacts.

#[cfg(all(guest_arch = "x86_64", guest_is_native, target_os = "linux"))]
mod apic;
#[cfg(all(
guest_arch = "x86_64",
guest_is_native,
Expand Down
Loading