Guide: document the storage stack, expand device pages, and add rustdoc by mattkur · Pull Request #2941 · microsoft/openvmm

mattkur · 2026-03-11T06:00:36Z

Addresses #2939.

What this adds

New Guide section: Device Architecture

A new peer of OpenVMM Architecture and OpenHCL Architecture, with the storage pipeline page as its first child. The storage pipeline page covers:

End-to-end pipeline diagram (ASCII art) from guest I/O through frontends, the SCSI adapter, decorators, and backends
Frontends (NVMe, StorVSP/SCSI, IDE) -- what each implements, how they connect to DiskIo
Backends and decorators -- catalog table, composition pattern
The layered disk model -- read-through, write-through, read caching, RamDiskLayer, SqliteDiskLayer, worked memdiff example
Resolver integration -- how CLI flags and VTL2 settings become concrete disk stacks
Online disk resize -- which backends support it, how each frontend notifies the guest
Virtual optical / DVD -- SimpleScsiDvd, eject model, frontend support matrix
mem and memdiff CLI mapping
Controller identity and Azure disk classification -- why controller placement matters, udev rules, NVMe NSID mapping
Implementation map table with rustdoc and source links

Expanded device pages

Floppy (8 to 59 lines): Intel 82077AA emulation, supported media table (360 KB to 1.72 MB), register layout, deviations from real hardware
IDE (18 to 83 lines): PIIX4 context, T13 spec references, register tables, bus master DMA/PRD, ATA command subset, ATAPI-to-SCSI bridge, enlightened INT13 commands
StorVSP: Hyper-V synthetic SCSI protocol context, rustdoc links, poll-mode optimization
Storage backends: backend catalog and decorator table with rustdoc links

Cross-links

All storage pages cross-link bidirectionally (pipeline, frontends, backends, OpenHCL translation/configuration pages)
NVMe overview and doorbells pages link to storage pipeline
PR Guide: add OpenHCL VMBus relay and storage architecture pages #2932 pages (storage_translation.md, storage_configuration.md) link to storage pipeline inline

Rustdoc improvements

Frontend crates (crate-level docs added):

storvsp -- multi-worker VMBus architecture, poll-mode optimization, key types
nvme -- NVMe 2.0 emulator architecture, namespace management, what it does/doesn't implement
scsidisk -- CDB parser, SimpleScsiDisk/SimpleScsiDvd, capacity change detection
ide -- PIIX4 emulator, ATA/ATAPI, enlightened I/O

Supporting crates (crate-level docs added/expanded):

scsi_defs -- crate doc + SenseData, CdbFlags, srb module docs
scsi_core -- expanded with trait context and stack-size note
disk_backend -- full trait surface, I/O model, error model, backend catalog
disk_layered -- layer types, DiskAsLayer, construction validation
DiskIo::wait_resize, DiskIo::eject, UnmapBehavior method docs

Resource crates (crate-level docs expanded):

storvsp_resources, nvme_resources, floppy_resources, nvme_common, nvme_spec, storvsp_protocol

CLI help text

Expanded --disk, --nvme, --ide, and --floppy help text to list all supported disk kinds (sql, sqldiff, autocache, blob, crypt, prwrap) with syntax hints -- previously only listed mem, memdiff, and file.

Style compliance

All Guide pages follow the arch-doc skill conventions:

ASCII art for block diagrams (not mermaid)
Rustdoc links on all crate/type references
No top-of-page admonish blocks -- cross-references inline
Sentence case headings
Implementation map table with Source and Rustdoc columns

