Skip to content

guide: document StorVSP channels and subchannels#2976

Open
mattkur wants to merge 2 commits intomicrosoft:mainfrom
mattkur:guide/storvsp-channels
Open

guide: document StorVSP channels and subchannels#2976
mattkur wants to merge 2 commits intomicrosoft:mainfrom
mattkur:guide/storvsp-channels

Conversation

@mattkur
Copy link
Contributor

@mattkur mattkur commented Mar 13, 2026

The existing storvsp page mentions subchannels in a bullet point but has no coverage of the negotiation sequence, worker model, CPU affinity, performance tradeoffs, or configuration.

Changes

  • New Guide page: devices/vmbus/storvsp_channels.md covering subchannel negotiation (mermaid sequence diagram), the one-worker-per-channel model, CPU affinity and VP targeting, IDE accelerator comparison, subchannel scaling illustrations (0 subs through 64 VPs), poll mode mechanics, the slow-disk head-of-line blocking problem, cooperative executor impact, sidecar behavior, configuration (CLI + OpenHCL VTL2 settings + guest kernel params), Hyper-V behavioral differences, and inspect output.
  • Updated storvsp.md with cross-link to the new page.
  • Updated storage.md with cross-link from sub-channel allocation mention.
  • Updated storage_configuration.md with scsi_sub_channels fixed settings documentation.
  • Updated ide.md with new IDE accelerator section explaining the StorVSP-backed VMBus path and why it doesn't support subchannels.
  • Added Guide cross-link to storvsp crate-level rustdoc.

Addresses #2954, touches #2955. Can be reviewed independently from the VMBus channels (#2977) and CPU scheduling (#2975) PRs.

@mattkur mattkur force-pushed the guide/storvsp-channels branch from 86749fd to 1028225 Compare March 13, 2026 19:00
@mattkur mattkur marked this pull request as ready for review March 13, 2026 19:19
@mattkur mattkur requested review from a team as code owners March 13, 2026 19:19
Copilot AI review requested due to automatic review settings March 13, 2026 19:19
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR expands OpenVMM Guide documentation around StorVSP’s VMBus channel/subchannel behavior (negotiation, worker/affinity/perf characteristics, and configuration) and adds cross-links from related storage and IDE docs, plus a rustdoc pointer back to the Guide.

Changes:

  • Add a new Guide reference page documenting StorVSP channels/subchannels in depth, including diagrams, perf notes, configuration, and inspect output.
  • Cross-link the new page from existing StorVSP, storage pipeline, OpenHCL storage configuration, and IDE documentation.
  • Add a crate-level rustdoc link from the storvsp crate to the new Guide page.

Reviewed changes

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

Show a summary per file
File Description
vm/devices/storage/storvsp/src/lib.rs Adds a rustdoc link to the new Guide page for channel/subchannel details.
Guide/src/reference/emulated/legacy_x86/ide.md Documents the StorVSP-backed IDE accelerator and links to StorVSP channel/subchannel docs.
Guide/src/reference/devices/vmbus/storvsp_channels.md New, detailed reference page for StorVSP channels/subchannels (negotiation, workers, affinity, perf, config, inspect).
Guide/src/reference/devices/vmbus/storvsp.md Adds a cross-link to the new channels/subchannels page.
Guide/src/reference/architecture/openhcl/storage_configuration.md Documents fixed settings and links to the new StorVSP channels/subchannels page.
Guide/src/reference/architecture/devices/storage.md Links “sub-channel allocation” text to the new StorVSP channels/subchannels page.
Guide/src/SUMMARY.md Adds the new page to the Guide navigation under VMBus → storvsp.

