From c7ac476b43671577d896a6e3133349cda3a1585d Mon Sep 17 00:00:00 2001 From: Pedro Henrique Penna Date: Sun, 25 Oct 2026 09:19:19 -0500 Subject: [PATCH 1/3] disk_zerofill: present a fixed geometry over a shorter or absent disk A microVM platform snapshot is a template that each clone restores with its own image in place of the template's distro placeholder, and with its own scratch device. A disk presents its backing file's length, and restore requires each block's captured length exactly, so every clone's image must be exactly as long as the placeholder, and a clone that keeps its upper layer in RAM still needs a scratch file of the captured length, which it never writes. Add ZeroFillDisk, a disk that presents a fixed sector count and fixed sector sizes 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: with ReadOnly for a read-only disk, and with an I/O error for a writable one, which a guest may have negotiated as writable but which has nowhere to keep data. Unlike a RAM layer over the backing disk, the disk never resizes, pads, or writes it, and keeps no written data. Flushes succeed, since no write ever completes, and the disk ignores unmaps, which the Disk wrapper then completes without calling it. Its sector count never changes, so it does not forward wait_resize. ZeroFillDiskHandle describes it in disk_backend_resources, and openvmm_resources registers its resolver, which resolves the backing disk with the same access and rejects a backing disk whose sector sizes differ or that is longer. Unit tests read within, across, and past a backing disk's end and from a disk without one, check that writes fail without reaching the backing disk, run the shared sector-range conformance suites, and check the geometry validation. The storage pages of the Guide list the new decorator. See microsoft/nvx#856. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- Cargo.lock | 19 + Cargo.toml | 1 + .../reference/architecture/devices/storage.md | 2 +- Guide/src/reference/backends/storage.md | 1 + openvmm/openvmm_resources/Cargo.toml | 1 + openvmm/openvmm_resources/src/lib.rs | 1 + vm/devices/storage/disk_backend/src/lib.rs | 1 + .../storage/disk_backend_resources/src/lib.rs | 19 + vm/devices/storage/disk_zerofill/Cargo.toml | 27 ++ vm/devices/storage/disk_zerofill/src/lib.rs | 453 ++++++++++++++++++ .../storage/disk_zerofill/src/resolver.rs | 44 ++ 11 files changed, 568 insertions(+), 1 deletion(-) create mode 100644 vm/devices/storage/disk_zerofill/Cargo.toml create mode 100644 vm/devices/storage/disk_zerofill/src/lib.rs create mode 100644 vm/devices/storage/disk_zerofill/src/resolver.rs 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/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/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)?) + } +} From 857ff9645e5dbe3f2e3cc1fa07a23d25ed7f981b Mon Sep 17 00:00:00 2001 From: Pedro Henrique Penna Date: Sun, 25 Oct 2026 09:19:20 -0500 Subject: [PATCH 2/3] microVM: present a platform distro's capacity over a shorter image A platform snapshot is a template that each clone restores with its own image in the distro slot. The template's distro placeholder fixes the capacity that the guest learned at the template's boot, but a disk's size is its file's length, and restore compares each block's length and block sizes with the captured ones exactly. Every clone's image therefore had to be exactly as long as the placeholder. Present the placeholder's capacity at every platform restore instead. prepare_restore records the captured geometry of a platform snapshot's distro block, and the storage builder checks the clone's image against it: the image must have the captured logical and physical block sizes, and must not be longer. A shorter image is attached through a ZeroFillDisk of the captured length, so reads inside the image go to it, and reads past its end, including the tail of a request that crosses it, return zeros. The image is opened read-only, as before, and nothing resizes, pads, or writes it. The device's capacity is fixed when the VM is built, before any vCPU runs, and the block's source records it, so the restore contract still compares the captured geometry exactly. An image of the captured length is attached as it is. Other tiers, the other blocks, and cold boots keep the exact rules. Move the scratch rules of prepare_restore into plan_sandbox_block_restore, which also selects the distro capacity, so that unit tests cover them without a snapshot. Unit tests cover the capacity check; attaching shorter, equal, longer, and mismatched images to a platform distro block, which leaves the image unchanged; and the restore plans of platform and paired snapshots. The CLI reference and the snapshot guide describe the capacity. See microsoft/nvx#856. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- Guide/src/reference/openvmm/management/cli.md | 7 +- Guide/src/user_guide/openvmm/snapshots.md | 7 +- openvmm/openvmm_entry/src/microvm/config.rs | 4 + openvmm/openvmm_entry/src/microvm/restore.rs | 314 ++++++++++++------ .../src/storage_builder/microvm.rs | 236 ++++++++++++- 5 files changed, 470 insertions(+), 98 deletions(-) diff --git a/Guide/src/reference/openvmm/management/cli.md b/Guide/src/reference/openvmm/management/cli.md index d9a15d2e961..f5667ae2a93 100644 --- a/Guide/src/reference/openvmm/management/cli.md +++ b/Guide/src/reference/openvmm/management/cli.md @@ -450,7 +450,12 @@ 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. diff --git a/Guide/src/user_guide/openvmm/snapshots.md b/Guide/src/user_guide/openvmm/snapshots.md index 3971d084e53..0941bc66495 100644 --- a/Guide/src/user_guide/openvmm/snapshots.md +++ b/Guide/src/user_guide/openvmm/snapshots.md @@ -184,7 +184,12 @@ 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. 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/microvm/config.rs b/openvmm/openvmm_entry/src/microvm/config.rs index 4da8607220f..90a23e636df 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; @@ -392,6 +393,9 @@ 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?; } diff --git a/openvmm/openvmm_entry/src/microvm/restore.rs b/openvmm/openvmm_entry/src/microvm/restore.rs index 1adcdebed9c..1e915468527 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,9 @@ 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, } impl MicrovmRestore { @@ -189,12 +194,15 @@ 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. 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 restore_gate_required = false; let restore_memory_target_requested = opt.microvm.restore_memory.is_some(); let mut restore_memory_ranges = Vec::new(); @@ -262,65 +270,62 @@ 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), + )?; + distro_capacity = blocks.distro_capacity; + 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 +344,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 +381,60 @@ pub(crate) fn prepare_restore( memory_target_requested: restore_memory_target_requested, memory_ranges: restore_memory_ranges, private_scratch_dir, + distro_capacity, + }) +} + +/// 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, +} + +/// Plans how a restore attaches `blocks`, the sandbox blocks of a snapshot of +/// tier `snapshot_tier`, given whether the caller passed a scratch block. +/// +/// A paired snapshot supplies its own scratch, and a fresh-scratch snapshot, +/// the platform tier's, takes the caller's. 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, +) -> anyhow::Result> { + if blocks.is_empty() { + 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 paired_scratch = (scratch.artifact == openvmm_helpers::snapshot::format::SCRATCH_FILE_NAME) + .then_some(scratch); + if paired_scratch.is_some() { + anyhow::ensure!( + !scratch_block, + "paired snapshot restore supplies scratch.img; do not pass a scratch block" + ); + } else { + anyhow::ensure!( + scratch_block, + "fresh-scratch snapshot restore requires a scratch block" + ); + } + let distro_capacity = blocks + .iter() + .find(|block| block.role == MicrovmSandboxBlockRole::Distro.as_str()) + .filter(|_| snapshot_tier == openvmm_helpers::snapshot::format::SNAPSHOT_TIER_PLATFORM) + .map(MicrovmSandboxBlockGeometry::of); + Ok(SandboxBlockRestore { + paired_scratch, + distro_capacity, }) } @@ -631,6 +682,82 @@ 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).unwrap(), + SandboxBlockRestore { + paired_scratch: None, + distro_capacity: Some(MicrovmSandboxBlockGeometry { + length: 1 << 30, + logical_block_size: 512, + physical_block_size: 4096, + }), + } + ); + // The fresh scratch of a platform snapshot still needs a file. + let err = plan_sandbox_block_restore(SNAPSHOT_TIER_PLATFORM, &blocks, false).unwrap_err(); + assert_eq!( + err.to_string(), + "fresh-scratch snapshot restore requires a scratch block" + ); + + // 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).unwrap(), + SandboxBlockRestore { + paired_scratch: Some(&paired[1]), + distro_capacity: None, + } + ); + let err = + plan_sandbox_block_restore(SNAPSHOT_TIER_WORKLOAD_START, &paired, true).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).unwrap(), + SandboxBlockRestore::default() + ); + let err = + plan_sandbox_block_restore(SNAPSHOT_TIER_PLATFORM, &blocks[..1], true).unwrap_err(); + assert_eq!( + err.to_string(), + "microVM snapshot is missing its scratch contract" + ); + } fn time_abi_restore(capture_generation: u32) -> MicrovmRestore { let mut contract: SnapshotMachineContract = mesh::payload::decode(&[]).unwrap(); contract.time = Some(SnapshotTimeContract { @@ -663,6 +790,7 @@ pub(crate) mod tests { length: 0x4000_0000, }], private_scratch_dir: None, + distro_capacity: None, } } diff --git a/openvmm/openvmm_entry/src/storage_builder/microvm.rs b/openvmm/openvmm_entry/src/storage_builder/microvm.rs index 5b8f6087ae5..a28eb07f1d5 100644 --- a/openvmm/openvmm_entry/src/storage_builder/microvm.rs +++ b/openvmm/openvmm_entry/src/storage_builder/microvm.rs @@ -25,6 +25,56 @@ 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, @@ -164,13 +214,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 +326,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 +344,16 @@ 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 { + Resource::new(disk_backend_resources::ZeroFillDiskHandle { + disk: Some(disk), + sector_count: presented.length / u64::from(presented.logical_block_size), + sector_size: presented.logical_block_size, + physical_sector_size: presented.physical_block_size, + }) + } else { + disk + }; let disk = if let Some(delay_ms) = delay_ms { Resource::new(disk_backend_resources::DelayDiskHandle { disk, @@ -288,9 +371,9 @@ impl StorageBuilder { snapshot_source: Some(MicrovmSandboxBlockSource { role, read_only, - length, - logical_block_size, - physical_block_size, + length: presented.length, + logical_block_size: presented.logical_block_size, + physical_block_size: presented.physical_block_size, file, }), }), @@ -336,3 +419,150 @@ 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); + } +} From a12d9167fe103bd01f2d09521f715971776c5f5b Mon Sep 17 00:00:00 2001 From: Pedro Henrique Penna Date: Sun, 25 Oct 2026 09:19:20 -0500 Subject: [PATCH 3/3] microVM: let a platform restore attach an absent fresh scratch A platform snapshot captures its scratch device before the guest mounts it, as a fresh scratch: the manifest records its geometry, and each restore must supply a new scratch file of exactly that length. The guest negotiated the device as writable at the template's boot, and restore compares each block's access with the captured one, so the device must stay, and stay writable. A clone that keeps its upper layer in RAM never writes the scratch, but still needed a scratch file of the captured length. Add --restore-absent-scratch, with which a platform restore declares its fresh scratch absent. OpenVMM then attaches the scratch device with no file, at the length and block sizes that the manifest records, through a writable ZeroFillDisk without a backing disk: reads return zeros, and every write fails with an I/O error, so no write is dropped or kept in host memory. The block's source records that geometry and has no file, so the restore contract still compares the captured access, length, and block sizes exactly. Only a fresh scratch, the platform tier's, may be absent. Before the VM is built, the restore plan refuses the option for a paired snapshot and for one without sandbox blocks, and together with a scratch block. The microVM validation refuses it without --restore-snapshot, since clap's requirement does not hold once a cold boot passes --kernel, which conflicts with --restore-snapshot. A scratch file, when given, keeps the exact captured length, and a fresh-scratch restore with neither a scratch block nor the option is still refused. A block source's file is now optional. Capture, which a restored microVM cannot take, fails instead of reading a file that an absent scratch does not have. Unit tests cover the restore plan with an absent scratch for each tier, with and without a scratch block, the attached device and its restore contract, and the CLI rules, including a cold boot with --kernel. The CLI reference, the snapshot guide, and the snapshot format describe the option. See microsoft/nvx#856. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- Guide/src/dev_guide/snapshot_format.md | 5 +- Guide/src/reference/openvmm/management/cli.md | 15 +- Guide/src/user_guide/openvmm/snapshots.md | 9 +- openvmm/openvmm_entry/src/cli_args/microvm.rs | 72 ++++++++- openvmm/openvmm_entry/src/microvm/config.rs | 6 +- openvmm/openvmm_entry/src/microvm/restore.rs | 137 +++++++++++++++--- .../src/storage_builder/microvm.rs | 122 ++++++++++++++-- .../src/vm_controller/microvm.rs | 2 +- 8 files changed, 332 insertions(+), 36 deletions(-) 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/openvmm/management/cli.md b/Guide/src/reference/openvmm/management/cli.md index f5667ae2a93..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 @@ -458,7 +459,7 @@ describes the source definitions. 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 @@ -508,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 0941bc66495..c93975ec24f 100644 --- a/Guide/src/user_guide/openvmm/snapshots.md +++ b/Guide/src/user_guide/openvmm/snapshots.md @@ -189,7 +189,14 @@ identities. A platform restore also presents the captured capacity of its 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. An instance-checkpoint restore attempt atomically creates +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 90a23e636df..7a10f11926f 100644 --- a/openvmm/openvmm_entry/src/microvm/config.rs +++ b/openvmm/openvmm_entry/src/microvm/config.rs @@ -368,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, @@ -399,6 +400,9 @@ impl<'a> MicrovmConfigBuilder<'a> { ) .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 1e915468527..e1d7c9ceb86 100644 --- a/openvmm/openvmm_entry/src/microvm/restore.rs +++ b/openvmm/openvmm_entry/src/microvm/restore.rs @@ -111,6 +111,9 @@ pub(crate) struct MicrovmRestore { /// 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 { @@ -196,13 +199,15 @@ pub(crate) fn restore_packet_base( /// 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. A /// platform snapshot's `distro` block keeps its captured capacity, whatever -/// the length of the image that the restore attaches to it. +/// 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(); @@ -277,8 +282,10 @@ pub(crate) fn prepare_restore( .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()? @@ -382,6 +389,7 @@ pub(crate) fn prepare_restore( memory_ranges: restore_memory_ranges, private_scratch_dir, distro_capacity, + absent_scratch, }) } @@ -393,48 +401,68 @@ struct SandboxBlockRestore<'a> { /// 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. +/// 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, and a fresh-scratch snapshot, -/// the platform tier's, takes the caller's. A platform restore also presents -/// the captured capacity of its `distro` block whatever the image's length; -/// other tiers keep exact lengths. +/// 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" + "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(|_| snapshot_tier == openvmm_helpers::snapshot::format::SNAPSHOT_TIER_PLATFORM) + .filter(|_| platform) .map(MicrovmSandboxBlockGeometry::of); Ok(SandboxBlockRestore { paired_scratch, distro_capacity, + absent_scratch: absent_scratch.then(|| MicrovmSandboxBlockGeometry::of(scratch)), }) } @@ -711,7 +739,7 @@ pub(crate) mod tests { sandbox_block("scratch", 1 << 20), ]; assert_eq!( - plan_sandbox_block_restore(SNAPSHOT_TIER_PLATFORM, &blocks, true).unwrap(), + plan_sandbox_block_restore(SNAPSHOT_TIER_PLATFORM, &blocks, true, false).unwrap(), SandboxBlockRestore { paired_scratch: None, distro_capacity: Some(MicrovmSandboxBlockGeometry { @@ -719,13 +747,16 @@ pub(crate) mod tests { logical_block_size: 512, physical_block_size: 4096, }), + absent_scratch: None, } ); - // The fresh scratch of a platform snapshot still needs a file. - let err = plan_sandbox_block_restore(SNAPSHOT_TIER_PLATFORM, &blocks, false).unwrap_err(); + // 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" + "fresh-scratch snapshot restore requires a scratch block or --restore-absent-scratch" ); // A paired snapshot of another tier keeps the exact lengths and @@ -733,14 +764,16 @@ pub(crate) mod tests { 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).unwrap(), + 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).unwrap_err(); + 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" @@ -748,16 +781,83 @@ pub(crate) mod tests { // A snapshot without sandbox blocks has nothing to attach. assert_eq!( - plan_sandbox_block_restore("", &[], false).unwrap(), + plan_sandbox_block_restore("", &[], false, false).unwrap(), SandboxBlockRestore::default() ); - let err = - plan_sandbox_block_restore(SNAPSHOT_TIER_PLATFORM, &blocks[..1], true).unwrap_err(); + 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 { @@ -791,6 +891,7 @@ pub(crate) mod tests { }], 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 a28eb07f1d5..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 { @@ -81,7 +82,33 @@ pub(crate) struct MicrovmSandboxBlockSource { 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( @@ -98,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()) })?; } @@ -112,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()), )?, @@ -175,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()), )? @@ -345,12 +372,7 @@ impl StorageBuilder { #[cfg(not(target_os = "linux"))] let disk = Resource::new(disk_backend_resources::FileDiskHandle(disk_file)); let disk = if presented.length != image.length { - Resource::new(disk_backend_resources::ZeroFillDiskHandle { - disk: Some(disk), - sector_count: presented.length / u64::from(presented.logical_block_size), - sector_size: presented.logical_block_size, - physical_sector_size: presented.physical_block_size, - }) + zero_fill_disk(Some(disk), presented) } else { disk }; @@ -374,13 +396,39 @@ impl StorageBuilder { length: presented.length, logical_block_size: presented.logical_block_size, physical_block_size: presented.physical_block_size, - file, + 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( @@ -565,4 +613,56 @@ mod tests { // 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()?;