petri/vm/openvmm/

mod.rs

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

//! Code managing the lifetime of a `PetriVmOpenVmm`. All VMs live the same lifecycle:
//! * A `PetriVmConfigOpenVmm` is built for the given firmware and architecture in `construct`.
//! * The configuration is optionally modified from the defaults using the helpers in `modify`.
//! * The `PetriVmOpenVmm` is started by the code in `start`.
//! * The VM is interacted with through the methods in `runtime`.
//! * The VM is either shut down by the code in `runtime`, or gets dropped and cleaned up automatically.

mod construct;
#[cfg(target_os = "linux")]
mod hugetlb;
mod modify;
mod mshv;
mod runtime;
mod start;

#[cfg(target_os = "linux")]
pub use hugetlb::HUGETLB_2MB_PAGE_SIZE;
#[cfg(target_os = "linux")]
pub use hugetlb::ensure_2mb_hugetlb_pages;
pub use runtime::OpenVmmFramebufferAccess;
pub use runtime::OpenVmmInspector;
pub use runtime::PetriVmOpenVmm;

use crate::Disk;
use crate::DiskPath;
use crate::Firmware;
use crate::ModifyFn;
use crate::OpenHclServicingFlags;
use crate::OpenvmmLogConfig;
use crate::PetriLogFile;
use crate::PetriVmConfig;
use crate::PetriVmResources;
use crate::PetriVmRuntimeConfig;
use crate::PetriVmgsDisk;
use crate::PetriVmgsResource;
use crate::PetriVmmBackend;
use crate::VmmQuirks;
use crate::linux_direct_serial_agent::LinuxDirectSerialAgent;
use crate::vm::PetriVmProperties;
use anyhow::Context;
use async_trait::async_trait;
use disk_backend_resources::DiskLayerDescription;
use disk_backend_resources::LayeredDiskHandle;
use disk_backend_resources::layer::DiskLayerHandle;
use disk_backend_resources::layer::RamDiskLayerHandle;
use disk_backend_resources::layer::SqliteAutoCacheDiskLayerHandle;
use get_resources::ged::FirmwareEvent;
use guid::Guid;
use hyperv_ic_resources::shutdown::ShutdownRpc;
use mesh::Receiver;
use mesh::Sender;
use net_backend_resources::mac_address::MacAddress;
use openvmm_defs::config::Config;
use openvmm_helpers::disk::OpenDiskOptions;
use openvmm_helpers::disk::open_disk_type;
use pal_async::DefaultDriver;
use pal_async::socket::PolledSocket;
use pal_async::task::Task;
use petri_artifacts_common::tags::GuestQuirksInner;
use petri_artifacts_common::tags::MachineArch;
use petri_artifacts_core::ArtifactResolver;
use petri_artifacts_core::ResolvedArtifact;
use std::path::Path;
use std::path::PathBuf;
use std::sync::Arc;
use std::time::Duration;
use tempfile::TempPath;
use unix_socket::UnixListener;
use vm_resource::IntoResource;
use vm_resource::Resource;
use vm_resource::kind::DiskHandleKind;
use vmgs_resources::VmgsDisk;
use vmgs_resources::VmgsResource;

/// The instance guid for the MANA nic automatically added when specifying [`PetriVmConfigOpenVmm::with_nic`]
const MANA_INSTANCE: Guid = guid::guid!("f9641cf4-d915-4743-a7d8-efa75db7b85a");

/// The MAC address used by the NIC assigned with [`PetriVmConfigOpenVmm::with_nic`].
pub const NIC_MAC_ADDRESS: MacAddress = MacAddress::new([0x00, 0x15, 0x5D, 0x12, 0x12, 0x12]);

/// OpenVMM Petri Backend
#[derive(Debug)]
pub struct OpenVmmPetriBackend {
    openvmm_path: ResolvedArtifact,
}