Why is this change being made?
- Addresses [microsoft#2954](microsoft#2954) —
  the existing storvsp page mentions subchannels in a bullet point but
  has no detailed coverage of the negotiation sequence, worker model,
  CPU affinity, performance tradeoffs, or configuration.
- Touches on [microsoft#2955](microsoft#2955)
  by documenting the channel-level foundation that CPU affinity builds on.

What changed?
- New Guide page: `Guide/src/reference/devices/vmbus/storvsp_channels.md`
  covering subchannel negotiation (mermaid sequence diagram), worker model,
  CPU affinity and targeting, IDE accelerator comparison, subchannel scaling
  illustrations, poll mode, the slow-disk problem, cooperative executor
  impact, sidecar behavior, configuration (CLI + OpenHCL + guest kernel),
  Hyper-V differences, and inspect output.
- Updated `storvsp.md` with cross-link to the new page.
- Updated `storage.md` with cross-link from "sub-channel allocation."
- Updated `storage_configuration.md` with `scsi_sub_channels` fixed
  settings documentation.
- Updated `ide.md` with IDE accelerator section explaining StorVSP-backed
  VMBus path and why it doesn't support subchannels.
- Added Guide cross-link to
  [`storvsp`](https://openvmm.dev/rustdoc/linux/storvsp/index.html)
  crate-level rustdoc.

How was the change tested?
- ✅ `cargo doc --no-deps -p storvsp` — no warnings
- ✅ Guide cross-links verified against existing pages

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds substantially expanded Guide coverage for StorVSP’s channel/subchannel behavior (negotiation, workers, affinity, performance, and configuration) and links it from related storage docs and rustdoc.

Changes:

  • Add a new Guide reference page documenting StorVSP channels/subchannels in depth.
  • Cross-link the new page from existing StorVSP/storage/IDE documentation.
  • Add a crate-level rustdoc link from storvsp to the corresponding Guide page.

Reviewed changes

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

Show a summary per file
File Description
vm/devices/storage/storvsp/src/lib.rs Adds rustdoc link to the new Guide page for channels/subchannels context.
Guide/src/reference/emulated/legacy_x86/ide.md Documents the StorVSP-backed IDE accelerator and links to the new page for subchannel details.
Guide/src/reference/devices/vmbus/storvsp_channels.md New in-depth reference page on negotiation, worker model, affinity, perf tradeoffs, config, and inspect examples.
Guide/src/reference/devices/vmbus/storvsp.md Adds a cross-link to the new channels/subchannels page.
Guide/src/reference/architecture/openhcl/storage_configuration.md Documents fixed settings including scsi_sub_channels and links to the new page.
Guide/src/reference/architecture/devices/storage.md Links “sub-channel allocation” to the new StorVSP channels/subchannels page.
Guide/src/SUMMARY.md Adds the new page to the mdBook table of contents under StorVSP.

- Replace synthetic inspect example with real output captured from
  openvmm.exe running with --scsi-sub-channels 2
- Fix inspect path: scsi:<instance_id>/ not storvsp/
- Fix scsi_sub_channels type: u16 not u32
- Fix vtl2_settings_worker reference to use full module path
- Fix poll_mode_queue_depth inspect example path

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR expands the OpenVMM Guide’s StorVSP documentation by adding a dedicated reference page explaining StorVSP’s VMBus channel/subchannel model, how it maps to worker execution and VP targeting, and how to configure/tune it across OpenVMM and OpenHCL.

Changes:

  • Adds a new Guide page documenting StorVSP channels/subchannels (negotiation, worker model, CPU affinity, scaling, poll mode, configuration, inspect output).
  • Cross-links the new page from existing StorVSP/storage docs and adds an IDE-accelerator (StorVSP-backed) section.
  • Adds a crate-level rustdoc link from the storvsp crate to the new Guide documentation.

Reviewed changes

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

Show a summary per file
File Description
vm/devices/storage/storvsp/src/lib.rs Adds rustdoc link pointing readers to the new Guide page for channel/subchannel behavior.
Guide/src/reference/emulated/legacy_x86/ide.md Documents the StorVSP-backed IDE accelerator and explains why it does not use subchannels.
Guide/src/reference/devices/vmbus/storvsp_channels.md New in-depth reference page for StorVSP channels/subchannels, including diagrams and configuration guidance.
Guide/src/reference/devices/vmbus/storvsp.md Adds a link from the StorVSP overview page to the new channels/subchannels page.
Guide/src/reference/architecture/openhcl/storage_configuration.md Documents scsi_sub_channels in fixed VTL2 settings and links to the new StorVSP channels page.
Guide/src/reference/architecture/devices/storage.md Links sub-channel allocation mention to the new StorVSP channels page.
Guide/src/SUMMARY.md Adds the new page to the mdBook navigation under VMBus → storvsp.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants