disk_backend/

lib.rs

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

//! The shared disk backend abstraction for OpenVMM storage.
//!
//! This crate defines [`Disk`] and the [`DiskIo`] trait, the central
//! interface between storage frontends (NVMe, SCSI/StorVSP, IDE) and disk
//! backends (host files, block devices, remote blobs, and more).
//!
//! # Architecture
//!
//! Every disk backend implements [`DiskIo`]. Frontends don't interact with
//! backends directly — they hold a [`Disk`], which wraps a type-erased
//! backend (`DynDisk`, an adapter around [`DiskIo`] that normalizes return
//! futures) behind an `Arc` for cheap, concurrent cloning. The `Disk`
//! wrapper caches immutable metadata (sector size, physical sector size,
//! disk ID, FUA support) at construction time and validates that sector
//! sizes are powers of two and at least 512 bytes.
//!
//! # I/O model
//!
//! All I/O is **async** and uses **scatter-gather** buffers via
//! [`RequestBuffers`]. Callers must pass
//! buffers that are an integral number of sectors.
//!
//! The key operations are:
//!
//! - [`DiskIo::read_vectored`] / [`DiskIo::write_vectored`] — async
//!   scatter-gather read and write. The `fua` parameter on writes requests
//!   Force Unit Access (write-through to stable storage). Whether FUA is
//!   actually respected depends on the backend — check
//!   [`DiskIo::is_fua_respected`].
//! - [`DiskIo::sync_cache`] — flush (equivalent to SCSI SYNCHRONIZE CACHE
//!   or NVMe FLUSH).
//! - [`DiskIo::unmap`] — trim / deallocate sectors. The
//!   [`DiskIo::unmap_behavior`] method reports whether unmapped sectors
//!   become zero, become indeterminate, or whether unmap is ignored
//!   entirely.
//! - [`DiskIo::eject`] — eject media (optical drives only). The default
//!   returns [`DiskError::UnsupportedEject`]. Eject is a media state change
//!   managed by the SCSI DVD layer, not by the backend.
//! - [`DiskIo::wait_resize`] — block until the disk's sector count changes.
//!   The default returns [`std::future::pending()`], meaning the backend
//!   never signals a resize. Only backends that can detect runtime capacity
//!   changes (e.g., `BlockDeviceDisk` via Linux uevent, `NvmeDisk` via AEN)
//!   should override this. Decorators and layered disks delegate to the
//!   inner backend.
//!
//! # Error model
//!
//! All I/O methods return [`DiskError`], which frontends translate into
//! protocol-specific errors (NVMe status codes, SCSI sense keys). The
//! variants cover out-of-range LBAs, I/O errors, medium errors with
//! sub-classification, guest memory access failures, read-only violations,
//! persistent reservation conflicts, and unsupported eject.
//!
//! # Available backends
//!
//! | Backend | Crate | Description |
//! |---------|-------|-------------|
//! | `FileDisk` | `disk_file` | Host file, cross-platform |
//! | `Vhd1Disk` | `disk_vhd1` | VHD1 fixed format |
//! | `VhdmpDisk` | `disk_vhdmp` | Windows vhdmp driver |
//! | `BlobDisk` | `disk_blob` | Read-only HTTP / Azure Blob |
//! | `BlockDeviceDisk` | `disk_blockdevice` | Linux block device (io_uring) |
//! | `NvmeDisk` | `disk_nvme` | Physical NVMe (user-mode driver) |
//! | `StripedDisk` | `disk_striped` | Striped across multiple disks |
//! | `CryptDisk` | `disk_crypt` | XTS-AES-256 encryption wrapper |
//! | `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 |

#![forbid(unsafe_code)]

pub mod pr;
pub mod resolve;
pub mod sync_wrapper;

use guestmem::AccessError;
use inspect::Inspect;
use scsi_buffers::RequestBuffers;
use stackfuture::StackFuture;
use std::fmt::Debug;
use std::future::Future;
use std::future::ready;
use std::pin::Pin;
use std::sync::Arc;
use thiserror::Error;

/// A disk operation error.
#[derive(Debug, Error)]
pub enum DiskError {
    /// The request failed due to a preempt and abort status.
    #[error("aborted command")]
    AbortDueToPreemptAndAbort,
    /// The LBA was out of range.
    #[error("illegal request")]
    IllegalBlock,
    /// The request failed due to invalid input.
    #[error("invalid input")]
    InvalidInput,
    /// The request failed due to an unrecovered IO error.
    #[error("io error")]
    Io(#[source] std::io::Error),
    /// The request failed due to a reportable medium error.
    #[error("medium error")]
    MediumError(#[source] std::io::Error, MediumErrorDetails),
    /// The request failed due to a failure to access the specified buffers.
    #[error("failed to access guest memory")]
    MemoryAccess(#[from] AccessError),
    /// The request failed because the disk is read-only.
    #[error("attempt to write to read-only disk/range")]
    ReadOnly,
    /// The request failed due to a persistent reservation conflict.
    #[error("reservation conflict")]
    ReservationConflict,
    /// The request failed because eject is not supported.
    #[error("unsupported eject")]
    UnsupportedEject,
}

/// Failure details for [`DiskError::MediumError`].
#[derive(Debug)]
pub enum MediumErrorDetails {
    /// The medium had an application tag check failure.
    ApplicationTagCheckFailed,
    /// The medium had a guard check failure.
    GuardCheckFailed,
    /// The medium had a reference tag check failure.
    ReferenceTagCheckFailed,
    /// The medium had an unrecovered read error.
    UnrecoveredReadError,
    /// The medium had a write fault.
    WriteFault,
}

/// Disk metadata and IO operations.
///
/// # Sector range validation
///
/// Sector numbers reaching a backend originate with the guest, so
/// implementations **must not panic** for any sector value, and must return
/// [`DiskError::IllegalBlock`] for requests that fall outside the disk.
/// Callers are *not* required to validate the range beforehand — they cannot
/// do so meaningfully, since [`DiskIo::sector_count`] may change at runtime,
/// so a range checked by a caller can be invalidated before the request is
/// issued. Only the backend can validate against its own state.
///
/// An implementation may delegate this to whatever it is layered on top of,
/// but only if the backing object's bounds coincide exactly with the disk's,
/// out-of-range operations fail rather than silently succeeding, and the
/// resulting error is mapped to [`DiskError::IllegalBlock`].
///
/// In exchange, implementations may rely on one guarantee from [`Disk`]: the
/// end byte offset of any request — that is, `(sector + count) * sector_size`
/// — is representable and no greater than [`i64::MAX`]. Sector arithmetic
/// therefore cannot overflow, and a backend that transforms the offset (adding
/// a header size, a chunk base, and so on) has 2^63 bytes of headroom in which
/// to do so. Note that this says nothing about how large the disk is, so it is
/// not a substitute for the range check above.
pub trait DiskIo: 'static + Send + Sync + Inspect {
    /// Returns the disk type name as a string.
    ///
    /// This is used for diagnostic purposes.
    fn disk_type(&self) -> &str;

    /// Returns the current sector count.
    ///
    /// For some backing stores, this may change at runtime. If it does, then
    /// the backing store must also implement [`DiskIo::wait_resize`].
    fn sector_count(&self) -> u64;

    /// Returns the logical sector size of the backing store.
    ///
    /// This must not change at runtime.
    fn sector_size(&self) -> u32;

    /// Optionally returns a 16-byte identifier for the disk, if there is a
    /// natural one for this backing store.
    ///
    /// This may be exposed to the guest as a unique disk identifier.
    /// This must not change at runtime.
    fn disk_id(&self) -> Option<[u8; 16]>;

    /// Returns the physical sector size of the backing store.
    ///
    /// This must not change at runtime.
    fn physical_sector_size(&self) -> u32;

    /// Returns true if the `fua` parameter to [`DiskIo::write_vectored`] is
    /// respected by the backing store by ensuring that the IO is immediately
    /// committed to disk.
    fn is_fua_respected(&self) -> bool;

    /// Returns true if the disk is read only.
    fn is_read_only(&self) -> bool;

    /// Unmap sectors from the layer.
    ///
    /// See the [trait documentation](DiskIo#sector-range-validation) for the
    /// requirements on out-of-range requests.
    fn unmap(
        &self,
        sector: u64,
        count: u64,
        block_level_only: bool,
    ) -> impl Future<Output = Result<(), DiskError>> + Send;

    /// Returns the behavior of the unmap operation.
    ///
    /// This tells callers what happens to the content of unmapped sectors:
    ///
    /// - [`UnmapBehavior::Zeroes`] — unmapped sectors read back as zero.
    /// - [`UnmapBehavior::Unspecified`] — content may or may not change, and
    ///   not necessarily to zero.
    /// - [`UnmapBehavior::Ignored`] — unmap is a no-op; content is unchanged.
    fn unmap_behavior(&self) -> UnmapBehavior;

    /// Returns the optimal granularity for unmaps, in sectors.
    fn optimal_unmap_sectors(&self) -> u32 {
        1
    }

    /// Optionally returns a trait object to issue persistent reservation
    /// requests.
    fn pr(&self) -> Option<&dyn pr::PersistentReservation> {
        None
    }

    /// Issues an asynchronous eject media operation to the disk.
    ///
    /// The default implementation returns [`DiskError::UnsupportedEject`].
    /// Eject is primarily a media state change managed by the SCSI DVD layer
    /// (`SimpleScsiDvd`), not by disk backends. Backends generally do not
    /// need to override this.
    fn eject(&self) -> impl Future<Output = Result<(), DiskError>> + Send {
        ready(Err(DiskError::UnsupportedEject))
    }

    /// Issues an asynchronous read-scatter operation to the disk.
    ///
    /// # Arguments
    /// * `buffers` - An object representing the data buffers into which the disk data will be transferred.
    /// * `sector` - The logical sector at which the read operation starts.
    fn read_vectored(
        &self,
        buffers: &RequestBuffers<'_>,
        sector: u64,
    ) -> impl Future<Output = Result<(), DiskError>> + Send;

    /// Issues an asynchronous write-gather operation to the disk.
    /// # Arguments
    /// * `buffers` - An object representing the data buffers containing the data to transfer to the disk.
    /// * `sector` - The logical sector at which the write operation starts.
    /// * `fua` - A flag indicates if FUA (force unit access) is requested.
    fn write_vectored(
        &self,
        buffers: &RequestBuffers<'_>,
        sector: u64,
        fua: bool,
    ) -> impl Future<Output = Result<(), DiskError>> + Send;

    /// Issues an asynchronous flush operation to the disk.
    fn sync_cache(&self) -> impl Future<Output = Result<(), DiskError>> + Send;

    /// Waits for the disk sector count to change from the specified value.
    ///
    /// Returns the new sector count once [`DiskIo::sector_count`] would return
    /// a value different from `sector_count`. Frontends use this to detect
    /// runtime capacity changes and notify the guest (NVMe via AEN, SCSI via
    /// UNIT_ATTENTION).
    ///
    /// The default implementation returns [`std::future::pending()`], meaning
    /// the disk never signals a resize. Only backends that can detect runtime
    /// capacity changes should override this — for example, `BlockDeviceDisk`
    /// (via Linux uevent) and `NvmeDisk` (via NVMe AEN). Decorator wrappers
    /// and `LayeredDisk` should delegate to the inner disk.
    fn wait_resize(&self, sector_count: u64) -> impl Future<Output = u64> + Send {
        let _ = sector_count;
        std::future::pending()
    }
}

/// An asynchronous block device.
///
/// This type is cheap to clone, for sharing the disk among multiple concurrent
/// users.
#[derive(Inspect, Clone)]
#[inspect(extra = "Self::inspect_extra")]
pub struct Disk(#[inspect(flatten)] Arc<DiskInner>);

impl Disk {
    fn inspect_extra(&self, resp: &mut inspect::Response<'_>) {
        resp.field("disk_type", self.0.disk.disk_type())
            .field("sector_count", self.0.disk.sector_count())
            .field("supports_pr", self.0.disk.pr().is_some());
    }
}

impl Debug for Disk {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_tuple("Disk").finish()
    }
}

#[derive(Inspect)]
#[inspect(bound = "T: DynDisk")]
struct DiskInner<T: ?Sized = dyn DynDisk> {
    sector_size: u32,
    sector_shift: u32,
    physical_sector_size: u32,
    disk_id: Option<[u8; 16]>,
    is_fua_respected: bool,
    is_read_only: bool,
    unmap_behavior: UnmapBehavior,
    optimal_unmap_sectors: u32,
    disk: T,
}

/// Errors that can occur when creating a `Disk`.
#[derive(Debug, Error)]
pub enum InvalidDisk {
    /// The sector size is invalid.
    #[error("invalid sector size: {0}")]
    InvalidSectorSize(u32),
    /// The physical sector size is invalid.
    #[error("invalid physical sector size: {0}")]
    InvalidPhysicalSectorSize(u32),
}

impl Disk {
    /// Returns a new disk wrapping the given backing object.
    pub fn new(disk: impl 'static + DiskIo) -> Result<Self, InvalidDisk> {
        // Cache the metadata locally to validate it and so that it can be
        // accessed without needing to go through the trait object. This is more
        // efficient and ensures the backing disk does not change these values
        // during the lifetime of the disk.
        let sector_size = disk.sector_size();
        if !sector_size.is_power_of_two() || sector_size < 512 {
            return Err(InvalidDisk::InvalidSectorSize(sector_size));
        }
        let physical_sector_size = disk.physical_sector_size();
        if !physical_sector_size.is_power_of_two() || physical_sector_size < sector_size {
            return Err(InvalidDisk::InvalidPhysicalSectorSize(physical_sector_size));
        }
        Ok(Self(Arc::new(DiskInner {
            sector_size,
            sector_shift: sector_size.trailing_zeros(),
            physical_sector_size,
            disk_id: disk.disk_id(),
            is_fua_respected: disk.is_fua_respected(),
            is_read_only: disk.is_read_only(),
            optimal_unmap_sectors: disk.optimal_unmap_sectors(),
            unmap_behavior: disk.unmap_behavior(),
            disk,
        })))
    }

    /// Returns the current sector count.
    ///
    /// For some backing stores, this may change at runtime. Use
    /// [`wait_resize`](Self::wait_resize) to detect this change.
    pub fn sector_count(&self) -> u64 {
        self.0.disk.sector_count()
    }

    /// Returns the logical sector size of the backing store.
    pub fn sector_size(&self) -> u32 {
        self.0.sector_size
    }

    /// Returns log2 of the logical sector size of the backing store.
    pub fn sector_shift(&self) -> u32 {
        self.0.sector_shift
    }

    /// Optionally returns a 16-byte identifier for the disk, if there is a
    /// natural one for this backing store.
    ///
    /// This may be exposed to the guest as a unique disk identifier.
    pub fn disk_id(&self) -> Option<[u8; 16]> {
        self.0.disk_id
    }

    /// Returns the physical sector size of the backing store.
    pub fn physical_sector_size(&self) -> u32 {
        self.0.physical_sector_size
    }

    /// Returns true if the `fua` parameter to
    /// [`write_vectored`](Self::write_vectored) is respected by the backing
    /// store by ensuring that the IO is immediately committed to disk.
    pub fn is_fua_respected(&self) -> bool {
        self.0.is_fua_respected
    }

    /// Returns true if the disk is read only.
    pub fn is_read_only(&self) -> bool {
        self.0.is_read_only
    }

    /// Returns the largest sector number that may appear as the end of a
    /// request while keeping the end byte offset representable.
    fn max_sector(&self) -> u64 {
        (i64::MAX as u64) >> self.0.sector_shift
    }

    /// Checks that a request's end byte offset is representable.
    ///
    /// This is deliberately *not* a range check: it never consults
    /// [`sector_count`](Self::sector_count), so it cannot mask a bug in a
    /// backend that fails to validate the range itself, and it cannot be
    /// invalidated by the disk being resized. Range validation belongs to the
    /// backend, which is the only component that can perform it atomically
    /// with the I/O.
    ///
    /// What it does guarantee is that `(sector + count) * sector_size` does not
    /// overflow and is at most [`i64::MAX`], which is the real limit imposed by
    /// `pread64`/`pwrite64` and the Windows file APIs. Backends may rely on
    /// this to do sector and offset arithmetic without worrying about
    /// wraparound.
    fn check_representable(&self, sector: u64, count: u64) -> Result<(), DiskError> {
        match sector.checked_add(count) {
            Some(end) if end <= self.max_sector() => Ok(()),
            // No disk can be 2^63 bytes, so such a sector is out of range for
            // any disk.
            _ => Err(DiskError::IllegalBlock),
        }
    }

    /// Returns the number of sectors spanned by `buffers`.
    ///
    /// Callers must pass a whole number of sectors, so this is normally exact.
    /// Rounding down is nonetheless the right choice for a caller that does
    /// not: `max_sector` is `i64::MAX` rounded *down* to a sector, which for a
    /// power-of-two sector size leaves exactly `sector_size - 1` bytes of slack
    /// below `i64::MAX` — enough to cover a partial trailing sector. So the end
    /// byte offset stays representable either way.
    fn buffer_sectors(&self, buffers: &RequestBuffers<'_>) -> u64 {
        (buffers.len() as u64) >> self.0.sector_shift
    }

    /// Unmap sectors from the disk.
    ///
    /// If the disk reports [`UnmapBehavior::Ignored`], the request is not
    /// passed to the backing object at all, since by definition it would do
    /// nothing. The range is still validated first — a no-op is still not a
    /// legal response to a request naming sectors the disk does not have.
    pub async fn unmap(
        &self,
        sector: u64,
        count: u64,
        block_level_only: bool,
    ) -> Result<(), DiskError> {
        self.check_representable(sector, count)?;
        if self.unmap_behavior() == UnmapBehavior::Ignored {
            // This is the one place where `Disk` range checks a request, and it
            // is sound precisely because it is the one place where `Disk` does
            // not delegate: there is no backend check for it to be redundant
            // with, and none for it to mask. The check being momentarily stale
            // if the disk is resized is harmless here, because the operation
            // does nothing either way — only the status code is observable.
            //
            // The addition cannot overflow because of `check_representable`.
            if sector + count > self.sector_count() {
                return Err(DiskError::IllegalBlock);
            }
            return Ok(());
        }
        self.0.disk.unmap(sector, count, block_level_only).await
    }

    /// Returns the behavior of the unmap operation.
    pub fn unmap_behavior(&self) -> UnmapBehavior {
        self.0.unmap_behavior
    }

    /// Returns the optimal granularity for unmaps, in sectors.
    pub fn optimal_unmap_sectors(&self) -> u32 {
        self.0.optimal_unmap_sectors
    }

    /// Optionally returns a trait object to issue persistent reservation
    /// requests.
    pub fn pr(&self) -> Option<&dyn pr::PersistentReservation> {
        self.0.disk.pr()
    }

    /// Issues an asynchronous eject media operation to the disk.
    pub fn eject(&self) -> impl use<'_> + Future<Output = Result<(), DiskError>> + Send {
        self.0.disk.eject()
    }

    /// Issues an asynchronous read-scatter operation to the disk.
    ///
    /// # Arguments
    ///
    /// * `buffers` - An object representing the data buffers into which the disk data will be transferred.
    /// * `sector` - The logical sector at which the read operation starts.
    pub async fn read_vectored(
        &self,
        buffers: &RequestBuffers<'_>,
        sector: u64,
    ) -> Result<(), DiskError> {
        self.check_representable(sector, self.buffer_sectors(buffers))?;
        self.0.disk.read_vectored(buffers, sector).await
    }

    /// Issues an asynchronous write-gather operation to the disk.
    ///
    /// # Arguments
    ///
    /// * `buffers` - An object representing the data buffers containing the data to transfer to the disk.
    /// * `sector` - The logical sector at which the write operation starts.
    /// * `fua` - A flag indicates if FUA (force unit access) is requested.
    ///
    /// # Panics
    ///
    /// The caller must pass a buffer with an integer number of sectors.
    pub async fn write_vectored(
        &self,
        buffers: &RequestBuffers<'_>,
        sector: u64,
        fua: bool,
    ) -> Result<(), DiskError> {
        self.check_representable(sector, self.buffer_sectors(buffers))?;
        self.0.disk.write_vectored(buffers, sector, fua).await
    }

    /// Issues an asynchronous flush operation to the disk.
    pub fn sync_cache(&self) -> impl use<'_> + Future<Output = Result<(), DiskError>> + Send {
        self.0.disk.sync_cache()
    }