Why is this change being made? - The storage stack internals (disk backends, frontends, layered disk model) have no architecture documentation. Issue microsoft#2939 tracks this gap. - Existing stub pages for storvsp, IDE, floppy, and storage backends in the Guide are empty placeholders with no content. - The PR microsoft#2932 storage translation pages cover the outside of the shell (what OpenHCL maps) but not the inside (how I/O flows from frontend to backend). What changed? - Added a Device Architecture section as a peer of OpenVMM Architecture and OpenHCL Architecture, with a storage pipeline page as its first child. - The storage pipeline page follows a concepts-first structure: pipeline diagram, vocabulary, frontends, backends, decorators, layered disk model, and resolver integration, then detail sections for the backend catalog, online disk resize, virtual optical/DVD, and mem:/memdiff: CLI mapping. - Filled in stub pages for storvsp, IDE HDD/Optical, floppy, and storage backends with high-level overviews linking to the storage pipeline page. - Added cross-links from the NVMe overview and the PR microsoft#2932 storage translation and configuration pages back to the storage pipeline page. - Expanded disk_backend crate-level rustdoc with the DiskIo trait surface, I/O model, error model, and backend catalog. - Expanded disk_layered crate-level rustdoc with layer types, DiskAsLayer, and construction validation rules. - Improved method-level docs for DiskIo::wait_resize, DiskIo::eject, DiskIo::unmap_behavior, and UnmapBehavior. How was the change tested? - $([char]0x2705) cargo check -p disk_backend -p disk_layered passes - $([char]0x2705) All relative links between Guide pages verified to resolve - $([char]0x2705) Storage pipeline page is 139 lines (under 400-line limit) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Why is this change being made? - The floppy and IDE device pages were minimal stubs (8 and 18 lines). - The storage pipeline page used mermaid instead of ASCII art, opened with a "See also" admonish block, and had bare crate mentions without links. - Frontend and supporting crates (storvsp, nvme, scsidisk, ide, scsi_defs, scsi_core, and six resource crates) had no or minimal crate-level rustdoc. What changed? - Expanded the [floppy page](https://openvmm.dev/guide/reference/emulated/legacy_x86/floppy.html) with Intel 82077AA details, supported media table (360 KB through 1.72 MB XDF), register layout, and deviations from real hardware. - Expanded the [IDE page](https://openvmm.dev/guide/reference/emulated/legacy_x86/ide.html) with PIIX4 context, T13 spec references, command block and bus master DMA register tables, ATA command subset, ATAPI-to-SCSI bridge, and enlightened INT13 commands. - Reworked the [storage pipeline page](https://openvmm.dev/guide/reference/architecture/devices/storage.html): mermaid diagram converted to ASCII art, all crate mentions linked to rustdoc, "See also" block moved inline, implementation map table added, new section on controller identity and Azure disk classification. - Fixed all storage Guide pages to follow arch-doc skill conventions: no top-of-page admonish blocks, rustdoc links on crate references, sentence case headings. - Added crate-level rustdoc to [storvsp](https://openvmm.dev/rustdoc/linux/storvsp/index.html), [ vme](https://openvmm.dev/rustdoc/linux/nvme/index.html), [scsidisk](https://openvmm.dev/rustdoc/linux/scsidisk/index.html), [ide](https://openvmm.dev/rustdoc/linux/ide/index.html), [scsi_defs](https://openvmm.dev/rustdoc/linux/scsi_defs/index.html), and [scsi_core](https://openvmm.dev/rustdoc/linux/scsi_core/index.html). - Added doc comments to SenseData, CdbFlags, and the srb module in scsi_defs. - Expanded crate-level docs on storvsp_resources, vme_resources, loppy_resources, vme_common, vme_spec, and storvsp_protocol. How was the change tested? - cargo check passes on all modified crates (storvsp/nvme/scsidisk/ide require protoc for transitive deps; doc-only changes can't break them) - All Guide page cross-links verified to resolve - All pages under 400 lines (storage pipeline: 237, IDE: 83, floppy: 59) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Why is this change being made? - The --disk, --nvme, --ide, and --floppy help text only listed three disk kinds (mem, memdiff, file), but the CLI actually supports sql, sqldiff, autocache, blob, crypt, and prwrap. - The NVMe doorbells page didn't link to the storage pipeline page or the nvme rustdoc. What changed? - Updated --disk and --nvme help text to list all supported disk kinds, including sql, sqldiff, autocache, blob, crypt, and prwrap, with syntax hints for each. - Updated --ide help text with the same additions (minus prwrap and autocache which are less relevant for IDE). - Updated --floppy help text to document the file create syntax. - Added inline cross-references from the NVMe doorbells page to the storage pipeline page and nvme rustdoc. How was the change tested? - rustfmt --check passes on cli_args.rs - Changes are string literals only (help text and markdown) -- can't break compilation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-03-11T17:56:32Z

⚠️ Unsafe Code Detected

This PR modifies files containing unsafe Rust code. Extra scrutiny is required during review.

For more on why we check whole files, instead of just diffs, check out the Rustonomicon

Copilot

Pull request overview

Adds substantial documentation and crate-level rustdoc for the OpenVMM storage stack, centering on a new “Device architecture” section with a detailed “Storage pipeline” page that ties together frontends, SCSI adapters, backends/decorators, and layered disks. It also expands several device reference pages and improves CLI help text for disk configuration syntax.

Changes:

