Document the microsoft,message-connection-id property for VMBus DeviceTree
node. This property allows specifying the connection ID used for
communication between host and guest.
Signed-off-by: Hardik Garg <hargar@linux.microsoft.com>
---
v3: https://lore.kernel.org/all/6a92ca86-ad6b-4d49-af6e-1ed7651b8ab8@linux.microsoft.com
v2: https://lore.kernel.org/all/096edaf7-cc90-42b6-aff4-c5f088574e1e@linux.microsoft.com
v1: https://lore.kernel.org/all/6acee4bf-cb04-43b9-9476-e8d811d26dfd@linux.microsoft.com
---
Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml b/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml
index 0bea4f5287ce..615b48bd6a8b 100644
--- a/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml
+++ b/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml
@@ -17,6 +17,14 @@ properties:
compatible:
const: microsoft,vmbus
+ microsoft,message-connection-id:
+ description: |
+ VMBus message connection ID to be used for communication between host and
+ guest. If not specified, defaults to VMBUS_MESSAGE_CONNECTION_ID_4 (4) for
+ protocol version VERSION_WIN10_V5 and above, or VMBUS_MESSAGE_CONNECTION_ID
+ (1) for older versions.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
ranges: true
'#address-cells':
@@ -55,6 +63,7 @@ examples:
vmbus@ff0000000 {
compatible = "microsoft,vmbus";
+ microsoft,message-connection-id = <4>;
#address-cells = <2>;
#size-cells = <1>;
ranges = <0x0f 0xf0000000 0x0f 0xf0000000 0x10000000>;
--
2.40.4On Thu, Jun 19, 2025 at 04:06:34PM GMT, Hardik Garg wrote: > Document the microsoft,message-connection-id property for VMBus DeviceTree > node. This property allows specifying the connection ID used for What is a connection ID and why it cannot be inferred from existing system API? > communication between host and guest. > > Signed-off-by: Hardik Garg <hargar@linux.microsoft.com> > --- > v3: https://lore.kernel.org/all/6a92ca86-ad6b-4d49-af6e-1ed7651b8ab8@linux.microsoft.com > v2: https://lore.kernel.org/all/096edaf7-cc90-42b6-aff4-c5f088574e1e@linux.microsoft.com > v1: https://lore.kernel.org/all/6acee4bf-cb04-43b9-9476-e8d811d26dfd@linux.microsoft.com > --- > Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml | 9 +++++++++ > 1 file changed, 9 insertions(+) > > diff --git a/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml b/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml > index 0bea4f5287ce..615b48bd6a8b 100644 > --- a/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml > +++ b/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml > @@ -17,6 +17,14 @@ properties: > compatible: > const: microsoft,vmbus There's a reason why you have here generic property - this is generic and/or discoverable and/or whatever software interface. Adding now more properties, just because you made it generic, is not the way. > > + microsoft,message-connection-id: > + description: | Drop | > + VMBus message connection ID to be used for communication between host and > + guest. If not specified, defaults to VMBUS_MESSAGE_CONNECTION_ID_4 (4) for > + protocol version VERSION_WIN10_V5 and above, or VMBUS_MESSAGE_CONNECTION_ID > + (1) for older versions. Missing constraints, defaults, if this stays, but frankly speaking it looks really not appropriate, considering lack of any explanation in the binding or in commit msg. Best regards, Krzysztof
Thank you for your review, Krzysztof. I apologize for the delay in my response. >> What is a connection ID and why it cannot be inferred from existing >> system API? The connection-id determines which hypervisor communication channel the guest should use to talk to the VMBus host. Reading from DeviceTree allows platforms to specify their preferred communication channel, making it more flexible (I will add this detail in the commit message). Presently, this value is hardcoded and there is no existing API to read it. >> There's a reason why you have here generic property - this is generic >> and/or discoverable and/or whatever software interface. Adding now more >> properties, just because you made it generic, is not the way. Presently the value is hardcoded and we want to provide a functionality to the user to specify their prefered communication channel. This is a virtualized hardware property for us. >> Drop | I will remove "|". >> Missing constraints, defaults, if this stays, but frankly speaking it >> looks really not appropriate, considering lack of any explanation in the >> binding or in commit msg. I will add constraints, and defaults. Please let me know if there are any other issues that I should fix with the next version of the patch and thank you again for the review. Regards, Hardik
On 14/07/2025 09:48, Hardik Garg wrote: > Thank you for your review, Krzysztof. I apologize for the delay in > my response. You got review after 8 hours. You respond after 3 weeks. > >>> What is a connection ID and why it cannot be inferred from existing >>> system API? > > The connection-id determines which hypervisor communication channel the > guest should use to talk to the VMBus host. Reading from DeviceTree allows > platforms to specify their preferred communication channel, making it more > flexible (I will add this detail in the commit message). Presently, this We don't add properties to make things flexible. > value is hardcoded and there is no existing API to read it. > >>> There's a reason why you have here generic property - this is generic >>> and/or discoverable and/or whatever software interface. Adding now more >>> properties, just because you made it generic, is not the way. > > Presently the value is hardcoded and we want to provide a functionality to > the user to specify their prefered communication channel. This is a > virtualized hardware property for us. That's not really acceptable reason. With such approach I would add 100 properties to make various things "flexible". Best regards, Krzysztof
>>>> What is a connection ID and why it cannot be inferred from existing >>>> system API? >> The connection-id determines which hypervisor communication channel the >> guest should use to talk to the VMBus host. Reading from DeviceTree allows >> platforms to specify their preferred communication channel, making it more >> flexible (I will add this detail in the commit message). Presently, this >> We don't add properties to make things flexible. You're right. I should have explained better. The connection ID is a hardware configuration detail that defines which specific VMBus channel is used for host-guest communication. This value is configured by the host and passed to the guest through the host's device tree. Different hypervisor versions and configurations may require different channels, and this needs to be specified by the platform. >>>> There's a reason why you have here generic property - this is generic >>>> and/or discoverable and/or whatever software interface. Adding now more >>>> properties, just because you made it generic, is not the way. >> Presently the value is hardcoded and we want to provide a functionality to >> the user to specify their prefered communication channel. This is a >> virtualized hardware property for us. >> That's not really acceptable reason. With such approach I would add 100 >> properties to make various things "flexible". I understand your concern. Let me clarify: this isn't about making things flexible for flexibility's sake. The connection ID is a fundamental hardware configuration parameter that is set by the host and must be matched in the guest. The host configures this value in its device tree and shares it with the guest. Without the correct channel ID, the VMBus communication fails. Different hypervisor configurations require different channels, and this cannot be automatically discovered. Would you prefer if we handled this configuration through a different mechanism? I'm open to suggestions. Thanks, Hardik
On 16/07/2025 06:42, Hardik Garg wrote: >>>>> What is a connection ID and why it cannot be inferred from existing >>>>> system API? > >>> The connection-id determines which hypervisor communication channel the >>> guest should use to talk to the VMBus host. Reading from DeviceTree allows >>> platforms to specify their preferred communication channel, making it more >>> flexible (I will add this detail in the commit message). Presently, this > >>> We don't add properties to make things flexible. > > You're right. I should have explained better. The connection ID is a hardware > configuration detail that defines which specific VMBus channel is used for > host-guest communication. This value is configured by the host and passed to > the guest through the host's device tree. Different hypervisor versions and > configurations may require different channels, and this needs to be specified > by the platform. Host is supposed to have multiple guests, so this feels like you are going to prepare for each guest different DTS with different connection ID. This feels like poor design. DTS is supposed to be relatively static configuration, not runtime choice vmguestid+1. The guest cannot access other configuration channels, can it? If it can, it would mean it can eavesdrop on other guests? So obviously it cannot. Therefore from guest point of view this is completely redundant. Guest cannot use any other value, thus guest should not configure it. The guest has only one channel and uses only this one which gets to right place to the host. Best regards, Krzysztof
> Host is supposed to have multiple guests, so this feels like you are > going to prepare for each guest different DTS with different connection > ID. This feels like poor design. DTS is supposed to be relatively static > configuration, not runtime choice vmguestid+1. > The guest cannot access other configuration channels, can it? If it can, > it would mean it can eavesdrop on other guests? So obviously it cannot. > Therefore from guest point of view this is completely redundant. Guest > cannot use any other value, thus guest should not configure it. The > guest has only one channel and uses only this one which gets to right > place to the host. Thank you for your feedback. Let me explain the connection ID in more detail: 1. Message Port Architecture: - The connection ID specifies which Hyper-V hypervisor message port (mailbox slot) to use for communication between the host and guest - The hypervisor has multiple message ports, but historically VMBus only used one - With the introduction of VTL2 (Virtual Trust Level 2), the control plane can now be hosted in VTL2, requiring different message ports for communication 2. Control Plane Communication: - The VMBus control plane on the host needs to communicate with the VMBus driver in the guest - When the control plane is hosted in VTL2, it requires a different message port than the standard communication path - The connection ID tells the guest whether to use the standard or alternate message port for this control plane communication 3. Message Processing: - Each message is tagged with an ID - If the guest uses an incorrect ID, the host won't recognize the message and will drop it - This is not about choosing between multiple available channels - it's about using the correct mailbox slot for communication 4. Security and Isolation: - Each guest has its private hypervisor mailbox - Multiple guests using the same connection ID cannot interfere with each other - The connection ID is more like a "root ID" that helps enumerate devices on the bus, not a channel selector between guests 5. Dynamic Nature: - The connection ID is specified when the guest starts running - The host can change it during VM lifecycle events (reset/reboot) - This is why the VMBus driver needs to know the connection ID every time the kernel starts - The ID might be different from what it was during the last guest run Thanks, Hardik
On 23/07/2025 05:08, Hardik Garg wrote: >> Host is supposed to have multiple guests, so this feels like you are >> going to prepare for each guest different DTS with different connection >> ID. This feels like poor design. DTS is supposed to be relatively static >> configuration, not runtime choice vmguestid+1. > >> The guest cannot access other configuration channels, can it? If it can, >> it would mean it can eavesdrop on other guests? So obviously it cannot. >> Therefore from guest point of view this is completely redundant. Guest >> cannot use any other value, thus guest should not configure it. The >> guest has only one channel and uses only this one which gets to right >> place to the host. > > Thank you for your feedback. Let me explain the connection ID in more detail: > > 1. Message Port Architecture: > - The connection ID specifies which Hyper-V hypervisor message port (mailbox slot) to use for communication between the host and guest > - The hypervisor has multiple message ports, but historically VMBus only used one > - With the introduction of VTL2 (Virtual Trust Level 2), the control plane can now be hosted in VTL2, requiring different message ports for communication > > 2. Control Plane Communication: > - The VMBus control plane on the host needs to communicate with the VMBus driver in the guest > - When the control plane is hosted in VTL2, it requires a different message port than the standard communication path > - The connection ID tells the guest whether to use the standard or alternate message port for this control plane communication > > 3. Message Processing: > - Each message is tagged with an ID > - If the guest uses an incorrect ID, the host won't recognize the message and will drop it > - This is not about choosing between multiple available channels - it's about using the correct mailbox slot for communication > Don't paste me specs in response to questions, but answer specific questions. > 4. Security and Isolation: > - Each guest has its private hypervisor mailbox > - Multiple guests using the same connection ID cannot interfere with each other Then all guests can use the same value, 0, making this property redundant. > - The connection ID is more like a "root ID" that helps enumerate devices on the bus, not a channel selector between guests > > 5. Dynamic Nature: > - The connection ID is specified when the guest starts running > - The host can change it during VM lifecycle events (reset/reboot) So not suitable for DT. DT is a static data. You cannot just keep changing existing DT to match whatever you want runtime. > - This is why the VMBus driver needs to know the connection ID every time the kernel starts > - The ID might be different from what it was during the last guest run Best regards, Krzysztof
> Then all guests can use the same value, 0, making this property redundant. No, they cannot use the same value. The protocol requires different connection IDs for different communication paths. For example, a guest communicating with a VTL0 control plane uses a different connection ID than one communicating with a VTL2 control plane. The host specifies this value based on the guest's configuration, and there is no other discovery method available to determine the correct connection ID. > So not suitable for DT. DT is a static data. You cannot just keep changing existing DT to match whatever you want runtime. From the guest's perspective, this data is completely static - it doesn't change over the lifetime of the guest. The guest always looks it up in DT. The hypervisor merely populates this value in the guest's DT. Once set, it remains fixed for that guest instance, so this data is not dynamic, it's completely fixed for the guest. Thanks, Hardik
On 25/07/2025 00:12, Hardik Garg wrote: >> Then all guests can use the same value, 0, making this property redundant. > > No, they cannot use the same value. The protocol requires different connection IDs for different communication paths. > For example, a guest communicating with a VTL0 control plane uses a different connection ID than one communicating with > a VTL2 control plane. The host specifies this value based on the guest's configuration, and there is no other discovery > method available to determine the correct connection ID. You completely removed entire thread and discussion making it difficult to connect to one of 100 or more discussions I am doing. Plus wrap your emails according to netiquette rules. The guest should not care about the value. Otherwise what if guests decides to ignore your DT property and start using other value? Sniffing other guests traffic? Causing conflicts or denial of service? If different values are important for the host, then all guests should use whatever 0 which will map to different values on host by other means of your protocol. Best regards, Krzysztof
© 2016 - 2025 Red Hat, Inc.