    /// Waits for the disk sector count to change from the specified value.
    pub fn wait_resize(&self, sector_count: u64) -> impl use<'_> + Future<Output = u64> {
        self.0.disk.wait_resize(sector_count)
    }
}

/// The behavior of the [`DiskIo::unmap`] operation.
///
/// This describes what happens to the content of unmapped sectors. Frontends
/// use this to report the correct behavior to the guest (e.g., SCSI
/// `LBPRZ` bit or NVMe DLFEAT field).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Inspect)]
pub enum UnmapBehavior {
    /// Unmap may or may not change the content, and not necessarily to zero.
    /// The guest cannot assume anything about the content of unmapped sectors.
    Unspecified,
    /// Unmaps are guaranteed to be ignored — the content is unchanged.
    /// The disk reports that unmap is not supported.
    Ignored,
    /// Unmap will deterministically zero the content. The guest can rely on
    /// reading back zeroes from unmapped sectors.
    Zeroes,
}

/// The amount of space reserved for a DiskIo future
///
/// This was chosen by running `cargo test -p storvsp -- --no-capture` and looking at the required
/// size that was given in the failure message
const ASYNC_DISK_STACK_SIZE: usize = 1256;

type IoFuture<'a> = StackFuture<'a, Result<(), DiskError>, { ASYNC_DISK_STACK_SIZE }>;

trait DynDisk: Send + Sync + Inspect {
    fn disk_type(&self) -> &str;
    fn sector_count(&self) -> u64;

    fn unmap(&self, sector_offset: u64, sector_count: u64, block_level_only: bool) -> IoFuture<'_>;

    fn pr(&self) -> Option<&dyn pr::PersistentReservation>;
    fn eject(&self) -> IoFuture<'_>;

    fn read_vectored<'a>(&'a self, buffers: &'a RequestBuffers<'_>, sector: u64) -> IoFuture<'a>;

    fn write_vectored<'a>(
        &'a self,
        buffers: &'a RequestBuffers<'_>,
        sector: u64,
        fua: bool,
    ) -> IoFuture<'a>;

    fn sync_cache(&self) -> IoFuture<'_>;

    fn wait_resize<'a>(
        &'a self,
        sector_count: u64,
    ) -> Pin<Box<dyn 'a + Send + Future<Output = u64>>> {
        let _ = sector_count;
        Box::pin(std::future::pending())
    }
}

impl<T: DiskIo> DynDisk for T {
    fn disk_type(&self) -> &str {
        self.disk_type()
    }

    fn sector_count(&self) -> u64 {
        self.sector_count()
    }

    fn unmap(
        &self,
        sector_offset: u64,
        sector_count: u64,
        block_level_only: bool,
    ) -> StackFuture<'_, Result<(), DiskError>, { ASYNC_DISK_STACK_SIZE }> {
        StackFuture::from_or_box(self.unmap(sector_offset, sector_count, block_level_only))
    }

    fn pr(&self) -> Option<&dyn pr::PersistentReservation> {
        self.pr()
    }

    fn eject(&self) -> IoFuture<'_> {
        StackFuture::from_or_box(self.eject())
    }

    fn read_vectored<'a>(&'a self, buffers: &'a RequestBuffers<'_>, sector: u64) -> IoFuture<'a> {
        StackFuture::from_or_box(self.read_vectored(buffers, sector))
    }

    fn write_vectored<'a>(
        &'a self,
        buffers: &'a RequestBuffers<'a>,
        sector: u64,
        fua: bool,
    ) -> IoFuture<'a> {
        StackFuture::from_or_box(self.write_vectored(buffers, sector, fua))
    }

    fn sync_cache(&self) -> IoFuture<'_> {
        StackFuture::from_or_box(self.sync_cache())
    }
}