virt/hyperv/vmbus.rst

5 VMbus is a software construct provided by Hyper-V to guest VMs.  It
6 consists of a control path and common facilities used by synthetic
15 VMbus is modeled in Linux as a bus, with the expected /sys/bus/vmbus
16 entry in a running Linux guest.  The VMbus driver (drivers/hv/vmbus_drv.c)
18 registers itself as a Linux bus driver.  It implements the standard
21 Most synthetic devices offered by Hyper-V have a corresponding Linux
35 * Hyper-V online backup (a.k.a. VSS)
39 synthetic devices are limited to a single instance per VM.  Not
40 listed above are a small number of synthetic devices offered by
42 does not have a driver.
45 devices.  "VSP" refers to the Hyper-V code that implements a
54 An instance of a synthetic device uses VMbus channels to communicate
56 for passing messages.   Most synthetic devices use a single channel,
61 buffers from a university data structures textbook.  If the read
63 empty, so a full ring buffer always has at least one byte unused.
71 ring buffer consists of a header page (4 Kbytes) with the read and
76 VMbus control path as a GPA Descriptor List (GPADL).  See function
81 that makes up the ring itself, and 3) a second mapping of the memory
85 Once a copy operation has completed, the read or write index may
92 passed to Hyper-V as a 4 Kbyte area.  But the memory for the actual
93 ring must be aligned to PAGE_SIZE and have a size that is a multiple
95 a portion of the header page is unused and not communicated to
98 Hyper-V enforces a limit on the aggregate amount of guest memory
100 that a rogue guest can't force the consumption of excessive host
107 All VMbus messages have a standard header that includes the message
108 length, the offset of the message payload, some flags, and a
114 * Unidirectional:  Either side sends a message and does not
115   expect a response message
116 * Request/response:  One side (usually the guest) sends a message
117   and expects a response
119 The transactionID (a.k.a. "requestID") is for matching requests &
121 flight simultaneously, so the guest specifies a transactionID when
122 sending a request.  Hyper-V sends back the same transactionID in the
126 example, a message sent from the storvsc driver might be "execute
127 this SCSI command".   If a message also implies some data transfer
130 specified as a separate data buffer that the Hyper-V host will
131 access as a DMA operation.  The former case is used when the size of
135 data is larger, a separate data buffer is used.  In this case, the
136 control message contains a list of GPAs that describe the data
150    associated with a list of GPAs.  The GPAs must describe a
158 the Hyper-V host is no longer a valid assumption.  The drivers for
162 messages read by the guest from the "in" ring buffer are copied to a
170 VMbus provides a mechanism for the guest to interrupt the host when
171 the guest has queued new messages in a ring buffer.  The host
175 unnecessary.  If a guest sends an excessive number of unnecessary
177 execution for a few seconds to prevent a denial-of-service attack.
179 Similarly, the host will interrupt the guest when it sends a new
180 message on the VMbus control path, or when a VMbus channel "in" ring
183 interrupts in Linux.  This model works well on arm64 where a single
190 The guest CPU that a VMbus channel will interrupt is selected by the
212 The CPU that a VMbus channel will interrupt can be seen in
215 by writing a new value to this sysfs entry.  Because the interrupt
220 An online CPU in a Linux guest may not be taken offline if it has
226 When a guest CPU receives a VMbus interrupt from the host, the
228 channel interrupts by calling vmbus_chan_sched(), which looks at a
236 correctly even if an interrupt is received on a CPU other than the
239 will interrupt the assigned CPU.  But when the CPU assigned to a
242 even if there is a time lag before Hyper-V starts interrupting the
247 Hyper-V and the Linux guest have a separate message-passing path
249 path does not use a VMbus channel.  See vmbus_post_msg() and
254 the guest and Hyper-V agree on a VMbus protocol version they will
260 is configured to have. Each VMbus device type has a fixed GUID
262 identified by a GUID. The offer message from Hyper-V contains
264 There is one offer message for each device instance, so a VM with
281 giving the host a list of GPAs for the ring buffer memory.  See
295 The Hyper-V host can send a "rescind" message to the guest to
296 remove a device that was previously offered. Linux drivers must
297 handle such a rescind message at any time. Rescinding a device
299 down the device and remove it. Once a synthetic device is
301 its previous existence. Such a device might be re-added later,