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:
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
31   processor registers or in memory shared between the Linux guest and
32   Hyper-V.   On x86/x64, hypercalls use a Hyper-V specific calling
36 * Synthetic register access: Hyper-V implements a variety of
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
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
61 Sharing Memory
62 --------------
63 Many aspects are communication between Hyper-V and Linux are based
64 on sharing memory.  Such sharing is generally accomplished as
67 * Linux allocates memory from its physical address space using
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
72   single GPA is sufficient.   Larger shared areas require a list of
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,
80   and creates a virtual mapping that it can use to access the memory.
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
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
98 uses the usual approach of allocating guest memory and telling
99 Hyper-V the GPA of the allocated memory.  But Hyper-V then replaces
100 that physical memory page with a page it has allocated, and the
101 original physical memory page is no longer accessible in the guest
102 VM.  Linux may access the memory normally as if it were the memory
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
113 a shared page or remove an overlay page after the new kernel is
115 Hyper-V does not provide a single "set everything" operation to
118 the crash/panic path still has holes in cleanup because some shared
119 pages are set using per-CPU synthetic registers and there's no
120 mechanism to revoke the shared pages for CPUs other than the CPU
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
197 "Hyper-V/Azure CORE AND DRIVERS" and "DRM DRIVER FOR HYPERV
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.