virt/hyperv/overview.rst

1 .. SPDX-License-Identifier: GPL-2.0
6 enlightened guest on Microsoft's Hyper-V hypervisor.  Hyper-V
7 consists primarily of a bare-metal hypervisor plus a virtual machine
10 partitions.  In this documentation, references to Hyper-V usually
15 Hyper-V runs on x86/x64 and arm64 architectures, and Linux guests
16 are supported on both.  The functionality and behavior of Hyper-V is
19 Linux Guest Communication with Hyper-V
20 --------------------------------------
21 Linux guests communicate with Hyper-V in four different ways:
23 * Implicit traps: As defined by the x86/x64 or arm64 architecture,
24   some guest actions trap to Hyper-V.  Hyper-V emulates the action and
29   Hyper-V, passing parameters.  Hyper-V performs the requested action
32   Hyper-V.   On x86/x64, hypercalls use a Hyper-V specific calling
36 * Synthetic register access: Hyper-V implements a variety of
37   synthetic registers.  On x86/x64 these registers appear as MSRs in
39   the normal mechanisms defined by the x86/x64 architecture.  On
43 * VMBus: VMBus is a higher-level software construct that is built on
45   the Hyper-V host and the Linux guest.  It uses memory that is shared
46   between Hyper-V and the guest, along with various signaling
50 `Hyper-V Top Level Functional Spec (TLFS)`_.  The TLFS describes
51 general Hyper-V functionality and provides details on the hypercalls
53 x86/x64 architecture only.
55 .. _Hyper-V Top Level Functional Spec (TLFS): https://docs.microsoft.com/en-us/virtualization/hyper…
57 VMBus is not documented.  This documentation provides a high-level
62 --------------
63 Many aspects are communication between Hyper-V and Linux are based
70 * Linux tells Hyper-V the guest physical address (GPA) of the
71   allocated memory.  Many shared areas are kept to 1 page so that a
74   physical address space.  How Hyper-V is told about the GPA or list
79 * Hyper-V translates the GPAs into "real" physical memory addresses,
83   telling Hyper-V to set the shared GPA to zero.
85 Hyper-V operates with a page size of 4 Kbytes. GPAs communicated to
86 Hyper-V may be in the form of page numbers, and always describe a
87 range of 4 Kbytes.  Since the Linux guest page size on x86/x64 is
88 also 4 Kbytes, the mapping from guest page to Hyper-V page is 1-to-1.
89 On arm64, Hyper-V supports guests with 4/16/64 Kbyte pages as
91 Kbyte pages, Linux code must be careful to communicate with Hyper-V
93 are used in code that communicates with Hyper-V so that it works
96 As described in the TLFS, a few memory pages shared between Hyper-V
99 Hyper-V the GPA of the allocated memory.  But Hyper-V then replaces
107 revokes the sharing, in which case Hyper-V removes the overlay page,
112 memory shared with Hyper-V should be revoked.  Hyper-V could modify
115 Hyper-V does not provide a single "set everything" operation to
119 pages are set using per-CPU synthetic registers and there's no
124 --------------
125 Hyper-V does not have a ability to hot-add or hot-remove a CPU
126 from a running VM.  However, Windows Server 2019 Hyper-V and
129 treats these additional CPUs as potential hot-add CPUs, and reports
130 them as such even though Hyper-V will never actually hot-add them.
131 Starting in Windows Server 2022 Hyper-V, the ACPI tables reflect
133 any hot-add CPUs.
138 on how VMBus channel interrupts can be re-assigned to permit
141 32-bit and 64-bit
142 -----------------
143 On x86/x64, Hyper-V supports 32-bit and 64-bit guests, and Linux
144 will build and run in either version. While the 32-bit version is
148 On arm64, Hyper-V supports only 64-bit guests.
150 Endian-ness
151 -----------
152 All communication between Hyper-V and guest VMs uses Little-Endian
153 format on both x86/x64 and arm64.  Big-endian format on arm64 is not
154 supported by Hyper-V, and Linux code does not use endian-ness macros
155 when accessing data shared with Hyper-V.
158 ----------
160 Hyper-V back to Windows Server 2012 Hyper-V. Support for running
161 on the original Hyper-V release in Windows Server 2008/2008 R2
164 A Linux guest on Hyper-V outputs in dmesg the version of Hyper-V
168 and functionality. Hyper-V indicates feature/function availability
169 via flags in synthetic MSRs that Hyper-V provides to the guest,
173 initial VMBus connection from the guest to Hyper-V. This version
185 --------------
186 Hyper-V related code appears in the Linux kernel code tree in three
189 1. drivers/hv
197 "Hyper-V/Azure CORE AND DRIVERS" and "DRM DRIVER FOR HYPERV
200 The code in #1 and #2 is built only when CONFIG_HYPERV is set.
201 Similarly, the code for most Hyper-V related drivers is built only
204 Most Hyper-V related code in #1 and #3 can be built as a module.
205 The architecture specific code in #2 must be built-in.  Also,
206 drivers/hv/hv_common.c is low-level code that is common across
207 architectures and must be built-in.