impl OpenVmmPetriBackend {
    /// Launch a separately supplied, protocol-compatible native executable.
    pub fn from_binary(path: PathBuf) -> Self {
        Self {
            openvmm_path: ResolvedArtifact::from_local_path(path),
        }
    }
}

#[async_trait]
impl PetriVmmBackend for OpenVmmPetriBackend {
    type VmmConfig = PetriVmConfigOpenVmm;
    type VmRuntime = PetriVmOpenVmm;
    const SUPPORTS_VMBUS: bool = true;
    const SUPPORTS_FILE_SHARING: bool = cfg!(any(windows, target_os = "linux"));

    fn check_compat(firmware: &Firmware, arch: MachineArch) -> bool {
        !(firmware.is_openhcl() && (!cfg!(windows) || arch == MachineArch::Aarch64))
    }

    fn quirks(firmware: &Firmware) -> (GuestQuirksInner, VmmQuirks) {
        (
            firmware.quirks().openvmm,
            VmmQuirks {
                // Workaround for #3897
                flaky_boot: firmware.is_pcat().then_some(Duration::from_secs(15)),
            },
        )
    }

    fn default_servicing_flags() -> OpenHclServicingFlags {
        OpenHclServicingFlags {
            enable_nvme_keepalive: true,
            enable_mana_keepalive: true,
            override_version_checks: false,
            stop_timeout_hint_secs: None,
        }
    }

    fn create_guest_dump_disk() -> anyhow::Result<
        Option<(
            Arc<TempPath>,
            Box<dyn FnOnce() -> anyhow::Result<Box<dyn fatfs::ReadWriteSeek>>>,
        )>,
    > {
        Ok(None) // TODO #2403
    }

    fn build_custom_init_script(_pipette_path: &str) -> Option<String> {
        None
    }

    fn new(resolver: &ArtifactResolver<'_>, arch: MachineArch) -> Self {
        // OpenVMM guests must have the same arch as the host
        assert_eq!(arch, MachineArch::host());
        OpenVmmPetriBackend {
            openvmm_path: resolver
                .require(petri_artifacts_vmm_test::artifacts::OPENVMM_NATIVE)
                .erase(),
        }
    }

    async fn run(
        self,
        config: PetriVmConfig,
        modify_vmm_config: Option<ModifyFn<Self::VmmConfig>>,
        resources: &PetriVmResources,
        properties: &PetriVmProperties,
    ) -> anyhow::Result<(Self::VmRuntime, PetriVmRuntimeConfig)> {
        let mut config =
            PetriVmConfigOpenVmm::new(&self.openvmm_path, config, resources, properties).await?;

        if let Some(f) = modify_vmm_config {
            config = f.0(config);
        }

        config.run().await
    }
}

/// Configuration state for a test VM.
pub struct PetriVmConfigOpenVmm {
    guest_shares: std::collections::HashMap<String, crate::GuestShare>,
    // Direct configuration related information.
    runtime_config: PetriVmRuntimeConfig,
    arch: MachineArch,
    host_log_levels: Option<OpenvmmLogConfig>,
    config: Config,

    // Mesh host
    mesh: mesh_process::Mesh,

    // Runtime resources
    resources: PetriVmResourcesOpenVmm,

    // Logging
    openvmm_log_file: PetriLogFile,

    // File-backed guest memory.
    memory_backing_file: Option<PathBuf>,

    // The private-memory setting explicitly requested via
    // `MemoryConfig::private_memory`, preserved so that backend methods which
    // force shared memory (e.g. `with_hugepages`, `with_memory_backing_file`)
    // can fail when the caller explicitly asked for private memory rather than
    // silently downgrading it.
    requested_private_memory: Option<bool>,

    // Resources that are only used during startup.
    ged: Option<get_resources::ged::GuestEmulationDeviceHandle>,
    framebuffer_view: Option<framebuffer::View>,