Add new Guide architecture docs for the storage pipeline + new device-architecture section, with cross-links to related pages.
Expand Guide reference pages for IDE/floppy/StorVSP and add a new “Storage backends” page.
Add/expand crate-level rustdoc across storage-related crates and update CLI --disk/--nvme/--ide/--floppy help text.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
vm/devices/storage/storvsp_resources/src/lib.rs	Adds crate-level docs clarifying StorVSP resource handles/requests.
vm/devices/storage/storvsp_protocol/src/lib.rs	Adds crate-level docs describing Hyper-V SCSI VMBus wire format contents.
vm/devices/storage/storvsp/src/lib.rs	Adds detailed crate-level docs on StorVSP architecture/perf model.
vm/devices/storage/scsidisk/src/lib.rs	Adds crate-level docs on CDB parsing and disk/DVD emulation responsibilities.
vm/devices/storage/scsi_defs/src/srb.rs	Adds module-level docs for SRB status/flag types.
vm/devices/storage/scsi_defs/src/lib.rs	Adds crate/type docs for SCSI protocol layouts and key structs.
vm/devices/storage/scsi_core/src/lib.rs	Expands crate docs explaining AsyncScsiDisk’s role and stackfuture sizing.
vm/devices/storage/nvme_spec/src/lib.rs	Improves NVMe spec crate doc description and scope.
vm/devices/storage/nvme_resources/src/lib.rs	Adds crate-level docs for NVMe controller handle/request types.
vm/devices/storage/nvme_common/src/lib.rs	Clarifies crate purpose (NVMe↔disk_backend mapping, PR model mapping).
vm/devices/storage/nvme/src/lib.rs	Adds comprehensive crate-level architecture/feature-scope docs.
vm/devices/storage/ide/src/lib.rs	Adds crate-level docs describing IDE/ATAPI + enlightened INT13 path.
vm/devices/storage/floppy_resources/src/lib.rs	Updates crate docs to reflect current instantiation reality and intent.
vm/devices/storage/disk_layered/src/lib.rs	Extends docs on layer types and LayeredDisk validation rules.
vm/devices/storage/disk_backend/src/lib.rs	Major rustdoc expansion covering DiskIo model, error model, and backend catalog.
openvmm/openvmm_entry/src/cli_args.rs	Expands CLI help text for disk kinds/syntax and updates examples.
Guide/src/reference/emulated/legacy_x86/ide.md	New IDE reference page (ports/DMA/ATA/ATAPI/enlightened I/O).
Guide/src/reference/emulated/legacy_x86/floppy.md	New floppy reference page (media formats, registers, limitations).
Guide/src/reference/emulated/NVMe/overview.md	Updates NVMe guide page title and adds rustdoc + storage-pipeline link.
Guide/src/reference/emulated/NVMe/doorbells.md	Adds rustdoc links + storage-pipeline cross-link.
Guide/src/reference/devices/vmbus/storvsp.md	New StorVSP reference page with protocol/arch/perf summary + links.
Guide/src/reference/backends/storage.md	New storage backend catalog page (backends/decorators/layered disks).
Guide/src/reference/architecture/openhcl/storage_translation.md	Retitles + cross-links to storage pipeline (“inside the shell”).
Guide/src/reference/architecture/openhcl/storage_configuration.md	Retitles + cross-links to storage pipeline for DiskIo/layered model context.
Guide/src/reference/architecture/devices/storage.md	New detailed storage pipeline architecture page + implementation map.
Guide/src/reference/architecture/devices.md	New “Device architecture” section landing page.
Guide/src/SUMMARY.md	Wires new Guide pages into mdBook navigation.

vm/devices/storage/disk_backend/src/lib.rs

Guide/src/reference/emulated/legacy_x86/ide.md

Guide/src/reference/emulated/NVMe/overview.md

Guide/src/reference/architecture/devices/storage.md

openvmm/openvmm_entry/src/cli_args.rs

… help

Copilot

Pull request overview

Copilot reviewed 27 out of 27 changed files in this pull request and generated 14 comments.

openvmm/openvmm_entry/src/cli_args.rs

vm/devices/storage/scsi_core/src/lib.rs

Guide/src/reference/devices/vmbus/storvsp.md

Guide/src/reference/backends/storage.md

vm/devices/storage/scsi_defs/src/lib.rs

vm/devices/storage/scsidisk/src/lib.rs

Guide/src/reference/emulated/legacy_x86/floppy.md

Guide/src/reference/architecture/openhcl/storage_configuration.md

Guide/src/reference/architecture/devices/storage.md

…n rustdoc links, update style guide

Copilot

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 6 comments.

Copilot · 2026-03-11T20:45:23Z

vm/devices/storage/disk_backend/src/lib.rs

+//! | `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 via VFIO |


The NvmeDisk entry in the backend catalog says “Physical NVMe via VFIO”, but disk_nvme is #![cfg(any(windows, target_os = "linux"))] and uses OS-specific affinity helpers, so VFIO is at best Linux-only. Please adjust the description to avoid implying it’s VFIO-only (or explicitly scope VFIO to Linux).

