guide: document VMBus channel model by mattkur · Pull Request #2977 · microsoft/openvmm

mattkur · 2026-03-13T18:31:43Z

The VMBus channel model — identity tuples, ring buffer pairs, subchannels, target VP, and lifecycle — is foundational to understanding any VMBus device but was not documented in the Guide. VP index vs APIC ID vs Linux CPU number confusion comes up frequently in debugging.

Changes

New Guide page: architecture/vmbus/channels.md covering channel identity (OfferKey), ring buffer pairs (diagram), subchannel lifecycle (mermaid state diagram), target VP semantics, VP index vs CPU number vs APIC ID clarification, ring buffer queuing model, and key types table.
New VMBus Architecture section in SUMMARY.md.
Expanded rustdoc for VmbusDevice trait — max_subchannels() now documents that it's the device's upper bound (not current count) and how the framework uses it; retarget_vp() now documents when it's called and what devices should do.
Expanded rustdoc for ChannelControl — documents the enable_subchannels() error case and usage context (called from device protocol handlers like StorVSP's CREATE_SUB_CHANNELS).

Can be reviewed independently from the StorVSP channels (#2976) and CPU scheduling (#2975) PRs.

mattkur · 2026-03-13T18:55:51Z

Guide/src/reference/architecture/vmbus/channels.md

+  │  VMBus Channel                                 │
+  │                                                │
+  │  ┌──────────────────┐  ┌──────────────────┐   │
+  │  │  Incoming Ring    │  │  Outgoing Ring   │   │
+  │  │  (guest → host)  │  │  (host → guest)  │   │
+  │  └────────┬─────────┘  └────────┬─────────┘   │
+  │           │                     │              │
+  │     GPADL-backed memory (guest-allocated)      │
+  │                                                │
+  │  Signal: guest → host  │  Signal: host → guest │
+  │  Target VP: set at open time                   │
+  └────────────────────────────────────────────────┘


Nit:

put a box around GPADL-backed memory (guest-allocated)

The | | between Incoming Ring and Outgoing Ring don't line up

Guide/src/reference/architecture/vmbus/channels.md

Why is this change being made? - The VMBus channel model — identity tuples, ring buffer pairs, subchannels, target VP, and lifecycle — is foundational to understanding any VMBus device but was not documented in the Guide. - VP index vs APIC ID vs Linux CPU number confusion comes up frequently in debugging. What changed? - New Guide page: `Guide/src/reference/architecture/vmbus/channels.md` covering channel identity (`OfferKey`), ring buffer pairs, subchannel lifecycle (mermaid state diagram), target VP semantics, VP index vs CPU number vs APIC ID clarification, ring buffer model, and key types. - New `VMBus Architecture` section in SUMMARY.md. - Expanded rustdoc for [`VmbusDevice`](https://openvmm.dev/rustdoc/linux/vmbus_channel/channel/trait.VmbusDevice.html) — `max_subchannels()` and `retarget_vp()` now document semantics and usage patterns. - Expanded rustdoc for [`ChannelControl`](https://openvmm.dev/rustdoc/linux/vmbus_channel/channel/struct.ChannelControl.html) — documents error handling for `enable_subchannels()` and device protocol handler usage context. How was the change tested? - ✅ `cargo doc --no-deps -p vmbus_channel` — no warnings - ✅ Guide cross-links verified Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds foundational documentation for the VMBus channel model (identity tuples, ring buffers, subchannels, target VP semantics, and lifecycle) to reduce recurring debugging confusion around VP/CPU/APIC identifiers, and aligns relevant rustdoc with the documented behavior.

Changes:

Adds a new Guide reference page describing the VMBus channel model (channels.md) and wires it into the Guide navigation.
Expands rustdoc on VmbusDevice and ChannelControl to clarify subchannel limits, VP retargeting semantics, and expected caller behavior.
Documents a concrete error-mapping expectation for enable_subchannels() over-limit requests.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
vm/devices/vmbus/vmbus_channel/src/channel.rs	Clarifies rustdoc around subchannel limits, subchannel enablement, and interrupt retargeting callbacks.
Guide/src/reference/architecture/vmbus/channels.md	New architecture doc page explaining VMBus channel/subchannel concepts and VP identifier mapping.
Guide/src/SUMMARY.md	Adds a new navigation section for VMBus architecture docs and links the new Channels page.

vm/devices/vmbus/vmbus_channel/src/channel.rs

@@ -140,8 +159,10 @@ impl ChannelControl {
    ///
    /// If more than `count` subchannels are already enabled, this does nothing.


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

mattkur · 2026-03-13T22:11:50Z

Guide/src/reference/architecture/vmbus/channels.md

+This is used when VPs come online/offline (e.g., CPU hot-remove) and
+the guest needs to rebalance channel assignments.
+
+### VP index, CPU number, and APIC ID


@jstarks , @smalis-msft, @chris-oo , could you review this section? I am not confident in its correctness, but this is based on what I have observed.

smalis-msft · 2026-03-16T14:51:57Z

Guide/src/reference/architecture/vmbus/channels.md

+VMBus server at offer time. The channel's lifecycle is: **offered →
+opened → active → closed**.
+
+```text


Does this diagram really add anything?

Personally: I'm a visual person, so like having the boxes with an incoming and outgoing ring. This helps me conceptualize VMBus channels as rings.

smalis-msft · 2026-03-16T14:53:26Z

Guide/src/reference/architecture/vmbus/channels.md

+This is used when VPs come online/offline (e.g., CPU hot-remove) and
+the guest needs to rebalance channel assignments.
+
+### VP index, CPU number, and APIC ID


I feel like this could be its own page somewhere else with just a link from here. It's an important topic, and not vmbus specific

Agreed. Probably makes sense to move it to the page I add #2975, or even its own section. I can refactor immediately after I take all these PRs to avoid too much structural churn. Do you mind confirming correctness of this section as written?

I think it's right but Chris should double check

will-j-wright

This all seems right to me, but @SvenGroot might want to take a read through for correctness.

mattkur mentioned this pull request Mar 13, 2026

guide: VMBus channels, StorVSP subchannels, and CPU scheduling docs #2978

Draft

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

This was referenced Mar 13, 2026

guide: document OpenHCL CPU scheduling model #2975

Open

guide: document StorVSP channels and subchannels #2976

Open

mattkur commented Mar 13, 2026

View reviewed changes

mattkur force-pushed the guide/vmbus-channels branch from e4c7bcd to 14db471 Compare March 13, 2026 19:15

Merge branch 'main' into guide/vmbus-channels

ca9b240

mattkur marked this pull request as ready for review March 13, 2026 19:21

mattkur requested review from a team as code owners March 13, 2026 19:21

Copilot AI review requested due to automatic review settings March 13, 2026 19:21

Copilot started reviewing on behalf of mattkur March 13, 2026 19:21 View session

Copilot AI reviewed Mar 13, 2026

View reviewed changes

vm/devices/vmbus/vmbus_channel/src/channel.rs Outdated

@@ -140,8 +159,10 @@ impl ChannelControl {

///

/// If more than `count` subchannels are already enabled, this does nothing.

fixup: clarify enable_subchannels no-op wording

ea92721

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

alandau approved these changes Mar 13, 2026

View reviewed changes

mattkur commented Mar 13, 2026

View reviewed changes

smalis-msft reviewed Mar 16, 2026

View reviewed changes

will-j-wright approved these changes Mar 16, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

guide: document VMBus channel model#2977

guide: document VMBus channel model#2977
mattkur wants to merge 3 commits intomicrosoft:mainfrom
mattkur:guide/vmbus-channels

mattkur commented Mar 13, 2026 •

edited

Loading

Uh oh!

mattkur Mar 13, 2026

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

mattkur Mar 13, 2026

Uh oh!

smalis-msft Mar 16, 2026

Uh oh!

mattkur Mar 16, 2026

Uh oh!

smalis-msft Mar 16, 2026

Uh oh!

mattkur Mar 16, 2026

Uh oh!

smalis-msft Mar 16, 2026

Uh oh!

will-j-wright left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		@@ -140,8 +159,10 @@ impl ChannelControl {
		///
		/// If more than `count` subchannels are already enabled, this does nothing.

Conversation

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

Uh oh!

Changes

Uh oh!

mattkur Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

mattkur Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

smalis-msft Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

mattkur Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

smalis-msft Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

mattkur Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

smalis-msft Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

will-j-wright left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mattkur commented Mar 13, 2026 •

edited

Loading