diff --git a/Cargo.lock b/Cargo.lock index f91d6712adb..ef55d05df26 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1800,6 +1800,24 @@ dependencies = [ "windows-sys 0.61.0", ] +[[package]] +name = "disk_zerofill" +version = "0.0.0" +dependencies = [ + "anyhow", + "async-trait", + "disk_backend", + "disk_backend_resources", + "disklayer_ram", + "guestmem", + "inspect", + "pal_async", + "scsi_buffers", + "storage_tests", + "thiserror 2.0.16", + "vm_resource", +] + [[package]] name = "disklayer_ram" version = "0.0.0" @@ -6282,6 +6300,7 @@ dependencies = [ "disk_prwrap", "disk_vhd1", "disk_vhdmp", + "disk_zerofill", "disklayer_ram", "disklayer_sqlite", "disklayer_vhdx", diff --git a/Cargo.toml b/Cargo.toml index 84448c6d624..d37e4547356 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -347,6 +347,7 @@ disk_striped = { path = "vm/devices/storage/disk_striped" } disk_vhd1 = { path = "vm/devices/storage/disk_vhd1" } disklayer_vhdx = { path = "vm/devices/storage/disklayer_vhdx" } disk_vhdmp = { path = "vm/devices/storage/disk_vhdmp" } +disk_zerofill = { path = "vm/devices/storage/disk_zerofill" } disklayer_ram = { path = "vm/devices/storage/disklayer_ram" } disklayer_sqlite = { path = "vm/devices/storage/disklayer_sqlite" } floppy = { path = "vm/devices/storage/floppy" } diff --git a/Guide/src/dev_guide/snapshot_format.md b/Guide/src/dev_guide/snapshot_format.md index ea6ae4a84b6..ee5df5860ab 100644 --- a/Guide/src/dev_guide/snapshot_format.md +++ b/Guide/src/dev_guide/snapshot_format.md @@ -111,7 +111,10 @@ an available snapshot. A missing restore-mode field retains `private-copy` behavior. A pre-mount capture instead records the `fresh` scratch policy and geometry, -contains no `scratch.img`, and requires a new matching scratch file on restore. +contains no `scratch.img`, and requires a new scratch file of that geometry on +restore, unless `--restore-absent-scratch` declares the scratch absent: +OpenVMM then attaches a writable scratch device of that geometry with no file, +which reads zeros and fails every write. ## Code references diff --git a/Guide/src/reference/architecture/devices/storage.md b/Guide/src/reference/architecture/devices/storage.md index 0ba2e8d8354..c10dffbf1ee 100644 --- a/Guide/src/reference/architecture/devices/storage.md +++ b/Guide/src/reference/architecture/devices/storage.md @@ -107,7 +107,7 @@ A decorator is a `DiskIo` implementation that wraps another `Disk` and transform └── BlockDeviceDisk ``` -Three decorators exist: [`CryptDisk`](https://openvmm.dev/rustdoc/linux/disk_crypt/struct.CryptDisk.html) (XTS-AES-256 encryption), [`DelayDisk`](https://openvmm.dev/rustdoc/linux/disk_delay/struct.DelayDisk.html) (injected latency), and [`DiskWithReservations`](https://openvmm.dev/rustdoc/linux/disk_prwrap/struct.DiskWithReservations.html) (in-memory persistent reservation emulation). All three forward metadata (sector count, sector size, disk ID, `wait_resize`) to the inner disk unchanged. See the [storage backends](../../backends/storage.md) page for the decorator catalog. +Four decorators exist: [`CryptDisk`](https://openvmm.dev/rustdoc/linux/disk_crypt/struct.CryptDisk.html) (XTS-AES-256 encryption), [`DelayDisk`](https://openvmm.dev/rustdoc/linux/disk_delay/struct.DelayDisk.html) (injected latency), [`DiskWithReservations`](https://openvmm.dev/rustdoc/linux/disk_prwrap/struct.DiskWithReservations.html) (in-memory persistent reservation emulation), and [`ZeroFillDisk`](https://openvmm.dev/rustdoc/linux/disk_zerofill/struct.ZeroFillDisk.html) (a fixed geometry over a shorter inner disk, or none). The first three forward metadata (sector count, sector size, disk ID, `wait_resize`) to the inner disk unchanged. `ZeroFillDisk` presents its own sector count, which never changes: reads past the inner disk's end return zeros, and writes fail without reaching it. See the [storage backends](../../backends/storage.md) page for the decorator catalog. ## The layered disk model diff --git a/Guide/src/reference/backends/storage.md b/Guide/src/reference/backends/storage.md index 065cb0f1cbf..389795dfbbf 100644 --- a/Guide/src/reference/backends/storage.md +++ b/Guide/src/reference/backends/storage.md @@ -34,6 +34,7 @@ without modifying the backends underneath. | CryptDisk | [`disk_crypt`](https://openvmm.dev/rustdoc/linux/disk_crypt/index.html) | XTS-AES-256 encryption. Encrypts on write, decrypts on read. | | DelayDisk | [`disk_delay`](https://openvmm.dev/rustdoc/linux/disk_delay/index.html) | Adds configurable latency to each I/O operation. | | DiskWithReservations | [`disk_prwrap`](https://openvmm.dev/rustdoc/linux/disk_prwrap/index.html) | In-memory SCSI persistent reservation emulation. | +| ZeroFillDisk | [`disk_zerofill`](https://openvmm.dev/rustdoc/linux/disk_zerofill/index.html) | Presents a fixed sector count over a shorter disk, or none. Reads past the inner disk's end return zeros; writes fail. | ## Layered disks diff --git a/Guide/src/reference/openvmm/management/cli.md b/Guide/src/reference/openvmm/management/cli.md index d9a15d2e961..c89d713b696 100644 --- a/Guide/src/reference/openvmm/management/cli.md +++ b/Guide/src/reference/openvmm/management/cli.md @@ -392,7 +392,8 @@ describes the source definitions. mounted, it freezes the workload cgroup with a bounded wait, syncs, freezes the scratch filesystem, and asks OpenVMM to drain queues and atomically publish `scratch.img`. `/sbin/nvx-snapshot --fresh-scratch` is for a - pre-mount boundary and records that restore must supply a fresh scratch. + pre-mount boundary and records that restore must supply a fresh scratch, + or declare it absent with `--restore-absent-scratch`. * `--microvm-workload-identity `: Add a fixed non-root numeric workload identity to the host-owned microVM command line. UID and GID zero are rejected. The guest workload supervisor must resolve both values in the @@ -450,10 +451,15 @@ describes the source definitions. For sandbox-block snapshots, restore repeats each read-only `--microvm-sandbox-block` argument. Its role, access, geometry, and SHA-256 - must match the manifest. A paired snapshot supplies scratch internally from + must match the manifest, with two exceptions for a platform snapshot: its + read-only layers are unbound, and its `distro` block keeps the captured + capacity over an image that may be shorter. Such an image must have the + captured logical and physical block sizes, reads past its end return zeros, + and OpenVMM never resizes, pads, or writes it; a longer image is rejected. + A paired snapshot supplies scratch internally from a verified process-private copy of `scratch.img`; passing another scratch is rejected. A fresh-scratch snapshot instead requires a writable scratch - argument with matching geometry. + argument with matching geometry, or `--restore-absent-scratch`. `--restore-memory ` selects the total RAM for this launch. It requires an expansion-capable snapshot and a 128-MiB-aligned value from the exact @@ -503,6 +509,16 @@ describes the source definitions. validating the full saved VP inventory; that reduced-prefix process cannot be saved again. MSHV restores without this option, and KVM and WHP restores, instantiate the full VP capacity. +* `--restore-absent-scratch`: Restore a platform snapshot's fresh scratch + without a file. OpenVMM attaches the scratch device at the length and block + sizes that the manifest records. The device stays writable, as the guest + negotiated it and as the restore contract requires, but has nowhere to keep + data: reads return zeros, and every write fails with an I/O error, so no + write is dropped or kept in host memory. Only a platform snapshot's fresh + scratch may be absent. OpenVMM rejects the option before any vCPU starts + for a cold boot, for a paired snapshot or one without sandbox blocks, and + together with a scratch `--microvm-sandbox-block`. A scratch file, when given + instead, keeps the exact captured length. * `--restore-gate-timeout-ms `: Bound microVM guest repair and gate acknowledgement after restore. The default is 60000 milliseconds. * `--cpu-profile `: Select the microVM's pinned CPU profile, `auto` diff --git a/Guide/src/user_guide/openvmm/snapshots.md b/Guide/src/user_guide/openvmm/snapshots.md index 3971d084e53..c93975ec24f 100644 --- a/Guide/src/user_guide/openvmm/snapshots.md +++ b/Guide/src/user_guide/openvmm/snapshots.md @@ -184,7 +184,19 @@ host can connect while input is gated, but OpenVMM reads its authentication only after the release, so its `--microvm-control-auth-timeout-ms` deadline starts over when the gate releases. Platform manifests leave read-only layer identities unbound, while later tiers require exact image -identities. An instance-checkpoint restore attempt atomically creates +identities. A platform restore also presents the captured capacity of its +`distro` block before any vCPU runs, so one platform snapshot serves images of +any length up to that capacity. An image with the captured logical and +physical block sizes may be shorter, and reads past its end, including the tail +of a request that crosses it, return zeros. OpenVMM rejects a longer image and +never resizes, pads, or writes the image file. A platform restore may also +declare its fresh scratch absent with `--restore-absent-scratch`, for a clone +that never writes it, such as one that keeps its upper layer in RAM. OpenVMM +then attaches the scratch device with no file, at the captured length and +block sizes. The device stays writable, as the guest negotiated it, but reads +return zeros and writes fail with an I/O error: OpenVMM never drops a write or +keeps one in host memory. Only a platform snapshot's fresh scratch may be +absent, and a scratch file, when given, keeps the exact captured length. An instance-checkpoint restore attempt atomically creates `resume.claim`; subsequent restores are rejected. The claim is committed after artifact and configuration validation but before worker construction, so the restore attempt remains consumed if later worker startup fails. diff --git a/openvmm/openvmm_entry/src/cli_args/microvm.rs b/openvmm/openvmm_entry/src/cli_args/microvm.rs index 4f222144e28..710b8890edd 100644 --- a/openvmm/openvmm_entry/src/cli_args/microvm.rs +++ b/openvmm/openvmm_entry/src/cli_args/microvm.rs @@ -288,6 +288,14 @@ pub struct MicrovmCli { #[clap(long, value_name = "SIZE", requires = "restore_snapshot")] pub restore_memory: Option, + /// Attach a platform snapshot's fresh scratch with no file. + /// + /// The scratch device keeps the captured length and block sizes, and stays + /// writable, as the guest negotiated it: reads return zeros, and writes + /// fail with an I/O error. Do not pass a scratch block with it. + #[clap(long, requires = "restore_snapshot")] + pub restore_absent_scratch: bool, + /// Maximum time allowed for a microVM guest to complete post-restore repair. #[clap(long, value_name = "MILLISECONDS", default_value_t = 60000)] pub restore_gate_timeout_ms: u64, @@ -768,13 +776,14 @@ impl Options { && self.microvm.microvm_report.is_none() && self.microvm.restore_processors.is_none() && self.microvm.restore_memory.is_none() + && !self.microvm.restore_absent_scratch && self.microvm.memory_capacity.is_none() && self.microvm.snapshot_block_identity.is_none() && self.microvm.snapshot_generation_id.is_none() && self.microvm.snapshot_scratch_restore_mode.is_none() && self.microvm.microvm_control_console.is_none() && !self.microvm.microvm_control_auth_stdin, - "--network-profile, --net-tap, --mount, --mount-aggregate, --microvm-sandbox-block, --microvm-workload-identity, --microvm-lifecycle, --microvm-control-console, --microvm-control-auth-stdin, --restore-processors, --restore-memory, --memory-capacity, snapshot block policy, and microVM network policy require a microVM machine" + "--network-profile, --net-tap, --mount, --mount-aggregate, --microvm-sandbox-block, --microvm-workload-identity, --microvm-lifecycle, --microvm-control-console, --microvm-control-auth-stdin, --restore-processors, --restore-memory, --restore-absent-scratch, --memory-capacity, snapshot block policy, and microVM network policy require a microVM machine" ); return Ok(()); } @@ -889,6 +898,13 @@ impl Options { ); } } + // Clap's `requires` does not hold when an option that conflicts with + // --restore-snapshot, such as --kernel, is present, so a cold boot + // would otherwise ignore the declaration. + anyhow::ensure!( + self.restore_snapshot.is_some() || !self.microvm.restore_absent_scratch, + "--restore-absent-scratch requires --restore-snapshot" + ); if self.restore_snapshot.is_some() { anyhow::ensure!( self.microvm.microvm_workload_identity.is_none(), @@ -1576,6 +1592,60 @@ mod tests { assert!(unaligned.validate_microvm_options().is_err()); } + #[cfg(guest_arch = "x86_64")] + #[test] + fn test_microvm_restore_absent_scratch_requires_a_microvm_restore() { + let restore = Options::try_parse_from([ + "openvmm", + "--machine", + "microvm", + "--restore-snapshot", + "snapshot", + "--restore-absent-scratch", + ]) + .unwrap(); + restore.validate_microvm_options().unwrap(); + assert!(restore.microvm.restore_absent_scratch); + + // A cold boot has no captured scratch to declare absent. + assert!( + Options::try_parse_from([ + "openvmm", + "--machine", + "microvm", + "--restore-absent-scratch", + ]) + .is_err() + ); + // Clap accepts it when --kernel, which conflicts with --restore-snapshot, + // lifts the requirement, so the validation refuses it. + let cold_boot = Options::try_parse_from([ + "openvmm", + "--machine", + "microvm", + "--kernel", + "vmlinux", + "--restore-absent-scratch", + ]) + .unwrap(); + assert_eq!( + cold_boot + .validate_microvm_options() + .unwrap_err() + .to_string(), + "--restore-absent-scratch requires --restore-snapshot" + ); + // Nor does a standard machine. + let standard = Options::try_parse_from([ + "openvmm", + "--restore-snapshot", + "snapshot", + "--restore-absent-scratch", + ]) + .unwrap(); + assert!(standard.validate_microvm_options().is_err()); + } + #[cfg(guest_arch = "x86_64")] #[test] fn test_microvm_sandbox_block_parser_and_validation() { diff --git a/openvmm/openvmm_entry/src/microvm/config.rs b/openvmm/openvmm_entry/src/microvm/config.rs index 4da8607220f..7a10f11926f 100644 --- a/openvmm/openvmm_entry/src/microvm/config.rs +++ b/openvmm/openvmm_entry/src/microvm/config.rs @@ -44,6 +44,7 @@ use openvmm_defs::config::Config; use openvmm_defs::config::DeviceVtl; use openvmm_defs::config::LoadMode; use openvmm_defs::microvm::MachineProfile; +use openvmm_defs::microvm::MicrovmSandboxBlockRole; use openvmm_defs::microvm::build_microvm_command_line; use openvmm_defs::microvm::build_microvm_control_command_line; use pal_async::DefaultDriver; @@ -367,7 +368,8 @@ impl<'a> MicrovmConfigBuilder<'a> { Ok(virtio_console_backend) } - /// Adds the fixed-role sandbox block devices. + /// Adds the fixed-role sandbox block devices, with a platform restore's + /// absent fresh scratch. pub(crate) async fn add_sandbox_blocks( &self, storage: &mut StorageBuilder, @@ -392,9 +394,15 @@ impl<'a> MicrovmConfigBuilder<'a> { &disk.kind, disk.read_only, opt.microvm.snapshot_destination.is_some() || opt.restore_snapshot.is_some(), + self.restore + .distro_capacity + .filter(|_| block.role == MicrovmSandboxBlockRole::Distro), ) .await?; } + if let Some(geometry) = self.restore.absent_scratch { + storage.add_microvm_absent_scratch(geometry); + } Ok(()) } diff --git a/openvmm/openvmm_entry/src/microvm/restore.rs b/openvmm/openvmm_entry/src/microvm/restore.rs index 1adcdebed9c..e1d7c9ceb86 100644 --- a/openvmm/openvmm_entry/src/microvm/restore.rs +++ b/openvmm/openvmm_entry/src/microvm/restore.rs @@ -11,6 +11,7 @@ use crate::Options; use crate::cli_args; use crate::cli_args::DiskCliKind; use crate::cli_args::microvm::MachineProfileCli; +use crate::storage_builder::microvm::MicrovmSandboxBlockGeometry; use anyhow::Context; use chipset_resources::microvm_time::RESTORE_ENTROPY_LEN; use chipset_resources::microvm_time::RestoreMemoryRange; @@ -19,6 +20,7 @@ use chipset_resources::microvm_time::RestoreTimeRecord; use net_backend_resources::egress::EgressPolicy; use openvmm_defs::config::DeviceVtl; use openvmm_defs::microvm::MicrovmNetworkConfig; +use openvmm_defs::microvm::MicrovmSandboxBlockRole; use openvmm_defs::time_abi::RestoreTimeInput; use openvmm_defs::time_abi::SnapshotCpuProfile; use openvmm_defs::time_abi::SnapshotTimeContract; @@ -106,6 +108,12 @@ pub(crate) struct MicrovmRestore { pub(crate) memory_ranges: Vec, /// Private copy of a paired scratch image, kept alive for the VM lifetime. pub(crate) private_scratch_dir: Option, + /// The captured geometry of a platform snapshot's `distro` block, which + /// the restore presents over an image that may be shorter. + pub(crate) distro_capacity: Option, + /// The captured geometry of a platform snapshot's fresh scratch, which + /// `--restore-absent-scratch` attaches with no file. + pub(crate) absent_scratch: Option, } impl MicrovmRestore { @@ -189,12 +197,17 @@ pub(crate) fn restore_packet_base( /// restore-time inputs of the microVM configuration. /// /// This may adjust `opt`: the snapshot selects the RAM size, a paired scratch -/// image is replaced by a private copy, and restore gates require entropy. +/// image is replaced by a private copy, and restore gates require entropy. A +/// platform snapshot's `distro` block keeps its captured capacity, whatever +/// the length of the image that the restore attaches to it, and +/// `--restore-absent-scratch` attaches its fresh scratch with no file. pub(crate) fn prepare_restore( opt: &mut Options, restore_snapshot: Option<&OpenedSnapshot>, ) -> anyhow::Result { let mut private_scratch_dir = None; + let mut distro_capacity = None; + let mut absent_scratch = None; let mut restore_gate_required = false; let restore_memory_target_requested = opt.microvm.restore_memory.is_some(); let mut restore_memory_ranges = Vec::new(); @@ -262,65 +275,64 @@ pub(crate) fn prepare_restore( "restore-time memory overrides are not allowed" ); opt.memory.size = Some(vmm_cli::MemorySize(restore_memory_size)); - if !contract.microvm_sandbox_blocks.is_empty() { - let scratch = contract - .microvm_sandbox_blocks - .last() - .filter(|block| block.role == "scratch") - .context("microVM snapshot is missing its scratch contract")?; - if scratch.artifact == openvmm_helpers::snapshot::format::SCRATCH_FILE_NAME { - anyhow::ensure!( - !opt.microvm.microvm_sandbox_block.iter().any(|block| { - block.role == openvmm_defs::microvm::MicrovmSandboxBlockRole::Scratch - }), - "paired snapshot restore supplies scratch.img; do not pass a scratch block" - ); - let source = snapshot - .open_paired_scratch_file()? - .context("paired snapshot is missing scratch.img")?; - let restore_mode = if scratch.restore_mode.is_empty() { - openvmm_helpers::snapshot::microvm::SNAPSHOT_SCRATCH_RESTORE_PRIVATE_COPY - } else { - scratch.restore_mode.as_str() - }; - let (private_path, temp_dir) = match restore_mode { - openvmm_helpers::snapshot::microvm::SNAPSHOT_SCRATCH_RESTORE_DIRECT_CLAIMED => { - anyhow::ensure!( - manifest.restore_policy - == openvmm_helpers::snapshot::format::SNAPSHOT_RESTORE_POLICY_RESUME, - "direct-claimed scratch requires a resume snapshot" - ); - let parent = snapshot_dir - .parent() - .filter(|parent| !parent.as_os_str().is_empty()) - .unwrap_or(Path::new(".")); - let temp_dir = tempfile::Builder::new() - .prefix(".openvmm-claimed-scratch-") - .tempdir_in(parent) - .context("failed to create claimed restore scratch directory")?; - let private_path = temp_dir - .path() - .join(openvmm_helpers::snapshot::format::SCRATCH_FILE_NAME); - openvmm_helpers::snapshot::restore::link_claimed_paired_scratch_file( - &source, - &private_path, - scratch, - )?; - (private_path, Some(temp_dir)) - } - mode => { - let parent = snapshot_dir - .parent() - .filter(|parent| !parent.as_os_str().is_empty()) - .unwrap_or(Path::new(".")); - let temp_dir = tempfile::Builder::new() - .prefix(".openvmm-private-scratch-") - .tempdir_in(parent) - .context("failed to create private restore scratch directory")?; - let private_path = temp_dir - .path() - .join(openvmm_helpers::snapshot::format::SCRATCH_FILE_NAME); - match mode { + let blocks = plan_sandbox_block_restore( + &manifest.snapshot_tier, + &contract.microvm_sandbox_blocks, + opt.microvm + .microvm_sandbox_block + .iter() + .any(|block| block.role == MicrovmSandboxBlockRole::Scratch), + opt.microvm.restore_absent_scratch, + )?; + distro_capacity = blocks.distro_capacity; + absent_scratch = blocks.absent_scratch; + if let Some(scratch) = blocks.paired_scratch { + let source = snapshot + .open_paired_scratch_file()? + .context("paired snapshot is missing scratch.img")?; + let restore_mode = if scratch.restore_mode.is_empty() { + openvmm_helpers::snapshot::microvm::SNAPSHOT_SCRATCH_RESTORE_PRIVATE_COPY + } else { + scratch.restore_mode.as_str() + }; + let (private_path, temp_dir) = match restore_mode { + openvmm_helpers::snapshot::microvm::SNAPSHOT_SCRATCH_RESTORE_DIRECT_CLAIMED => { + anyhow::ensure!( + manifest.restore_policy + == openvmm_helpers::snapshot::format::SNAPSHOT_RESTORE_POLICY_RESUME, + "direct-claimed scratch requires a resume snapshot" + ); + let parent = snapshot_dir + .parent() + .filter(|parent| !parent.as_os_str().is_empty()) + .unwrap_or(Path::new(".")); + let temp_dir = tempfile::Builder::new() + .prefix(".openvmm-claimed-scratch-") + .tempdir_in(parent) + .context("failed to create claimed restore scratch directory")?; + let private_path = temp_dir + .path() + .join(openvmm_helpers::snapshot::format::SCRATCH_FILE_NAME); + openvmm_helpers::snapshot::restore::link_claimed_paired_scratch_file( + &source, + &private_path, + scratch, + )?; + (private_path, Some(temp_dir)) + } + mode => { + let parent = snapshot_dir + .parent() + .filter(|parent| !parent.as_os_str().is_empty()) + .unwrap_or(Path::new(".")); + let temp_dir = tempfile::Builder::new() + .prefix(".openvmm-private-scratch-") + .tempdir_in(parent) + .context("failed to create private restore scratch directory")?; + let private_path = temp_dir + .path() + .join(openvmm_helpers::snapshot::format::SCRATCH_FILE_NAME); + match mode { openvmm_helpers::snapshot::microvm::SNAPSHOT_SCRATCH_RESTORE_PRIVATE_COPY => { openvmm_helpers::snapshot::restore::copy_paired_scratch_file( &source, @@ -339,40 +351,32 @@ pub(crate) fn prepare_restore( "snapshot scratch restore mode '{mode}' is unsupported" ), } - (private_path, Some(temp_dir)) - } - }; - opt.microvm - .microvm_sandbox_block - .push(cli_args::microvm::MicrovmSandboxBlockCli { - role: openvmm_defs::microvm::MicrovmSandboxBlockRole::Scratch, - disk: cli_args::DiskCli { - vtl: DeviceVtl::Vtl0, - kind: DiskCliKind::File { - path: private_path, - create_with_len: None, - direct: false, - }, - read_only: false, - is_dvd: false, - underhill: None, - pcie_port: None, - serial: None, - controller: None, - nsid: None, - lun: None, - relay: None, + (private_path, Some(temp_dir)) + } + }; + opt.microvm + .microvm_sandbox_block + .push(cli_args::microvm::MicrovmSandboxBlockCli { + role: MicrovmSandboxBlockRole::Scratch, + disk: cli_args::DiskCli { + vtl: DeviceVtl::Vtl0, + kind: DiskCliKind::File { + path: private_path, + create_with_len: None, + direct: false, }, - }); - private_scratch_dir = temp_dir; - } else { - anyhow::ensure!( - opt.microvm.microvm_sandbox_block.iter().any(|block| { - block.role == openvmm_defs::microvm::MicrovmSandboxBlockRole::Scratch - }), - "fresh-scratch snapshot restore requires a scratch block" - ); - } + read_only: false, + is_dvd: false, + underhill: None, + pcie_port: None, + serial: None, + controller: None, + nsid: None, + lun: None, + relay: None, + }, + }); + private_scratch_dir = temp_dir; } Some(contract.clone()) } else { @@ -384,6 +388,81 @@ pub(crate) fn prepare_restore( memory_target_requested: restore_memory_target_requested, memory_ranges: restore_memory_ranges, private_scratch_dir, + distro_capacity, + absent_scratch, + }) +} + +/// How a restore attaches the sandbox blocks of a snapshot. +#[derive(Debug, Default, PartialEq, Eq)] +struct SandboxBlockRestore<'a> { + /// The paired scratch, whose `scratch.img` the restore attaches. + paired_scratch: Option<&'a SnapshotMicrovmSandboxBlock>, + /// The captured geometry of a platform snapshot's `distro` block, which + /// the restore presents over an image that may be shorter. + distro_capacity: Option, + /// The captured geometry of a platform snapshot's fresh scratch, which the + /// restore attaches with no file. + absent_scratch: Option, +} + +/// Plans how a restore attaches `blocks`, the sandbox blocks of a snapshot of +/// tier `snapshot_tier`, given whether the caller passed a scratch block and +/// whether it declared the scratch absent. +/// +/// A paired snapshot supplies its own scratch. A fresh-scratch snapshot, the +/// platform tier's, takes the caller's, or attaches the scratch with no file +/// when the caller declares it absent; no other scratch may be absent. A +/// platform restore also presents the captured capacity of its `distro` block +/// whatever the image's length; other tiers keep exact lengths. +fn plan_sandbox_block_restore<'a>( + snapshot_tier: &str, + blocks: &'a [SnapshotMicrovmSandboxBlock], + scratch_block: bool, + absent_scratch: bool, +) -> anyhow::Result> { + const ABSENT_SCRATCH_REQUIRES_PLATFORM: &str = + "--restore-absent-scratch requires the fresh scratch of a platform snapshot"; + if blocks.is_empty() { + anyhow::ensure!(!absent_scratch, ABSENT_SCRATCH_REQUIRES_PLATFORM); + return Ok(SandboxBlockRestore::default()); + } + let scratch = blocks + .last() + .filter(|block| block.role == MicrovmSandboxBlockRole::Scratch.as_str()) + .context("microVM snapshot is missing its scratch contract")?; + let platform = snapshot_tier == openvmm_helpers::snapshot::format::SNAPSHOT_TIER_PLATFORM; + let paired_scratch = (scratch.artifact == openvmm_helpers::snapshot::format::SCRATCH_FILE_NAME) + .then_some(scratch); + anyhow::ensure!( + !absent_scratch || (platform && paired_scratch.is_none()), + ABSENT_SCRATCH_REQUIRES_PLATFORM + ); + if paired_scratch.is_some() { + anyhow::ensure!( + !scratch_block, + "paired snapshot restore supplies scratch.img; do not pass a scratch block" + ); + } else if absent_scratch { + anyhow::ensure!( + !scratch_block, + "--restore-absent-scratch attaches the scratch block with no file; do not pass a scratch block" + ); + } else { + anyhow::ensure!( + scratch_block, + "fresh-scratch snapshot restore requires a scratch block or --restore-absent-scratch" + ); + } + let distro_capacity = blocks + .iter() + .find(|block| block.role == MicrovmSandboxBlockRole::Distro.as_str()) + .filter(|_| platform) + .map(MicrovmSandboxBlockGeometry::of); + Ok(SandboxBlockRestore { + paired_scratch, + distro_capacity, + absent_scratch: absent_scratch.then(|| MicrovmSandboxBlockGeometry::of(scratch)), }) } @@ -631,6 +710,154 @@ pub(crate) mod tests { entropy[16] = 0xa5; assert_eq!(microvm_generation_id(&entropy), [0x5a; 16]); } + + /// Returns the contract of a sandbox block of `role` and `length` bytes, + /// with a platform snapshot's identity. + fn sandbox_block(role: &str, length: u64) -> SnapshotMicrovmSandboxBlock { + let scratch = role == MicrovmSandboxBlockRole::Scratch.as_str(); + SnapshotMicrovmSandboxBlock { + role: role.to_owned(), + read_only: !scratch, + length, + identity_kind: if scratch { "fresh" } else { "unbound" }.to_owned(), + identity: Vec::new(), + artifact: String::new(), + logical_block_size: 512, + physical_block_size: 4096, + restore_mode: String::new(), + } + } + + #[test] + fn only_a_platform_restore_presents_the_distro_capacity() { + use openvmm_helpers::snapshot::format::SCRATCH_FILE_NAME; + use openvmm_helpers::snapshot::format::SNAPSHOT_TIER_PLATFORM; + use openvmm_helpers::snapshot::format::SNAPSHOT_TIER_WORKLOAD_START; + + let blocks = [ + sandbox_block("distro", 1 << 30), + sandbox_block("scratch", 1 << 20), + ]; + assert_eq!( + plan_sandbox_block_restore(SNAPSHOT_TIER_PLATFORM, &blocks, true, false).unwrap(), + SandboxBlockRestore { + paired_scratch: None, + distro_capacity: Some(MicrovmSandboxBlockGeometry { + length: 1 << 30, + logical_block_size: 512, + physical_block_size: 4096, + }), + absent_scratch: None, + } + ); + // The fresh scratch of a platform snapshot needs a file unless it is + // declared absent. + let err = + plan_sandbox_block_restore(SNAPSHOT_TIER_PLATFORM, &blocks, false, false).unwrap_err(); + assert_eq!( + err.to_string(), + "fresh-scratch snapshot restore requires a scratch block or --restore-absent-scratch" + ); + + // A paired snapshot of another tier keeps the exact lengths and + // supplies its own scratch. + let mut paired = blocks.clone(); + paired[1].artifact = SCRATCH_FILE_NAME.to_owned(); + assert_eq!( + plan_sandbox_block_restore(SNAPSHOT_TIER_WORKLOAD_START, &paired, false, false) + .unwrap(), + SandboxBlockRestore { + paired_scratch: Some(&paired[1]), + distro_capacity: None, + absent_scratch: None, + } + ); + let err = plan_sandbox_block_restore(SNAPSHOT_TIER_WORKLOAD_START, &paired, true, false) + .unwrap_err(); + assert_eq!( + err.to_string(), + "paired snapshot restore supplies scratch.img; do not pass a scratch block" + ); + + // A snapshot without sandbox blocks has nothing to attach. + assert_eq!( + plan_sandbox_block_restore("", &[], false, false).unwrap(), + SandboxBlockRestore::default() + ); + let err = plan_sandbox_block_restore(SNAPSHOT_TIER_PLATFORM, &blocks[..1], true, false) + .unwrap_err(); + assert_eq!( + err.to_string(), + "microVM snapshot is missing its scratch contract" + ); + } + + #[test] + fn only_a_platform_restore_attaches_an_absent_scratch() { + use openvmm_helpers::snapshot::format::SCRATCH_FILE_NAME; + use openvmm_helpers::snapshot::format::SNAPSHOT_TIER_INSTANCE_CHECKPOINT; + use openvmm_helpers::snapshot::format::SNAPSHOT_TIER_PLATFORM; + use openvmm_helpers::snapshot::format::SNAPSHOT_TIER_WORKLOAD_START; + + let blocks = [ + sandbox_block("distro", 1 << 30), + sandbox_block("scratch", 1 << 20), + ]; + // A platform restore attaches its fresh scratch at the captured + // geometry, with no file. + assert_eq!( + plan_sandbox_block_restore(SNAPSHOT_TIER_PLATFORM, &blocks, false, true).unwrap(), + SandboxBlockRestore { + paired_scratch: None, + distro_capacity: Some(MicrovmSandboxBlockGeometry::of(&blocks[0])), + absent_scratch: Some(MicrovmSandboxBlockGeometry { + length: 1 << 20, + logical_block_size: 512, + physical_block_size: 4096, + }), + } + ); + // An absent scratch has no file. + let err = + plan_sandbox_block_restore(SNAPSHOT_TIER_PLATFORM, &blocks, true, true).unwrap_err(); + assert_eq!( + err.to_string(), + "--restore-absent-scratch attaches the scratch block with no file; do not pass a scratch block" + ); + + // Outside a platform restore, the scratch is never absent: not for a + // paired snapshot, with or without a scratch block, and not for a + // snapshot without sandbox blocks. + let mut paired = blocks.clone(); + paired[1].artifact = SCRATCH_FILE_NAME.to_owned(); + for tier in [ + SNAPSHOT_TIER_WORKLOAD_START, + SNAPSHOT_TIER_INSTANCE_CHECKPOINT, + ] { + for scratch_block in [false, true] { + let err = + plan_sandbox_block_restore(tier, &paired, scratch_block, true).unwrap_err(); + assert_eq!( + err.to_string(), + "--restore-absent-scratch requires the fresh scratch of a platform snapshot" + ); + } + } + // The fresh scratch of a manifest of another tier, which the manifest + // validation rejects, is not absent either. + let err = plan_sandbox_block_restore(SNAPSHOT_TIER_WORKLOAD_START, &blocks, false, true) + .unwrap_err(); + assert_eq!( + err.to_string(), + "--restore-absent-scratch requires the fresh scratch of a platform snapshot" + ); + let err = plan_sandbox_block_restore("", &[], false, true).unwrap_err(); + assert_eq!( + err.to_string(), + "--restore-absent-scratch requires the fresh scratch of a platform snapshot" + ); + } + fn time_abi_restore(capture_generation: u32) -> MicrovmRestore { let mut contract: SnapshotMachineContract = mesh::payload::decode(&[]).unwrap(); contract.time = Some(SnapshotTimeContract { @@ -663,6 +890,8 @@ pub(crate) mod tests { length: 0x4000_0000, }], private_scratch_dir: None, + distro_capacity: None, + absent_scratch: None, } } diff --git a/openvmm/openvmm_entry/src/storage_builder/microvm.rs b/openvmm/openvmm_entry/src/storage_builder/microvm.rs index 5b8f6087ae5..0cd67dbbc46 100644 --- a/openvmm/openvmm_entry/src/storage_builder/microvm.rs +++ b/openvmm/openvmm_entry/src/storage_builder/microvm.rs @@ -18,6 +18,7 @@ use openvmm_defs::microvm::MicrovmSandboxBlockConfig; use openvmm_defs::microvm::MicrovmSandboxBlockRole; use std::time::Duration; use vm_resource::Resource; +use vm_resource::kind::DiskHandleKind; /// The fixed role of a microVM sandbox block device. pub(super) struct SandboxBlock { @@ -25,13 +26,89 @@ pub(super) struct SandboxBlock { snapshot_source: Option, } +/// The geometry of a microVM sandbox block: its length and block sizes, in +/// bytes. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) struct MicrovmSandboxBlockGeometry { + pub(crate) length: u64, + pub(crate) logical_block_size: u32, + pub(crate) physical_block_size: u32, +} + +impl MicrovmSandboxBlockGeometry { + /// Returns the geometry that a snapshot recorded for `block`. + pub(crate) fn of( + block: &openvmm_helpers::snapshot::microvm::SnapshotMicrovmSandboxBlock, + ) -> Self { + Self { + length: block.length, + logical_block_size: block.logical_block_size, + physical_block_size: block.physical_block_size, + } + } +} + +/// Checks that an image of geometry `image` fits `capacity`, the captured +/// geometry of a platform snapshot's `role` block: it must have the same block +/// sizes and must not be longer. +fn check_platform_capacity( + role: MicrovmSandboxBlockRole, + image: MicrovmSandboxBlockGeometry, + capacity: MicrovmSandboxBlockGeometry, +) -> anyhow::Result<()> { + anyhow::ensure!( + image.logical_block_size == capacity.logical_block_size + && image.physical_block_size == capacity.physical_block_size, + "microVM {} image has logical and physical block sizes {} and {}, but the platform snapshot captured {} and {}", + role.as_str(), + image.logical_block_size, + image.physical_block_size, + capacity.logical_block_size, + capacity.physical_block_size, + ); + anyhow::ensure!( + image.length <= capacity.length, + "microVM {} image is {} bytes, longer than the platform snapshot's {}-byte capacity", + role.as_str(), + image.length, + capacity.length, + ); + Ok(()) +} + pub(crate) struct MicrovmSandboxBlockSource { pub(crate) role: MicrovmSandboxBlockRole, pub(crate) read_only: bool, pub(crate) length: u64, pub(crate) logical_block_size: u32, pub(crate) physical_block_size: u32, - pub(crate) file: std::fs::File, + /// The block's file, or `None` for the absent fresh scratch of a platform + /// restore. + pub(crate) file: Option, +} + +impl MicrovmSandboxBlockSource { + /// Returns the block's file, which every block but an absent scratch has. + fn file(&self) -> anyhow::Result<&std::fs::File> { + self.file + .as_ref() + .with_context(|| format!("microVM {} block has no file", self.role.as_str())) + } +} + +/// Returns a disk resource of `geometry` that reads `disk` for the sectors +/// that it has, and zeros past its end or everywhere without one, and that +/// refuses writes. +fn zero_fill_disk( + disk: Option>, + geometry: MicrovmSandboxBlockGeometry, +) -> Resource { + Resource::new(disk_backend_resources::ZeroFillDiskHandle { + disk, + sector_count: geometry.length / u64::from(geometry.logical_block_size), + sector_size: geometry.logical_block_size, + physical_sector_size: geometry.physical_block_size, + }) } pub(crate) fn capture_snapshot_block_contract( @@ -48,7 +125,7 @@ pub(crate) fn capture_snapshot_block_contract( && scratch_policy == chipset_resources::microvm::MicrovmSnapshotScratchPolicy::Paired { - source.file.sync_all().with_context(|| { + source.file()?.sync_all().with_context(|| { format!("failed to flush microVM {} block", source.role.as_str()) })?; } @@ -62,7 +139,7 @@ pub(crate) fn capture_snapshot_block_contract( SnapshotBlockIdentityCli::Sha256 => ( openvmm_helpers::snapshot::microvm::SNAPSHOT_BLOCK_IDENTITY_SHA256, openvmm_helpers::snapshot::fs::file_sha256( - &source.file, + source.file()?, source.length, &format!("microVM {} block", source.role.as_str()), )?, @@ -125,7 +202,7 @@ pub(crate) fn restore_snapshot_block_contract( let identity = match saved.identity_kind.as_str() { openvmm_helpers::snapshot::microvm::SNAPSHOT_BLOCK_IDENTITY_SHA256 => { openvmm_helpers::snapshot::fs::file_sha256( - &source.file, + source.file()?, source.length, &format!("microVM {} block", source.role.as_str()), )? @@ -164,13 +241,25 @@ pub(crate) fn restore_snapshot_block_contract( impl StorageBuilder { /// Adds a fixed-role microVM sandbox block device. + /// + /// `capacity`, the captured geometry of a platform snapshot's `distro` + /// block at its restore, makes the device present that geometry over a + /// file that may be shorter: reads past the file's end return zeros, and + /// nothing resizes, pads, or writes the file. The file must have the + /// captured block sizes and must not be longer. Only a snapshot-capable + /// block has a capacity. pub async fn add_microvm_sandbox_block( &mut self, role: MicrovmSandboxBlockRole, kind: &DiskCliKind, read_only: bool, snapshot_capable: bool, + capacity: Option, ) -> anyhow::Result<()> { + assert!( + snapshot_capable || capacity.is_none(), + "only a snapshot-capable microVM sandbox block has a captured capacity" + ); if !snapshot_capable { self.vtl0_virtio_blk_disks.push(VirtioBlkDisk { disk: disk_open(kind, read_only).await?, @@ -264,6 +353,17 @@ impl StorageBuilder { physical_block_size >= logical_block_size && physical_block_size.is_power_of_two(), "microVM sandbox block has unsupported physical block geometry" ); + let image = MicrovmSandboxBlockGeometry { + length, + logical_block_size, + physical_block_size, + }; + let presented = if let Some(capacity) = capacity { + check_platform_capacity(role, image, capacity)?; + capacity + } else { + image + }; let disk_file = file .try_clone() .context("failed to duplicate microVM sandbox block handle")?; @@ -271,6 +371,11 @@ impl StorageBuilder { let disk = Resource::new(disk_backend_resources::BlockDeviceDiskHandle { file: disk_file }); #[cfg(not(target_os = "linux"))] let disk = Resource::new(disk_backend_resources::FileDiskHandle(disk_file)); + let disk = if presented.length != image.length { + zero_fill_disk(Some(disk), presented) + } else { + disk + }; let disk = if let Some(delay_ms) = delay_ms { Resource::new(disk_backend_resources::DelayDiskHandle { disk, @@ -288,16 +393,42 @@ impl StorageBuilder { snapshot_source: Some(MicrovmSandboxBlockSource { role, read_only, - length, - logical_block_size, - physical_block_size, - file, + length: presented.length, + logical_block_size: presented.logical_block_size, + physical_block_size: presented.physical_block_size, + file: Some(file), }), }), }); Ok(()) } + /// Adds the fresh scratch of a platform restore with no file, at its + /// captured `geometry`. + /// + /// The device stays writable, as the guest negotiated it at the template's + /// boot and as the restore contract records it, but it has nowhere to keep + /// data: reads return zeros, and writes fail with an I/O error. + pub fn add_microvm_absent_scratch(&mut self, geometry: MicrovmSandboxBlockGeometry) { + let role = MicrovmSandboxBlockRole::Scratch; + self.vtl0_virtio_blk_disks.push(VirtioBlkDisk { + disk: zero_fill_disk(None, geometry), + read_only: role.is_read_only(), + serial: None, + microvm: Some(SandboxBlock { + role, + snapshot_source: Some(MicrovmSandboxBlockSource { + role, + read_only: role.is_read_only(), + length: geometry.length, + logical_block_size: geometry.logical_block_size, + physical_block_size: geometry.physical_block_size, + file: None, + }), + }), + }); + } + /// Adds the sandbox block devices of a microVM at their fixed virtio-mmio /// slots, in role order. pub(super) fn build_microvm_sandbox_blocks( @@ -336,3 +467,202 @@ impl StorageBuilder { Ok(()) } } + +#[cfg(test)] +mod tests { + use super::*; + use std::path::Path; + use test_with_tracing::test; + + const MIB: u64 = 1024 * 1024; + + fn geometry( + length: u64, + logical_block_size: u32, + physical_block_size: u32, + ) -> MicrovmSandboxBlockGeometry { + MicrovmSandboxBlockGeometry { + length, + logical_block_size, + physical_block_size, + } + } + + /// Attaches `path` as the read-only `distro` block of a snapshot-capable + /// microVM, with `capacity`, and returns the attached block's disk + /// resource kind and presented geometry. + fn attach_distro( + path: &Path, + capacity: Option, + ) -> anyhow::Result<(String, MicrovmSandboxBlockGeometry)> { + let mut storage = StorageBuilder::new(None); + futures::executor::block_on(storage.add_microvm_sandbox_block( + MicrovmSandboxBlockRole::Distro, + &DiskCliKind::File { + path: path.to_owned(), + create_with_len: None, + direct: false, + }, + true, + true, + capacity, + ))?; + let [block] = storage.vtl0_virtio_blk_disks.as_slice() else { + panic!("one block is attached"); + }; + assert!(block.read_only); + let source = block + .microvm + .as_ref() + .and_then(|block| block.snapshot_source.as_ref()) + .expect("a snapshot-capable block has a source"); + Ok(( + block.disk.id().to_owned(), + geometry( + source.length, + source.logical_block_size, + source.physical_block_size, + ), + )) + } + + #[test] + fn platform_capacity_admits_no_longer_images_with_its_block_sizes() { + let capacity = geometry(MIB, 512, 4096); + for length in [512, 4096, MIB - 512, MIB] { + check_platform_capacity( + MicrovmSandboxBlockRole::Distro, + geometry(length, 512, 4096), + capacity, + ) + .unwrap(); + } + let err = check_platform_capacity( + MicrovmSandboxBlockRole::Distro, + geometry(MIB + 512, 512, 4096), + capacity, + ) + .unwrap_err(); + assert_eq!( + err.to_string(), + "microVM distro image is 1049088 bytes, longer than the platform snapshot's 1048576-byte capacity" + ); + for image in [ + geometry(MIB, 512, 512), + geometry(MIB, 512, 8192), + geometry(MIB, 4096, 4096), + ] { + let err = check_platform_capacity(MicrovmSandboxBlockRole::Distro, image, capacity) + .unwrap_err(); + assert!( + err.to_string() + .starts_with("microVM distro image has logical and physical block sizes"), + "{err:#}" + ); + } + } + + #[test] + fn platform_distro_presents_its_capacity_over_a_shorter_image() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("distro.img"); + let contents = vec![0x3c; 64 * 1024]; + std::fs::write(&path, &contents).unwrap(); + let file_kind = if cfg!(target_os = "linux") { + "block" + } else { + "file" + }; + + // Without a capacity, the device presents the image's own geometry. + let (kind, image) = attach_distro(&path, None).unwrap(); + assert_eq!(kind, file_kind); + assert_eq!(image.length, 64 * 1024); + assert_eq!(image.logical_block_size, 512); + + // A capacity of the image's length attaches it as it is. + assert_eq!( + attach_distro(&path, Some(image)).unwrap(), + (file_kind.to_owned(), image) + ); + + // A larger capacity is presented, and its tail reads as zeros. + let capacity = MicrovmSandboxBlockGeometry { + length: MIB, + ..image + }; + assert_eq!( + attach_distro(&path, Some(capacity)).unwrap(), + ("zerofill".to_owned(), capacity) + ); + + // A longer image, and one with other block sizes, are refused. + let smaller = MicrovmSandboxBlockGeometry { + length: 32 * 1024, + ..image + }; + let err = attach_distro(&path, Some(smaller)).unwrap_err(); + assert!(err.to_string().contains("longer than"), "{err:#}"); + let other_physical = MicrovmSandboxBlockGeometry { + physical_block_size: image.physical_block_size * 2, + ..capacity + }; + let err = attach_distro(&path, Some(other_physical)).unwrap_err(); + assert!(err.to_string().contains("block sizes"), "{err:#}"); + + // Nothing resized, padded, or wrote the image. + assert_eq!(std::fs::read(&path).unwrap(), contents); + } + + #[test] + fn absent_scratch_is_writable_and_has_no_file() { + let captured = geometry(MIB, 512, 4096); + let mut storage = StorageBuilder::new(None); + storage.add_microvm_absent_scratch(captured); + let [block] = storage.vtl0_virtio_blk_disks.as_slice() else { + panic!("one block is attached"); + }; + // The guest negotiated the scratch as writable, and a zero-fill disk + // without a backing disk serves it. + assert!(!block.read_only); + assert_eq!(block.disk.id(), "zerofill"); + let sandbox = block.microvm.as_ref().unwrap(); + assert_eq!(sandbox.role, MicrovmSandboxBlockRole::Scratch); + let source = sandbox.snapshot_source.as_ref().unwrap(); + assert!(source.file.is_none()); + + // Its restore contract is the captured fresh scratch's. + let saved = openvmm_helpers::snapshot::microvm::SnapshotMicrovmSandboxBlock { + role: "scratch".to_owned(), + read_only: false, + length: MIB, + identity_kind: "fresh".to_owned(), + identity: Vec::new(), + artifact: String::new(), + logical_block_size: 512, + physical_block_size: 4096, + restore_mode: String::new(), + }; + let sources = std::slice::from_ref(source); + assert_eq!( + restore_snapshot_block_contract( + sources, + chipset_resources::microvm::MicrovmSnapshotScratchPolicy::Fresh, + std::slice::from_ref(&saved), + ) + .unwrap(), + [saved] + ); + // A paired capture, which no restored microVM can take, fails instead + // of reading a file that it does not have. + let err = capture_snapshot_block_contract( + sources, + chipset_resources::microvm::MicrovmSnapshotScratchPolicy::Paired, + SnapshotBlockIdentityCli::Sha256, + None, + "", + ) + .unwrap_err(); + assert_eq!(err.to_string(), "microVM scratch block has no file"); + } +} diff --git a/openvmm/openvmm_entry/src/vm_controller/microvm.rs b/openvmm/openvmm_entry/src/vm_controller/microvm.rs index 2bbab49bbfc..2c107892e19 100644 --- a/openvmm/openvmm_entry/src/vm_controller/microvm.rs +++ b/openvmm/openvmm_entry/src/vm_controller/microvm.rs @@ -405,7 +405,7 @@ impl VmController { .find(|source| { source.role == openvmm_defs::microvm::MicrovmSandboxBlockRole::Scratch }) - .map(|source| &source.file) + .and_then(|source| source.file.as_ref()) .context("paired snapshot lost its scratch backing handle") }) .transpose()?; diff --git a/openvmm/openvmm_resources/Cargo.toml b/openvmm/openvmm_resources/Cargo.toml index 9dbf01da5ef..b977e8f6cae 100644 --- a/openvmm/openvmm_resources/Cargo.toml +++ b/openvmm/openvmm_resources/Cargo.toml @@ -42,6 +42,7 @@ disk_file.workspace = true disk_layered.workspace = true disk_prwrap.workspace = true disk_vhd1.workspace = true +disk_zerofill.workspace = true disklayer_vhdx.workspace = true disklayer_ram.workspace = true disklayer_sqlite = { workspace = true, optional = true } diff --git a/openvmm/openvmm_resources/src/lib.rs b/openvmm/openvmm_resources/src/lib.rs index ef7825e2fc1..b3f881fbe19 100644 --- a/openvmm/openvmm_resources/src/lib.rs +++ b/openvmm/openvmm_resources/src/lib.rs @@ -86,6 +86,7 @@ vm_resource::register_static_resolvers! { disk_vhdmp::VhdmpDiskResolver, #[cfg(feature = "disk_blob")] disk_blob::resolver::BlobDiskResolver, + disk_zerofill::resolver::ZeroFillDiskResolver, // Disk Layers disklayer_ram::resolver::RamDiskLayerResolver, diff --git a/vm/devices/storage/disk_backend/src/lib.rs b/vm/devices/storage/disk_backend/src/lib.rs index 4fbfd250b6b..15ab13820cc 100644 --- a/vm/devices/storage/disk_backend/src/lib.rs +++ b/vm/devices/storage/disk_backend/src/lib.rs @@ -69,6 +69,7 @@ //! | `DelayDisk` | `disk_delay` | Injected I/O latency wrapper | //! | `DiskWithReservations` | `disk_prwrap` | In-memory PR emulation wrapper | //! | `LayeredDisk` | `disk_layered` | Layered disk with per-sector presence | +//! | `ZeroFillDisk` | `disk_zerofill` | Fixed geometry over a shorter or absent disk: zeros past its end, no writes | #![forbid(unsafe_code)] diff --git a/vm/devices/storage/disk_backend_resources/src/lib.rs b/vm/devices/storage/disk_backend_resources/src/lib.rs index 3277fcca377..7067cc1831e 100644 --- a/vm/devices/storage/disk_backend_resources/src/lib.rs +++ b/vm/devices/storage/disk_backend_resources/src/lib.rs @@ -61,6 +61,25 @@ impl ResourceId for DelayDiskHandle { const ID: &'static str = "delay"; } +/// Disk handle for a disk of fixed geometry that reads zeros past the end of +/// its backing disk, or everywhere without one, and refuses writes. +#[derive(MeshPayload)] +pub struct ZeroFillDiskHandle { + /// The backing disk, with the disk's sector sizes and at most its sector + /// count, or `None` for a disk that reads zeros everywhere. + pub disk: Option>, + /// The number of sectors that the disk presents. + pub sector_count: u64, + /// The logical sector size, in bytes. + pub sector_size: u32, + /// The physical sector size, in bytes. + pub physical_sector_size: u32, +} + +impl ResourceId for ZeroFillDiskHandle { + const ID: &'static str = "zerofill"; +} + /// Disk handle for a fixed VHD1 disk. #[derive(MeshPayload)] pub struct FixedVhd1DiskHandle(pub std::fs::File); diff --git a/vm/devices/storage/disk_zerofill/Cargo.toml b/vm/devices/storage/disk_zerofill/Cargo.toml new file mode 100644 index 00000000000..d0da20f4647 --- /dev/null +++ b/vm/devices/storage/disk_zerofill/Cargo.toml @@ -0,0 +1,27 @@ +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. + +[package] +name = "disk_zerofill" +edition.workspace = true +rust-version.workspace = true + +[dependencies] +disk_backend.workspace = true +disk_backend_resources.workspace = true +guestmem.workspace = true +inspect.workspace = true +scsi_buffers.workspace = true +vm_resource.workspace = true + +anyhow.workspace = true +async-trait.workspace = true +thiserror.workspace = true + +[dev-dependencies] +disklayer_ram.workspace = true +pal_async.workspace = true +storage_tests.workspace = true + +[lints] +workspace = true diff --git a/vm/devices/storage/disk_zerofill/src/lib.rs b/vm/devices/storage/disk_zerofill/src/lib.rs new file mode 100644 index 00000000000..469d1c7bd01 --- /dev/null +++ b/vm/devices/storage/disk_zerofill/src/lib.rs @@ -0,0 +1,453 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +//! A disk of fixed geometry that reads zeros past the end of its backing disk +//! and refuses writes. +//! +//! [`ZeroFillDisk`] presents a fixed sector count over an optional backing +//! [`Disk`] with the same sector sizes and no more sectors. Reads of the +//! sectors that the backing disk has go to it. Reads of the sectors past its +//! end, or of every sector of a disk without one, return zeros, including the +//! tail of a request that crosses the end. Writes fail without reaching the +//! backing disk, so the disk never resizes, pads, or writes it, and keeps no +//! written data. +//! +//! A microVM platform restore uses it to present the captured capacity of its +//! `distro` block over a shorter image, and to attach a fresh scratch block +//! that has no file. + +#![forbid(unsafe_code)] + +pub mod resolver; + +use disk_backend::Disk; +use disk_backend::DiskError; +use disk_backend::DiskIo; +use disk_backend::UnmapBehavior; +use guestmem::MemoryWrite; +use inspect::Inspect; +use scsi_buffers::RequestBuffers; +use thiserror::Error; + +/// A disk of fixed geometry that reads zeros past the end of its backing disk +/// and refuses writes. +#[derive(Inspect)] +pub struct ZeroFillDisk { + backing: Option, + backing_sector_count: u64, + sector_count: u64, + sector_size: u32, + #[inspect(skip)] + sector_shift: u32, + physical_sector_size: u32, + read_only: bool, +} + +/// An error returned by [`ZeroFillDisk::new`]. +#[derive(Debug, Error)] +pub enum NewZeroFillDiskError { + /// The sector size is not a power of two of at least 512 bytes. + #[error("invalid sector size {0}")] + InvalidSectorSize(u32), + /// The physical sector size is not a power of two of at least the sector + /// size. + #[error("invalid physical sector size {0}")] + InvalidPhysicalSectorSize(u32), + /// The backing disk's sector sizes differ from the disk's. + #[error( + "backing disk sector sizes {backing_sector_size}/{backing_physical_sector_size} do not match {sector_size}/{physical_sector_size}" + )] + SectorSizeMismatch { + /// The disk's sector size. + sector_size: u32, + /// The disk's physical sector size. + physical_sector_size: u32, + /// The backing disk's sector size. + backing_sector_size: u32, + /// The backing disk's physical sector size. + backing_physical_sector_size: u32, + }, + /// The backing disk has more sectors than the disk. + #[error("backing disk has {backing_sector_count} sectors, more than the disk's {sector_count}")] + BackingTooLong { + /// The disk's sector count. + sector_count: u64, + /// The backing disk's sector count. + backing_sector_count: u64, + }, +} + +impl ZeroFillDisk { + /// Returns a disk of `sector_count` sectors of `sector_size` bytes, with + /// physical sectors of `physical_sector_size` bytes, that reads the + /// sectors that `backing` has from it and zeros past them. + /// + /// `backing` must have the same sector sizes and at most `sector_count` + /// sectors. Its sector count is sampled here: a backing disk that resizes + /// later does not change which sectors read as zeros, and this disk never + /// resizes. `read_only` selects how writes fail: with + /// [`DiskError::ReadOnly`] for a read-only disk, and with + /// [`DiskError::Io`] for a writable one, which the guest negotiated as + /// writable but which has nowhere to keep its data. + pub fn new( + backing: Option, + sector_count: u64, + sector_size: u32, + physical_sector_size: u32, + read_only: bool, + ) -> Result { + if sector_size < 512 || !sector_size.is_power_of_two() { + return Err(NewZeroFillDiskError::InvalidSectorSize(sector_size)); + } + if physical_sector_size < sector_size || !physical_sector_size.is_power_of_two() { + return Err(NewZeroFillDiskError::InvalidPhysicalSectorSize( + physical_sector_size, + )); + } + let backing_sector_count = if let Some(backing) = &backing { + if backing.sector_size() != sector_size + || backing.physical_sector_size() != physical_sector_size + { + return Err(NewZeroFillDiskError::SectorSizeMismatch { + sector_size, + physical_sector_size, + backing_sector_size: backing.sector_size(), + backing_physical_sector_size: backing.physical_sector_size(), + }); + } + let backing_sector_count = backing.sector_count(); + if backing_sector_count > sector_count { + return Err(NewZeroFillDiskError::BackingTooLong { + sector_count, + backing_sector_count, + }); + } + backing_sector_count + } else { + 0 + }; + Ok(Self { + backing, + backing_sector_count, + sector_count, + sector_size, + sector_shift: sector_size.trailing_zeros(), + physical_sector_size, + read_only, + }) + } + + /// Fails a request of `count` sectors at `sector` that does not lie inside + /// the disk. + fn check_range(&self, sector: u64, count: u64) -> Result<(), DiskError> { + if sector + .checked_add(count) + .is_none_or(|end| end > self.sector_count) + { + return Err(DiskError::IllegalBlock); + } + Ok(()) + } + + /// Returns the error of a write that lies inside the disk. + fn refused_write(&self) -> DiskError { + if self.read_only { + DiskError::ReadOnly + } else { + DiskError::Io(std::io::Error::new( + std::io::ErrorKind::Unsupported, + "zero-fill disk refuses writes", + )) + } + } +} + +impl DiskIo for ZeroFillDisk { + fn disk_type(&self) -> &str { + "zerofill" + } + + fn sector_count(&self) -> u64 { + self.sector_count + } + + fn sector_size(&self) -> u32 { + self.sector_size + } + + fn disk_id(&self) -> Option<[u8; 16]> { + self.backing.as_ref().and_then(Disk::disk_id) + } + + fn physical_sector_size(&self) -> u32 { + self.physical_sector_size + } + + fn is_fua_respected(&self) -> bool { + false + } + + fn is_read_only(&self) -> bool { + self.read_only + } + + async fn read_vectored( + &self, + buffers: &RequestBuffers<'_>, + sector: u64, + ) -> Result<(), DiskError> { + let count = (buffers.len() >> self.sector_shift) as u64; + self.check_range(sector, count)?; + // The backing disk serves the sectors that it has, and the rest of the + // request reads as zeros. + let backed = self.backing_sector_count.saturating_sub(sector).min(count); + let backed_len = (backed << self.sector_shift) as usize; + if let Some(backing) = &self.backing + && backed != 0 + { + backing + .read_vectored(&buffers.subrange(0, backed_len), sector) + .await?; + } + let zero_len = buffers.len() - backed_len; + if zero_len != 0 { + buffers + .subrange(backed_len, zero_len) + .writer() + .zero(zero_len)?; + } + Ok(()) + } + + async fn write_vectored( + &self, + buffers: &RequestBuffers<'_>, + sector: u64, + _fua: bool, + ) -> Result<(), DiskError> { + self.check_range(sector, (buffers.len() >> self.sector_shift) as u64)?; + Err(self.refused_write()) + } + + /// Succeeds: no write ever succeeds, so no data waits to be flushed. + async fn sync_cache(&self) -> Result<(), DiskError> { + Ok(()) + } + + /// Changes nothing: the disk ignores unmaps, as its unmap behavior + /// reports. + async fn unmap( + &self, + sector: u64, + count: u64, + _block_level_only: bool, + ) -> Result<(), DiskError> { + self.check_range(sector, count) + } + + fn unmap_behavior(&self) -> UnmapBehavior { + UnmapBehavior::Ignored + } +} + +#[cfg(test)] +mod tests { + use super::NewZeroFillDiskError; + use super::ZeroFillDisk; + use disk_backend::Disk; + use disk_backend::DiskError; + use disk_backend::DiskIo; + use guestmem::GuestMemory; + use pal_async::async_test; + use scsi_buffers::OwnedRequestBuffers; + + const SECTOR_SIZE: usize = 512; + + /// Returns the contents of a `count`-sector disk whose sector `n` is full + /// of the byte `n + 1`. + fn pattern(count: usize) -> Vec { + (0..count) + .flat_map(|sector| [sector as u8 + 1; SECTOR_SIZE]) + .collect() + } + + async fn write(disk: &Disk, sector: u64, data: &[u8]) -> Result<(), DiskError> { + let mem = GuestMemory::allocate(data.len()); + mem.write_at(0, data).unwrap(); + disk.write_vectored( + &OwnedRequestBuffers::linear(0, data.len(), false).buffer(&mem), + sector, + false, + ) + .await + } + + /// Reads `count` sectors at `sector` into a buffer that was full of ones. + async fn read(disk: &Disk, sector: u64, count: usize) -> Vec { + let mem = GuestMemory::allocate(count * SECTOR_SIZE); + mem.fill_at(0, 0xff, count * SECTOR_SIZE).unwrap(); + disk.read_vectored( + &OwnedRequestBuffers::linear(0, count * SECTOR_SIZE, true).buffer(&mem), + sector, + ) + .await + .unwrap(); + let mut data = vec![0; count * SECTOR_SIZE]; + mem.read_at(0, &mut data).unwrap(); + data + } + + /// Returns a writable RAM disk of `count` sectors with the contents of + /// [`pattern`]. + async fn backing(count: usize) -> Disk { + let disk = disklayer_ram::ram_disk((count * SECTOR_SIZE) as u64, false).unwrap(); + write(&disk, 0, &pattern(count)).await.unwrap(); + disk + } + + fn zero_fill(backing: Option, sector_count: u64, read_only: bool) -> Disk { + Disk::new( + ZeroFillDisk::new( + backing, + sector_count, + SECTOR_SIZE as u32, + SECTOR_SIZE as u32, + read_only, + ) + .unwrap(), + ) + .unwrap() + } + + #[async_test] + async fn reads_the_backing_disk_then_zeros() { + let disk = zero_fill(Some(backing(4).await), 8, true); + let image = pattern(4); + let zeros = |count| vec![0; count * SECTOR_SIZE]; + assert_eq!(disk.sector_count(), 8); + + // Inside the backing disk. + assert_eq!(read(&disk, 0, 4).await, image); + assert_eq!(read(&disk, 3, 1).await, image[3 * SECTOR_SIZE..]); + // Across its end. + assert_eq!( + read(&disk, 2, 4).await, + [&image[2 * SECTOR_SIZE..], &zeros(2)].concat() + ); + assert_eq!(read(&disk, 0, 8).await, [image, zeros(4)].concat()); + // Past it, up to the disk's last sector. + assert_eq!(read(&disk, 4, 4).await, zeros(4)); + assert_eq!(read(&disk, 7, 1).await, zeros(1)); + } + + #[async_test] + async fn a_disk_without_backing_reads_zeros() { + let disk = zero_fill(None, 8, false); + assert_eq!(disk.sector_count(), 8); + assert_eq!(disk.sector_size(), SECTOR_SIZE as u32); + assert!(!disk.is_read_only()); + assert_eq!(disk.disk_id(), None); + assert_eq!(read(&disk, 0, 8).await, vec![0; 8 * SECTOR_SIZE]); + } + + #[async_test] + async fn writes_are_refused_without_reaching_the_backing_disk() { + let image = pattern(4); + + // A read-only disk refuses writes inside and across the backing disk. + let inner = backing(4).await; + let disk = zero_fill(Some(inner.clone()), 8, true); + for sector in [0, 3, 6] { + assert!(matches!( + write(&disk, sector, &[0x55; 2 * SECTOR_SIZE]).await, + Err(DiskError::ReadOnly) + )); + } + assert_eq!(read(&inner, 0, 4).await, image); + assert_eq!( + read(&disk, 0, 8).await, + [&image[..], &[0; 4 * SECTOR_SIZE]].concat() + ); + + // A writable disk fails them as I/O errors, and keeps nothing. + let inner = backing(4).await; + let disk = zero_fill(Some(inner.clone()), 8, false); + for sector in [0, 3, 6] { + assert!(matches!( + write(&disk, sector, &[0x55; 2 * SECTOR_SIZE]).await, + Err(DiskError::Io(_)) + )); + } + assert_eq!(read(&inner, 0, 4).await, image); + assert_eq!( + read(&disk, 0, 8).await, + [&image[..], &[0; 4 * SECTOR_SIZE]].concat() + ); + + let disk = zero_fill(None, 8, false); + assert!(matches!( + write(&disk, 0, &[0x55; SECTOR_SIZE]).await, + Err(DiskError::Io(_)) + )); + assert_eq!(read(&disk, 0, 1).await, vec![0; SECTOR_SIZE]); + // Nothing waits to be flushed, and unmaps change nothing. + disk.sync_cache().await.unwrap(); + disk.unmap(0, 8, false).await.unwrap(); + assert_eq!(read(&disk, 0, 8).await, vec![0; 8 * SECTOR_SIZE]); + // The backend ignores the unmaps that it could receive, as `Disk` does. + let backend = ZeroFillDisk::new(Some(inner.clone()), 8, 512, 512, true).unwrap(); + DiskIo::unmap(&backend, 0, 8, false).await.unwrap(); + assert!(matches!( + DiskIo::unmap(&backend, 4, 5, false).await, + Err(DiskError::IllegalBlock) + )); + assert_eq!(read(&inner, 0, 4).await, image); + } + + #[async_test] + async fn sector_range_conformance() { + let disk = zero_fill(Some(backing(4).await), 8, true); + storage_tests::sector_range::test_disk_sector_range_conformance(&disk).await; + let disk = zero_fill(None, 8, false); + storage_tests::sector_range::test_disk_sector_range_conformance(&disk).await; + } + + #[async_test] + async fn new_rejects_inconsistent_geometry() { + // A backing disk as long as the disk is accepted, and a longer one is + // not. + ZeroFillDisk::new(Some(backing(8).await), 8, 512, 512, true).unwrap(); + assert!(matches!( + ZeroFillDisk::new(Some(backing(8).await), 7, 512, 512, true), + Err(NewZeroFillDiskError::BackingTooLong { + sector_count: 7, + backing_sector_count: 8, + }) + )); + // The sector sizes must match the backing disk's. + assert!(matches!( + ZeroFillDisk::new(Some(backing(8).await), 8, 512, 4096, true), + Err(NewZeroFillDiskError::SectorSizeMismatch { .. }) + )); + assert!(matches!( + ZeroFillDisk::new(Some(backing(8).await), 8, 4096, 4096, true), + Err(NewZeroFillDiskError::SectorSizeMismatch { .. }) + )); + // And they must be valid. + for sector_size in [0, 256, 768] { + assert!(matches!( + ZeroFillDisk::new(None, 8, sector_size, 4096, false), + Err(NewZeroFillDiskError::InvalidSectorSize(_)) + )); + } + for physical_sector_size in [256, 1536] { + assert!(matches!( + ZeroFillDisk::new(None, 8, 512, physical_sector_size, false), + Err(NewZeroFillDiskError::InvalidPhysicalSectorSize(_)) + )); + } + let disk = ZeroFillDisk::new(None, 8, 512, 4096, false).unwrap(); + let disk = Disk::new(disk).unwrap(); + assert_eq!(disk.physical_sector_size(), 4096); + } +} diff --git a/vm/devices/storage/disk_zerofill/src/resolver.rs b/vm/devices/storage/disk_zerofill/src/resolver.rs new file mode 100644 index 00000000000..ebc08148d16 --- /dev/null +++ b/vm/devices/storage/disk_zerofill/src/resolver.rs @@ -0,0 +1,44 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +//! The resolver of [`ZeroFillDiskHandle`]. + +use crate::ZeroFillDisk; +use async_trait::async_trait; +use disk_backend::resolve::ResolveDiskParameters; +use disk_backend::resolve::ResolvedDisk; +use disk_backend_resources::ZeroFillDiskHandle; +use vm_resource::AsyncResolveResource; +use vm_resource::ResourceResolver; +use vm_resource::declare_static_async_resolver; +use vm_resource::kind::DiskHandleKind; + +/// A resolver of [`ZeroFillDiskHandle`] to a [`ZeroFillDisk`]. +pub struct ZeroFillDiskResolver; +declare_static_async_resolver!(ZeroFillDiskResolver, (DiskHandleKind, ZeroFillDiskHandle)); + +#[async_trait] +impl AsyncResolveResource for ZeroFillDiskResolver { + type Output = ResolvedDisk; + type Error = anyhow::Error; + + async fn resolve( + &self, + resolver: &ResourceResolver, + rsrc: ZeroFillDiskHandle, + input: ResolveDiskParameters<'_>, + ) -> Result { + let backing = match rsrc.disk { + Some(disk) => Some(resolver.resolve(disk, input).await?.0), + None => None, + }; + let disk = ZeroFillDisk::new( + backing, + rsrc.sector_count, + rsrc.sector_size, + rsrc.physical_sector_size, + input.read_only, + )?; + Ok(ResolvedDisk::new(disk)?) + } +}