    // Deferred IOMMU configuration: (rc_name, iommu_config) pairs resolved
    // against pcie_root_complexes at VM start time.
    pending_iommu: Vec<(String, openvmm_defs::config::PcieIommuConfig)>,
}
/// Various channels and resources used to interact with the VM while it is running.
struct PetriVmResourcesOpenVmm {
    log_stream_tasks: Vec<Task<anyhow::Result<()>>>,
    firmware_event_recv: Receiver<FirmwareEvent>,
    ipmi_sel_event_recv: Receiver<get_resources::ged::IpmiSelEvent>,
    shutdown_ic_send: Option<Sender<ShutdownRpc>>,
    kvp_ic_send: Option<Sender<hyperv_ic_resources::kvp::KvpConnectRpc>>,
    ged_send: Option<Sender<get_resources::ged::GuestEmulationRequest>>,
    pipette_listener: PolledSocket<UnixListener>,
    vtl2_pipette_listener: Option<PolledSocket<UnixListener>>,
    linux_direct_serial_agent: Option<LinuxDirectSerialAgent>,

    /// When set, the host connects to pipette via TCP through consomme
    /// port forwarding instead of accepting on the Unix socket listener.
    /// Used for Windows no-vmbus guests where virtio-vsock is unavailable.
    /// The receiver yields the OS-assigned host port once the consomme
    /// resolver has bound the socket.
    tcp_pipette_port: Option<mesh::OneshotReceiver<u16>>,

    // Externally injected management stuff also needed at runtime.
    driver: DefaultDriver,
    openvmm_path: ResolvedArtifact,
    output_dir: PathBuf,

    // TempPaths that cannot be dropped until the end.
    vtl2_vsock_path: Option<TempPath>,
    _vsock_path: TempPath,

    // properties needed at runtime
    properties: PetriVmProperties,

    // vmswitch DirectIO switch port handles, held in the test (parent)
    // process for the lifetime of the child VMM so the kernel port object
    // survives until the VMM detaches.
    #[cfg(windows)]
    _switch_ports: Vec<vmswitch::kernel::SwitchPort>,
}

/// Discovers a usable Hyper-V virtual switch for `-net dio` tests.
///
/// Tries the well-known Default Switch GUID first (which is provisioned
/// automatically when Hyper-V is installed). If that switch is not
/// available (e.g. it was removed, or this host uses a different default
/// switch SKU), falls back to enumerating all HCN networks and returning
/// the first one reported.
///
/// Returns `None` when no switch can be opened — typically because
/// Hyper-V is not installed, the user lacks privileges, or
/// `computenetwork.dll` is missing.
#[cfg(windows)]
pub fn find_switch() -> Option<Guid> {
    if vmswitch::hcn::Network::open(&vmswitch::hcn::DEFAULT_SWITCH).is_ok() {
        return Some(vmswitch::hcn::DEFAULT_SWITCH);
    }
    let networks = match vmswitch::hcn::enumerate_networks() {
        Ok(n) => n,
        Err(e) => {
            tracing::warn!(
                error = &e as &dyn std::error::Error,
                "failed to enumerate HCN networks"
            );
            return None;
        }
    };
    networks.into_iter().find(|guid| {
        if let Err(e) = vmswitch::hcn::Network::open(guid) {
            tracing::debug!(
                %guid,
                error = &e as &dyn std::error::Error,
                "skipping unopenable HCN network"
            );
            false
        } else {
            true
        }
    })
}

/// Discovers a usable Hyper-V virtual switch.
///
/// Always `None` on non-Windows platforms.
#[cfg(not(windows))]
pub fn find_switch() -> Option<Guid> {
    None
}

async fn memdiff_disk(path: &Path) -> anyhow::Result<Resource<DiskHandleKind>> {
    let disk = open_disk_type(
        path,
        OpenDiskOptions {
            read_only: true,
            direct: false,
        },
    )
    .await
    .with_context(|| format!("failed to open disk: {}", path.display()))?;
    Ok(LayeredDiskHandle {
        layers: vec![
            RamDiskLayerHandle {
                len: None,
                sector_size: None,
            }
            .into_resource()
            .into(),
            DiskLayerHandle(disk).into_resource().into(),
        ],
    }
    .into_resource())
}

fn memdiff_remote_disk(url: &str) -> anyhow::Result<Resource<DiskHandleKind>> {
    // Strip query parameters and fragments before checking the file extension.
    let url_path = url.split(['?', '#']).next().unwrap_or(url);
    let format = if url_path.ends_with(".vhd") || url_path.ends_with(".vmgs") {
        disk_backend_resources::BlobDiskFormat::FixedVhd1
    } else {
        disk_backend_resources::BlobDiskFormat::Flat
    };

    let cache_dir = super::petri_disk_cache_dir();

    // For VHD1-formatted blobs, let the auto-cache layer derive the cache key
    // from the VHD's unique ID (a UUID embedded in the footer). This means the
    // cache automatically invalidates when the image is replaced with a new one,
    // even if the filename stays the same. For flat-format blobs (e.g. ISOs),
    // fall back to the URL filename since there's no embedded ID.
    let cache_key = match format {
        disk_backend_resources::BlobDiskFormat::FixedVhd1 => None,
        disk_backend_resources::BlobDiskFormat::Flat => {
            Some(url_path.rsplit('/').next().unwrap_or(url_path).to_owned())
        }
    };

    Ok(LayeredDiskHandle {
        layers: vec![
            RamDiskLayerHandle {
                len: None,
                sector_size: None,
            }
            .into_resource()
            .into(),
            DiskLayerDescription {
                read_cache: true,
                write_through: false,
                layer: SqliteAutoCacheDiskLayerHandle {
                    cache_path: cache_dir,
                    cache_key,
                }
                .into_resource(),
            },
            DiskLayerHandle(
                disk_backend_resources::BlobDiskHandle {
                    url: url.to_owned(),
                    format,
                }
                .into_resource(),
            )
            .into_resource()
            .into(),
        ],
    }
    .into_resource())
}

async fn memdiff_vmgs(vmgs: &PetriVmgsResource) -> anyhow::Result<VmgsResource> {
    async fn convert_disk(disk: &PetriVmgsDisk) -> anyhow::Result<VmgsDisk> {
        Ok(VmgsDisk {
            disk: petri_disk_to_openvmm(&disk.disk).await?,
            encryption_policy: disk.encryption_policy,
        })
    }

    Ok(match vmgs {
        PetriVmgsResource::Disk(disk) => VmgsResource::Disk(convert_disk(disk).await?),
        PetriVmgsResource::ReprovisionOnFailure(disk) => {
            VmgsResource::ReprovisionOnFailure(convert_disk(disk).await?)
        }
        PetriVmgsResource::Reprovision(disk) => {
            VmgsResource::Reprovision(convert_disk(disk).await?)
        }
        PetriVmgsResource::Ephemeral => VmgsResource::Ephemeral,
    })
}

async fn petri_disk_to_openvmm(disk: &Disk) -> anyhow::Result<Resource<DiskHandleKind>> {
    Ok(match disk {
        Disk::Memory(len) => LayeredDiskHandle::single_layer(RamDiskLayerHandle {
            len: Some(*len),
            sector_size: None,
        })
        .into_resource(),
        Disk::Differencing(DiskPath::Local(path)) => memdiff_disk(path).await?,
        Disk::Differencing(DiskPath::Remote { url }) => memdiff_remote_disk(url)?,
        Disk::Persistent(path) => {
            open_disk_type(
                path.as_ref(),
                OpenDiskOptions {
                    read_only: false,
                    direct: false,
                },
            )
            .await?
        }
        Disk::Temporary(path) => {
            open_disk_type(
                path.as_ref(),
                OpenDiskOptions {
                    read_only: false,
                    direct: false,
                },
            )
            .await?
        }
    })
}