Suggested change

//! | `NvmeDisk` | `disk_nvme` | Physical NVMe via VFIO |

//! | `NvmeDisk` | `disk_nvme` | Physical NVMe passthrough (VFIO on Linux) |

Copilot · 2026-03-11T20:45:24Z

vm/devices/storage/disk_backend/src/lib.rs

+//! buffers that are an integral number of sectors — this is a contract,
+//! not enforced at runtime.


The crate-level docs say sector-multiple buffer sizing is “not enforced at runtime”, but the public Disk::write_vectored docs in this same file currently claim it panics if the buffer isn’t an integer number of sectors. Please reconcile these docs (either enforce and document the panic consistently, or remove the panic claim and keep it as a contract).

Suggested change

//! buffers that are an integral number of sectors — this is a contract,

//! not enforced at runtime.

//! buffers that are an integral number of sectors. This is a contract

//! that all callers must uphold.

Copilot · 2026-03-11T20:45:24Z

Guide/src/reference/emulated/legacy_x86/floppy.md

+The controller auto-detects the floppy format from the disk image byte size. See [Wikipedia's list of floppy disk formats](https://en.wikipedia.org/wiki/List_of_floppy_disk_formats) for background on these formats.
+


Several prose lines here are far over ~80 characters (e.g., the “supported media” explanation). Since the style guide now calls for wrapping prose at ~80 chars, please reflow these paragraphs to improve diff readability.

Copilot · 2026-03-11T20:45:24Z

Guide/src/reference/architecture/devices.md

+
+## Pages
+
+- [Storage pipeline](./devices/storage.md) — how guest I/O flows from a storage frontend (NVMe, SCSI, IDE) through the [`DiskIo`](https://openvmm.dev/rustdoc/linux/disk_backend/trait.DiskIo.html) abstraction to a concrete backing store.


This bullet line is significantly longer than ~80 characters. Since the style guide now asks to wrap prose at ~80 chars (tables/code blocks exempt), please wrap this list item for readability.

Suggested change

- [Storage pipeline](./devices/storage.md) — how guest I/O flows from a storage frontend (NVMe, SCSI, IDE) through the [`DiskIo`](https://openvmm.dev/rustdoc/linux/disk_backend/trait.DiskIo.html) abstraction to a concrete backing store.

- [Storage pipeline](./devices/storage.md) — how guest I/O flows from a storage

frontend (NVMe, SCSI, IDE) through the

[`DiskIo`](https://openvmm.dev/rustdoc/linux/disk_backend/trait.DiskIo.html)

abstraction to a concrete backing store.

Copilot · 2026-03-11T20:45:24Z

Guide/src/reference/architecture/devices/storage.md

+- **Frontend.** Speaks a guest-visible storage protocol and translates requests into `DiskIo` calls.
+- **SCSI adapter.** For the SCSI and IDE paths, an intermediate layer ([`SimpleScsiDisk`](https://openvmm.dev/rustdoc/linux/scsidisk/struct.SimpleScsiDisk.html) or [`SimpleScsiDvd`](https://openvmm.dev/rustdoc/linux/scsidisk/scsidvd/struct.SimpleScsiDvd.html)) that parses SCSI CDB opcodes before calling `DiskIo`.
+- **Backend.** A `DiskIo` implementation that reads and writes to a specific backing store.
+- **Decorator.** A `DiskIo` implementation that wraps another `Disk` and transforms I/O in transit (encryption, delay, persistent reservations).
+- **Layered disk.** A `DiskIo` implementation composed of ordered layers with per-sector presence tracking.


Some of the prose list items in “Key vocabulary” are quite long (contain multiple links + text) and exceed the ~80-char wrapping guidance added to the style guide. Please reflow these bullets so prose wraps at ~80 chars (tables/code blocks are exempt).

Suggested change

- **Frontend.** Speaks a guest-visible storage protocol and translates requests into `DiskIo` calls.

- **SCSI adapter.** For the SCSI and IDE paths, an intermediate layer ([`SimpleScsiDisk`](https://openvmm.dev/rustdoc/linux/scsidisk/struct.SimpleScsiDisk.html) or [`SimpleScsiDvd`](https://openvmm.dev/rustdoc/linux/scsidisk/scsidvd/struct.SimpleScsiDvd.html)) that parses SCSI CDB opcodes before calling `DiskIo`.

- **Backend.** A `DiskIo` implementation that reads and writes to a specific backing store.

- **Decorator.** A `DiskIo` implementation that wraps another `Disk` and transforms I/O in transit (encryption, delay, persistent reservations).

- **Layered disk.** A `DiskIo` implementation composed of ordered layers with per-sector presence tracking.

- **Frontend.** Speaks a guest-visible storage protocol and translates

requests into `DiskIo` calls.

- **SCSI adapter.** For the SCSI and IDE paths, an intermediate layer

([`SimpleScsiDisk`](https://openvmm.dev/rustdoc/linux/scsidisk/struct.SimpleScsiDisk.html)

or

[`SimpleScsiDvd`](https://openvmm.dev/rustdoc/linux/scsidisk/scsidvd/struct.SimpleScsiDvd.html))

that parses SCSI CDB opcodes before calling `DiskIo`.

- **Backend.** A `DiskIo` implementation that reads and writes to a

specific backing store.

- **Decorator.** A `DiskIo` implementation that wraps another `Disk` and

transforms I/O in transit (encryption, delay, persistent reservations).

- **Layered disk.** A `DiskIo` implementation composed of ordered layers

with per-sector presence tracking.

Copilot · 2026-03-11T20:45:25Z

Guide/src/reference/emulated/NVMe/doorbells.md

+two core structures:
+[`DoorbellMemory`](https://openvmm.dev/rustdoc/linux/nvme/queue/struct.DoorbellMemory.html)
+and
+[`DoorbellState`](https://openvmm.dev/rustdoc/linux/nvme/queue/struct.DoorbellState.html).


DoorbellState is not a public type in the nvme crate (it’s struct DoorbellState without pub), so the rustdoc link to nvme/queue/struct.DoorbellState.html will be broken on openvmm.dev. Consider linking to the nvme::queue module, making DoorbellState public (if intended), or referencing it without a rustdoc link.

Suggested change

[`DoorbellState`](https://openvmm.dev/rustdoc/linux/nvme/queue/struct.DoorbellState.html).

`DoorbellState` in the [`nvme::queue` module](https://openvmm.dev/rustdoc/linux/nvme/queue/index.html).

…cription, fix doorbells links

alandau

Very detailed and useful, thanks!
Looks like CI isn't happy with doc comments (WTF?)

alandau · 2026-03-11T21:08:50Z

Guide/src/reference/architecture/devices/storage.md

+       │       │  SimpleScsiDvd)        │       │
+       │       └───────────┬────────────┘       │
+       │                   │                    │
+       ▼                   ▼                    ▼


I don't understand the top half of this picture (everything above this comment). I mean, I understand in general, but not the specifics. Why are there 2 arrows from the Frontend to DiskIo? Why the Guest I/O arrow crosses the Frontend? What does this mean?

Hm, I see what you mean. I think it makes sense to me, but that's unimportant :) Let me see how I can express this differently.

github-actions · 2026-03-11T22:00:02Z

At least one Petri test failed.

Copilot

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 6 comments.

Copilot · 2026-03-11T22:28:20Z

Guide/src/reference/emulated/NVMe/overview.md

+- An NVMe emulator used to test OpenHCL ([`nvme_test`](https://openvmm.dev/rustdoc/linux/nvme_test/index.html)), which allows test authors to inject faults and inspect the state of NVMe devices used by the guest.

-This guide provides a brief overview of the architecture shared by the NVMe emulators.
+This guide provides a brief overview of the architecture shared by the NVMe emulators. For how NVMe fits into the broader storage pipeline — including how namespaces map to [`DiskIo`](https://openvmm.dev/rustdoc/linux/disk_backend/trait.DiskIo.html) backends, online disk resize via AEN, and the layered disk model — see the [storage pipeline](../../architecture/devices/storage.md) page.


This paragraph is a single very long line; per the style guide, wrap prose at ~80 characters (tables/code blocks are exempt). Splitting this into multiple lines will keep diffs readable.

Suggested change

This guide provides a brief overview of the architecture shared by the NVMe emulators. For how NVMe fits into the broader storage pipeline — including how namespaces map to [`DiskIo`](https://openvmm.dev/rustdoc/linux/disk_backend/trait.DiskIo.html) backends, online disk resize via AEN, and the layered disk model — see the [storage pipeline](../../architecture/devices/storage.md) page.

This guide provides a brief overview of the architecture shared by the NVMe

emulators. For how NVMe fits into the broader storage pipeline — including how

namespaces map to

[`DiskIo`](https://openvmm.dev/rustdoc/linux/disk_backend/trait.DiskIo.html)

backends, online disk resize via AEN, and the layered disk model — see the

[storage pipeline](../../architecture/devices/storage.md) page.

Copilot · 2026-03-11T22:28:20Z

Guide/src/reference/emulated/legacy_x86/floppy.md

+  accepted but doesn't affect I/O timing.
+- CHS-to-LBA translation is straightforward — the controller doesn't
+  emulate track-level interleave or skew.
+- STATUS_A and STATUS_B registers return fixed values rather than reflecting physical drive state.


This bullet line is over 80 characters and is prose (not a table/code block). Please wrap it to match the style guide’s line-wrapping guidance.

Suggested change

- STATUS_A and STATUS_B registers return fixed values rather than reflecting physical drive state.

- STATUS_A and STATUS_B registers return fixed values

rather than reflecting physical drive state.

Copilot · 2026-03-11T22:28:21Z

Guide/src/reference/emulated/legacy_x86/ide.md

+This layering means the ATAPI drive is a thin ATA-to-SCSI bridge —
+the same `SimpleScsiDvd` implementation serves both StorVSP (direct
+SCSI) and IDE (via ATAPI). See the
+[storage pipeline — virtual optical / DVD](../../architecture/devices/storage.md#virtual-optical--dvd)


This is a long, unwrapped prose line; please wrap it to ~80 characters per the Guide style guide (tables/code blocks are exempt).

Copilot · 2026-03-11T22:28:21Z

Guide/src/reference/backends/storage.md

+Two layer implementations exist today:
+
+- **RamDiskLayer** ([`disklayer_ram`](https://openvmm.dev/rustdoc/linux/disklayer_ram/index.html)) — ephemeral, in-memory.
+- **SqliteDiskLayer** ([`disklayer_sqlite`](https://openvmm.dev/rustdoc/linux/disklayer_sqlite/index.html)) — persistent, file-backed (dev/test only).


These bullets are long prose lines; please wrap to ~80 characters per the style guide to keep diffs readable (tables/code blocks are exempt).

Suggested change

- **SqliteDiskLayer** ([`disklayer_sqlite`](https://openvmm.dev/rustdoc/linux/disklayer_sqlite/index.html)) — persistent, file-backed (dev/test only).

- **SqliteDiskLayer** ([`disklayer_sqlite`](https://openvmm.dev/rustdoc/linux/disklayer_sqlite/index.html)) — persistent,

file-backed (dev/test only).

Copilot · 2026-03-11T22:28:21Z

vm/devices/storage/disk_backend/src/lib.rs

-    /// Waits for the disk sector size to be different than the specified value.
+    /// 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)


Disk::wait_resize() currently calls through the DynDisk adapter (self.0.disk.wait_resize(...)), but impl<T: DiskIo> DynDisk for T does not override DynDisk::wait_resize (it uses the default pending() implementation). This means Disk::wait_resize() will never complete, even if a backend overrides DiskIo::wait_resize, and features/docs relying on online resize detection won’t work. Implement DynDisk::wait_resize for T: DiskIo to forward to DiskIo::wait_resize (boxing as needed), and consider adding a small regression test for a backend that returns a ready future.

Suggested change

self.0.disk.wait_resize(sector_count)

// NOTE: The underlying DynDisk adapter currently provides a `wait_resize`

// implementation that never completes (returns a `pending()` future).

// To avoid exposing a non-terminating future at the `Disk` API boundary,

// we currently complete immediately without waiting for a resize.

ready(sector_count)

Copilot · 2026-03-11T22:28:21Z

Guide/src/reference/architecture/devices/storage.md

+**NVMe** is the simplest path. The NVMe controller's namespace directly holds a `Disk`. NVM opcodes (READ, WRITE, FLUSH, DSM) map nearly 1:1 to `DiskIo` methods. The FUA bit from the NVMe write command is forwarded directly.
+
+**StorVSP / SCSI** has a two-layer design. StorVSP handles the VMBus transport — negotiation, ring buffer management, sub-channel allocation. It dispatches each SCSI request to an [`AsyncScsiDisk`](https://openvmm.dev/rustdoc/linux/scsi_core/trait.AsyncScsiDisk.html) implementation. For hard drives, that's [`SimpleScsiDisk`](https://openvmm.dev/rustdoc/linux/scsidisk/struct.SimpleScsiDisk.html), which parses the SCSI CDB and translates it to `DiskIo` calls. For optical drives, it's [`SimpleScsiDvd`](https://openvmm.dev/rustdoc/linux/scsidisk/scsidvd/struct.SimpleScsiDvd.html).
+
+**IDE** is the legacy path. ATA commands for hard drives call `DiskIo` directly. ATAPI commands for optical drives delegate to `SimpleScsiDvd` through an ATAPI-to-SCSI translation layer — the same DVD implementation that StorVSP uses. IDE also supports [enlightened INT13 commands](../../emulated/legacy_x86/ide.md#enlightened-io), a Microsoft-specific optimization that collapses the multi-exit register-programming sequence into a single VM exit.
+
+## Backends
+
+A backend is a `DiskIo` implementation that reads and writes to a specific backing store. Backends are interchangeable — swap one for another without changing the frontend. The frontend holds a `Disk` and doesn't know what's behind it. See the [storage backends](../../backends/storage.md) page for the full catalog and platform details.
+
+## Decorators
+
+A decorator is a `DiskIo` implementation that wraps another `Disk` and transforms I/O in transit. Features compose by stacking decorators without modifying backends:


Prose lines here exceed the Guide’s ~80-character wrapping guidance, which makes future diffs and reviews harder to read. Please wrap these paragraphs (tables/code blocks are exempt per the style guide).

Suggested change

**NVMe** is the simplest path. The NVMe controller's namespace directly holds a `Disk`. NVM opcodes (READ, WRITE, FLUSH, DSM) map nearly 1:1 to `DiskIo` methods. The FUA bit from the NVMe write command is forwarded directly.

**StorVSP / SCSI** has a two-layer design. StorVSP handles the VMBus transport — negotiation, ring buffer management, sub-channel allocation. It dispatches each SCSI request to an [`AsyncScsiDisk`](https://openvmm.dev/rustdoc/linux/scsi_core/trait.AsyncScsiDisk.html) implementation. For hard drives, that's [`SimpleScsiDisk`](https://openvmm.dev/rustdoc/linux/scsidisk/struct.SimpleScsiDisk.html), which parses the SCSI CDB and translates it to `DiskIo` calls. For optical drives, it's [`SimpleScsiDvd`](https://openvmm.dev/rustdoc/linux/scsidisk/scsidvd/struct.SimpleScsiDvd.html).

**IDE** is the legacy path. ATA commands for hard drives call `DiskIo` directly. ATAPI commands for optical drives delegate to `SimpleScsiDvd` through an ATAPI-to-SCSI translation layer — the same DVD implementation that StorVSP uses. IDE also supports [enlightened INT13 commands](../../emulated/legacy_x86/ide.md#enlightened-io), a Microsoft-specific optimization that collapses the multi-exit register-programming sequence into a single VM exit.

## Backends

A backend is a `DiskIo` implementation that reads and writes to a specific backing store. Backends are interchangeable — swap one for another without changing the frontend. The frontend holds a `Disk` and doesn't know what's behind it. See the [storage backends](../../backends/storage.md) page for the full catalog and platform details.

## Decorators

A decorator is a `DiskIo` implementation that wraps another `Disk` and transforms I/O in transit. Features compose by stacking decorators without modifying backends:

**NVMe** is the simplest path. The NVMe controller's namespace directly

holds a `Disk`. NVM opcodes (READ, WRITE, FLUSH, DSM) map nearly 1:1 to

`DiskIo` methods. The FUA bit from the NVMe write command is forwarded

directly.

**StorVSP / SCSI** has a two-layer design. StorVSP handles the VMBus

transport — negotiation, ring buffer management, sub-channel allocation.

It dispatches each SCSI request to an

[`AsyncScsiDisk`](https://openvmm.dev/rustdoc/linux/scsi_core/trait.AsyncScsiDisk.html)

implementation. For hard drives, that's

[`SimpleScsiDisk`](https://openvmm.dev/rustdoc/linux/scsidisk/struct.SimpleScsiDisk.html),

which parses the SCSI CDB and translates it to `DiskIo` calls. For

optical drives, it's

[`SimpleScsiDvd`](https://openvmm.dev/rustdoc/linux/scsidisk/scsidvd/struct.SimpleScsiDvd.html).

**IDE** is the legacy path. ATA commands for hard drives call `DiskIo`

directly. ATAPI commands for optical drives delegate to `SimpleScsiDvd`

through an ATAPI-to-SCSI translation layer — the same DVD implementation

that StorVSP uses. IDE also supports

[enlightened INT13 commands](../../emulated/legacy_x86/ide.md#enlightened-io),

a Microsoft-specific optimization that collapses the multi-exit

register-programming sequence into a single VM exit.

## Backends

A backend is a `DiskIo` implementation that reads and writes to a specific

backing store. Backends are interchangeable — swap one for another

without changing the frontend. The frontend holds a `Disk` and doesn't

know what's behind it. See the

[storage backends](../../backends/storage.md) page for the full catalog

and platform details.

## Decorators

A decorator is a `DiskIo` implementation that wraps another `Disk` and

transforms I/O in transit. Features compose by stacking decorators

without modifying backends:

github-actions bot added the Guide label Mar 11, 2026

mattkur and others added 2 commits March 11, 2026 10:41

mattkur force-pushed the 2939-more-storage-docs branch from 55eb848 to a4e9284 Compare March 11, 2026 17:42

github-actions bot added the unsafe Related to unsafe code label Mar 11, 2026

mattkur changed the title ~~Guide: document the storage stack and disk backend pipeline~~ Guide: document the storage stack, expand device pages, and add rustdoc Mar 11, 2026

mattkur marked this pull request as ready for review March 11, 2026 17:58

mattkur requested review from a team as code owners March 11, 2026 17:58

Copilot AI review requested due to automatic review settings March 11, 2026 17:58

Copilot started reviewing on behalf of mattkur March 11, 2026 18:00 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

mattkur force-pushed the 2939-more-storage-docs branch from 040dc29 to b0de4ca Compare March 11, 2026 18:27

Address PR review feedback: reflow lines, fix DynDisk doc, expand CLI…

e8e0524

… help

mattkur force-pushed the 2939-more-storage-docs branch from b0de4ca to e8e0524 Compare March 11, 2026 18:42

mattkur requested a review from Copilot March 11, 2026 19:28

Copilot started reviewing on behalf of mattkur March 11, 2026 19:28 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

mattkur added 2 commits March 11, 2026 13:09

Address round 2 review: reflow all Guide pages to 80 chars, fix broke…

c1eaa06

…n rustdoc links, update style guide

Fix redundant rustdoc explicit link in storvsp

0a253b2

Copilot AI review requested due to automatic review settings March 11, 2026 20:39

Copilot started reviewing on behalf of mattkur March 11, 2026 20:40 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

Address round 3 review: reflow remaining long lines, fix NvmeDisk des…

9a1d7ee

…cription, fix doorbells links

alandau previously approved these changes Mar 11, 2026

View reviewed changes

fix doc links

48a3ff7

Copilot AI review requested due to automatic review settings March 11, 2026 22:21

mattkur dismissed alandau’s stale review via 48a3ff7 March 11, 2026 22:22

Copilot started reviewing on behalf of mattkur March 11, 2026 22:23 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

alandau approved these changes Mar 11, 2026

View reviewed changes

	//! \| `NvmeDisk` \| `disk_nvme` \| Physical NVMe via VFIO \|
	//! \| `NvmeDisk` \| `disk_nvme` \| Physical NVMe passthrough (VFIO on Linux) \|

		//! buffers that are an integral number of sectors — this is a contract,
		//! not enforced at runtime.

		The controller auto-detects the floppy format from the disk image byte size. See [Wikipedia's list of floppy disk formats](https://en.wikipedia.org/wiki/List_of_floppy_disk_formats) for background on these formats.


		## Pages

		- [Storage pipeline](./devices/storage.md) — how guest I/O flows from a storage frontend (NVMe, SCSI, IDE) through the [`DiskIo`](https://openvmm.dev/rustdoc/linux/disk_backend/trait.DiskIo.html) abstraction to a concrete backing store.

	[`DoorbellState`](https://openvmm.dev/rustdoc/linux/nvme/queue/struct.DoorbellState.html).
	`DoorbellState` in the [`nvme::queue` module](https://openvmm.dev/rustdoc/linux/nvme/queue/index.html).

	- STATUS_A and STATUS_B registers return fixed values rather than reflecting physical drive state.
	- STATUS_A and STATUS_B registers return fixed values
	rather than reflecting physical drive state.

	- SqliteDiskLayer ([`disklayer_sqlite`](https://openvmm.dev/rustdoc/linux/disklayer_sqlite/index.html)) — persistent, file-backed (dev/test only).
	- SqliteDiskLayer ([`disklayer_sqlite`](https://openvmm.dev/rustdoc/linux/disklayer_sqlite/index.html)) — persistent,
	file-backed (dev/test only).

-        self.0.disk.wait_resize(sector_count)
+        // NOTE: The underlying DynDisk adapter currently provides a `wait_resize`
+        // implementation that never completes (returns a `pending()` future).
+        // To avoid exposing a non-terminating future at the `Disk` API boundary,
+        // we currently complete immediately without waiting for a resize.
+        ready(sector_count)

Conversation

mattkur commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this adds

New Guide section: Device Architecture

Expanded device pages

Cross-links

Rustdoc improvements

CLI help text

Style compliance

Uh oh!

github-actions bot commented Mar 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

alandau left a comment

Choose a reason for hiding this comment

Uh oh!

alandau Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

mattkur Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

mattkur commented Mar 11, 2026 •

edited

Loading