guide: document StorVSP channels and subchannels#2976
guide: document StorVSP channels and subchannels#2976mattkur wants to merge 2 commits intomicrosoft:mainfrom
Conversation
86749fd to
1028225
Compare
There was a problem hiding this comment.
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
storvspcrate 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. |
Guide/src/reference/architecture/openhcl/storage_configuration.md
Outdated
Show resolved
Hide resolved
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>
c49d5c4 to
80f849d
Compare
There was a problem hiding this comment.
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
storvspto 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. |
Guide/src/reference/architecture/openhcl/storage_configuration.md
Outdated
Show resolved
Hide resolved
Guide/src/reference/architecture/openhcl/storage_configuration.md
Outdated
Show resolved
Hide resolved
- 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>
There was a problem hiding this comment.
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
storvspcrate 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. |
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
devices/vmbus/storvsp_channels.mdcovering 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.storvsp.mdwith cross-link to the new page.storage.mdwith cross-link from sub-channel allocation mention.storage_configuration.mdwithscsi_sub_channelsfixed settings documentation.ide.mdwith new IDE accelerator section explaining the StorVSP-backed VMBus path and why it doesn't support subchannels.storvspcrate-level rustdoc.Addresses #2954, touches #2955. Can be reviewed independently from the VMBus channels (#2977) and CPU scheduling (#2975) PRs.