Crate disk_backend 

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

Modules

pr

Persistent reservation support.

resolve

Resolver-related definitions for disk resources.

sync_wrapper

A wrapper around Disk that adapts the trait for use with synchronous std::io traits (such as Read, Write, Seek, etc…).

Structs

Disk

An asynchronous block device.

Enums

DiskError

A disk operation error.

InvalidDisk

Errors that can occur when creating a Disk.

MediumErrorDetails

Failure details for DiskError::MediumError.

UnmapBehavior

The behavior of the DiskIo::unmap operation.

Traits

DiskIo

Disk metadata and IO operations.