Skip to main content

virt_kvm/
lib.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! KVM implementation of the virt::generic interfaces.
5
6#![cfg(all(target_os = "linux", guest_is_native))]
7#![expect(missing_docs)]
8// UNSAFETY: Calling KVM APIs and manually managing memory.
9#![expect(unsafe_code)]
10#![expect(clippy::undocumented_unsafe_blocks)]
11
12mod arch;
13mod gsi;
14mod memory;
15
16cfg_select! {
17    guest_arch = "x86_64" => {
18        mod snp;
19        pub use snp::SnpError;
20        use snp::SnpLaunchState;
21    }
22    _ => {}
23}
24
25pub use arch::Kvm;
26pub use memory::MemoryError;
27
28use guestmem::GuestMemory;
29use inspect::Inspect;
30use memory::KvmMemoryBackingMode;
31use memory::KvmMemoryRangeState;
32use memory_range::MemoryRange;
33use parking_lot::Mutex;
34use std::sync::Arc;
35use thiserror::Error;
36use virt::state::StateError;
37
38/// Returns whether KVM is available on this machine.
39pub fn is_available() -> Result<bool, KvmError> {
40    match std::fs::metadata("/dev/kvm") {
41        Ok(_) => Ok(true),
42        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(false),
43        Err(err) => Err(KvmError::AvailableCheck(err)),
44    }
45}
46
47use arch::KvmVpInner;
48use std::sync::atomic::Ordering;
49use virt::VpIndex;
50use vmcore::vmtime::VmTimeAccess;
51
52#[derive(Error, Debug)]
53pub enum KvmError {
54    #[error("operation not supported")]
55    NotSupported,
56    #[error("vtl2 is not supported on this hypervisor")]
57    Vtl2NotSupported,
58    #[error("isolation is not supported on this hypervisor")]
59    IsolationNotSupported,
60    #[error("kvm error")]
61    Kvm(#[from] kvm::Error),
62    #[error(transparent)]
63    Memory(#[from] MemoryError),
64    #[cfg(guest_arch = "x86_64")]
65    #[error(transparent)]
66    Snp(#[from] SnpError),
67    #[error("failed to stat /dev/kvm")]
68    AvailableCheck(#[source] std::io::Error),
69    #[error(transparent)]
70    State(#[from] Box<StateError<KvmError>>),
71    #[error("invalid state while restoring: {0}")]
72    InvalidState(&'static str),
73    #[error("unsupported isolation configuration: {0}")]
74    UnsupportedIsolationConfiguration(&'static str),
75    #[error("misaligned gic base address")]
76    Misaligned,
77    #[error("host does not support GICv2 or GICv3")]
78    NoGic,
79    #[error("host does not support required cpu capabilities")]
80    Capabilities(virt::PartitionCapabilitiesError),
81    #[cfg(guest_arch = "aarch64")]
82    #[error("failed to set MPIDR_EL1 for VP {vp_index}")]
83    SetMpidr {
84        vp_index: u32,
85        #[source]
86        err: kvm::Error,
87    },
88    #[cfg(guest_arch = "x86_64")]
89    #[error("nested virtualization was requested but the host does not support it")]
90    NestedVirtUnsupported,
91    #[cfg(guest_arch = "x86_64")]
92    #[error("unsupported CPU vendor")]
93    UnsupportedCpuVendor,
94    #[cfg(guest_arch = "x86_64")]
95    #[error("failed to compute topology cpuid")]
96    TopologyCpuid(#[source] virt::x86::topology::UnknownVendor),
97}
98
99#[derive(Inspect)]
100pub struct KvmPartition {
101    #[inspect(flatten)]
102    inner: Arc<KvmPartitionInner>,
103    #[cfg(guest_arch = "x86_64")]
104    #[inspect(skip)]
105    synic_ports: Arc<virt::synic::SynicPorts<KvmPartitionInner>>,
106    #[inspect(skip)]
107    irqfd_state: Arc<gsi::KvmIrqFdState>,
108}
109
110#[derive(Inspect)]
111struct KvmPartitionInner {
112    #[inspect(skip)]
113    kvm: kvm::Partition,
114    #[cfg(guest_arch = "x86_64")]
115    #[inspect(skip)]
116    sev: Option<std::fs::File>,
117    #[cfg(guest_arch = "x86_64")]
118    #[inspect(skip)]
119    snp_config: Option<snp::KvmSnpConfig>,
120    #[cfg(guest_arch = "x86_64")]
121    #[inspect(skip)]
122    snp_launch_state: Mutex<SnpLaunchState>,
123    memory: Mutex<KvmMemoryRangeState>,
124    memory_backing_mode: KvmMemoryBackingMode,
125    #[inspect(iter_by_index)]
126    ram_ranges: Vec<MemoryRange>,
127    hv1_enabled: bool,
128    gm: GuestMemory,
129    #[cfg(guest_arch = "x86_64")]
130    #[inspect(skip)]
131    bsp_cpuid: Vec<kvm::kvm_cpuid_entry2>,
132    #[inspect(skip)]
133    vps: Vec<KvmVpInner>,
134    #[inspect(skip)]
135    gsi_routing: Mutex<gsi::GsiRouting>,
136    caps: virt::PartitionCapabilities,
137
138    // This is used for debugging via Inspect
139    #[cfg(guest_arch = "x86_64")]
140    cpuid: virt::CpuidLeafSet,
141
142    #[cfg(guest_arch = "x86_64")]
143    reserved_vps_per_socket: u32,
144
145    /// Whether the host allows advertising `MCG_CMCI_P` in the guest's
146    /// `IA32_MCG_CAP` (required for KVM to expose the CMCI LVT register).
147    #[cfg(guest_arch = "x86_64")]
148    mce_cmci_supported: bool,
149
150    /// The GIC device fd, kept alive for the VM lifetime.
151    #[cfg(guest_arch = "aarch64")]
152    #[inspect(skip)]
153    _gic_device: kvm::Device,
154    /// The ITS device fd, kept alive for the VM lifetime.
155    #[cfg(guest_arch = "aarch64")]
156    #[inspect(skip)]
157    _its_device: Option<kvm::Device>,
158    /// MSI controller configuration (v2m, ITS, or none).
159    #[cfg(guest_arch = "aarch64")]
160    #[inspect(skip)]
161    gic_msi: vm_topology::processor::aarch64::GicMsiController,
162    /// Total configured GIC interrupt count (SGIs + PPIs + SPIs).
163    #[cfg(guest_arch = "aarch64")]
164    gic_nr_irqs: u32,
165    #[cfg(guest_arch = "x86_64")]
166    synic_ports: virt::synic::SynicPortMap,
167}
168
169// TODO: Chunk this up into smaller types.
170#[derive(Debug, Error)]
171enum KvmRunVpError {
172    #[error("KVM internal error: {0:#x}")]
173    InternalError(u32),
174    #[error("invalid vp state")]
175    InvalidVpState,
176    #[error("failed to run VP")]
177    Run(#[source] kvm::Error),
178    #[error("unhandled system event type: {0:#x}")]
179    UnhandledSystemEvent(u32),
180    #[cfg(guest_arch = "x86_64")]
181    #[error("unhandled KVM hypercall: nr={nr:#x}, flags={flags:#x}")]
182    UnhandledHypercall { nr: u64, flags: u64 },
183    #[cfg(guest_arch = "x86_64")]
184    #[error(
185        "SEV guest requested termination: ghcb_msr={ghcb_msr:#x} reason_set={reason_set:#x} reason={reason:#x}"
186    )]
187    SevTermination {
188        ghcb_msr: u64,
189        reason_set: u64,
190        reason: u64,
191    },
192    #[cfg(guest_arch = "x86_64")]
193    #[error("failed to inject an extint interrupt")]
194    ExtintInterrupt(#[source] kvm::Error),
195    #[cfg(guest_arch = "x86_64")]
196    #[error("cannot inject an extint: the VP is not ready for interrupt injection")]
197    ExtintNotInjectable,
198}
199
200pub struct KvmProcessorBinder {
201    partition: Arc<KvmPartitionInner>,
202    vpindex: VpIndex,
203    vmtime: VmTimeAccess,
204}
205
206impl KvmPartitionInner {
207    #[cfg(guest_arch = "x86_64")]
208    fn bsp(&self) -> &KvmVpInner {
209        &self.vps[0]
210    }
211
212    fn vp(&self, vp_index: VpIndex) -> Option<&KvmVpInner> {
213        self.vps.get(vp_index.index() as usize)
214    }
215
216    fn evaluate_vp(&self, vp_index: VpIndex) {
217        let Some(vp) = self.vp(vp_index) else { return };
218        vp.set_eval(true, Ordering::Relaxed);
219
220        let vp_id = cfg_select! {
221            guest_arch = "x86_64" => vp.vp_info().apic_id,
222            guest_arch = "aarch64" => vp.vp_info().base.vp_index.index(),
223        };
224        self.kvm.vp(vp_id).force_exit();
225    }
226}