Document the microsoft,message-connection-id property for VMBus DeviceTree node. The connection-id is a hardware-level identifier that specifies which Hyper-V message port (or mailbox slot) the guest should use to communicate with the VMBus control plane. Historically, VMBus always used a single, fixed connection ID. However, with the introduction of Virtual Trust Level 2 (VTL2) support, the control plane can now reside in a different trust level, requiring the guest to communicate through a different message port. This connection-id is determined by the hypervisor based on the status of VMBus relay. From the guests perspective, it is completely static for the lifetime of that VM instance, it never changes at runtime. Once the kernel boots, it must read this value to establish communication with the correct VMBus control plane. There is currently no system API, or discoverable interface that allows the guest to determine this value dynamically.
Each guest has a private hypervisor mailbox and cannot access any other guests communication path. Using an incorrect connection ID does not allow eavesdropping or cause interference, it only results in failed VMBus initialization because the host drops messages sent to an unexpected port. Thus, exposing the correct connection ID to the guest is safe and necessary for correct initialization. Signed-off-by: Hardik Garg <[email protected]> --- v4: https://lore.kernel.org/all/[email protected] v3: https://lore.kernel.org/all/[email protected] v2: https://lore.kernel.org/all/[email protected] v1: https://lore.kernel.org/all/[email protected] --- .../devicetree/bindings/bus/microsoft,vmbus.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml b/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml index 0bea4f5287ce..4745c2b89ac5 100644 --- a/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml +++ b/Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml @@ -17,6 +17,17 @@ properties: compatible: const: microsoft,vmbus + microsoft,message-connection-id: + description: + connection-id is a hardware-level identifier that specifies + which Hyper-V message port (or mailbox slot) the guest should + use to communicate with the VMBus control plane. When this + property is not present, the driver selects the connection ID + based on the protocol version (4 for VERSION_WIN10_V5 and + newer, or 1 for older versions). + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + ranges: true '#address-cells': @@ -55,6 +66,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.34.1
