1 .. SPDX-License-Identifier: GPL-2.0
2
3 Overview
4 ========
5 The Linux kernel contains a variety of code fo
6 enlightened guest on Microsoft's Hyper-V hyper
7 consists primarily of a bare-metal hypervisor
8 management service running in the parent parti
9 equivalent to KVM and QEMU, for example). Gue
10 partitions. In this documentation, references
11 encompass both the hypervisor and the VMM serv
12 distinction about which functionality is provi
13 component.
14
15 Hyper-V runs on x86/x64 and arm64 architecture
16 are supported on both. The functionality and
17 generally the same on both architectures unles
18
19 Linux Guest Communication with Hyper-V
20 --------------------------------------
21 Linux guests communicate with Hyper-V in four
22
23 * Implicit traps: As defined by the x86/x64 or
24 some guest actions trap to Hyper-V. Hyper-V
25 returns control to the guest. This behavior
26 to the Linux kernel.
27
28 * Explicit hypercalls: Linux makes an explicit
29 Hyper-V, passing parameters. Hyper-V perfor
30 and returns control to the caller. Paramete
31 processor registers or in memory shared betw
32 Hyper-V. On x86/x64, hypercalls use a Hype
33 sequence. On arm64, hypercalls use the ARM
34 sequence.
35
36 * Synthetic register access: Hyper-V implement
37 synthetic registers. On x86/x64 these regis
38 the guest, and the Linux kernel can read or
39 the normal mechanisms defined by the x86/x64
40 arm64, these synthetic registers must be acc
41 hypercalls.
42
43 * VMBus: VMBus is a higher-level software cons
44 the other 3 mechanisms. It is a message pas
45 the Hyper-V host and the Linux guest. It us
46 between Hyper-V and the guest, along with va
47 mechanisms.
48
49 The first three communication mechanisms are d
50 `Hyper-V Top Level Functional Spec (TLFS)`_.
51 general Hyper-V functionality and provides det
52 and synthetic registers. The TLFS is currentl
53 x86/x64 architecture only.
54
55 .. _Hyper-V Top Level Functional Spec (TLFS):
56
57 VMBus is not documented. This documentation p
58 overview of VMBus and how it works, but the de
59 only from the code.
60
61 Sharing Memory
62 --------------
63 Many aspects are communication between Hyper-V
64 on sharing memory. Such sharing is generally
65 follows:
66
67 * Linux allocates memory from its physical add
68 standard Linux mechanisms.
69
70 * Linux tells Hyper-V the guest physical addre
71 allocated memory. Many shared areas are kep
72 single GPA is sufficient. Larger shared ar
73 GPAs, which usually do not need to be contig
74 physical address space. How Hyper-V is told
75 of GPAs varies. In some cases, a single GPA
76 synthetic register. In other cases, a GPA o
77 in a VMBus message.
78
79 * Hyper-V translates the GPAs into "real" phys
80 and creates a virtual mapping that it can us
81
82 * Linux can later revoke sharing it has previo
83 telling Hyper-V to set the shared GPA to zer
84
85 Hyper-V operates with a page size of 4 Kbytes.
86 Hyper-V may be in the form of page numbers, an
87 range of 4 Kbytes. Since the Linux guest page
88 also 4 Kbytes, the mapping from guest page to
89 On arm64, Hyper-V supports guests with 4/16/64
90 defined by the arm64 architecture. If Linux
91 Kbyte pages, Linux code must be careful to com
92 only in terms of 4 Kbyte pages. HV_HYP_PAGE_S
93 are used in code that communicates with Hyper-
94 correctly in all configurations.
95
96 As described in the TLFS, a few memory pages s
97 and the Linux guest are "overlay" pages. With
98 uses the usual approach of allocating guest me
99 Hyper-V the GPA of the allocated memory. But
100 that physical memory page with a page it has a
101 original physical memory page is no longer acc
102 VM. Linux may access the memory normally as i
103 that it originally allocated. The "overlay" b
104 only because the contents of the page (as seen
105 the time that Linux originally establishes the
106 overlay page is inserted. Similarly, the cont
107 revokes the sharing, in which case Hyper-V rem
108 and the guest page originally allocated by Lin
109 again.
110
111 Before Linux does a kexec to a kdump kernel or
112 memory shared with Hyper-V should be revoked.
113 a shared page or remove an overlay page after
114 using the page for a different purpose, corrup
115 Hyper-V does not provide a single "set everyth
116 guest VMs, so Linux code must individually rev
117 doing kexec. See hv_kexec_handler() and hv_c
118 the crash/panic path still has holes in cleanu
119 pages are set using per-CPU synthetic register
120 mechanism to revoke the shared pages for CPUs
121 running the panic path.
122
123 CPU Management
124 --------------
125 Hyper-V does not have a ability to hot-add or
126 from a running VM. However, Windows Server 20
127 earlier versions may provide guests with ACPI
128 more CPUs than are actually present in the VM.
129 treats these additional CPUs as potential hot-
130 them as such even though Hyper-V will never ac
131 Starting in Windows Server 2022 Hyper-V, the A
132 only the CPUs actually present in the VM, so L
133 any hot-add CPUs.
134
135 A Linux guest CPU may be taken offline using t
136 mechanisms, provided no VMBus channel interrup
137 the CPU. See the section on VMBus Interrupts
138 on how VMBus channel interrupts can be re-assi
139 taking a CPU offline.
140
141 32-bit and 64-bit
142 -----------------
143 On x86/x64, Hyper-V supports 32-bit and 64-bit
144 will build and run in either version. While th
145 expected to work, it is used rarely and may su
146 regressions.
147
148 On arm64, Hyper-V supports only 64-bit guests.
149
150 Endian-ness
151 -----------
152 All communication between Hyper-V and guest VM
153 format on both x86/x64 and arm64. Big-endian
154 supported by Hyper-V, and Linux code does not
155 when accessing data shared with Hyper-V.
156
157 Versioning
158 ----------
159 Current Linux kernels operate correctly with o
160 Hyper-V back to Windows Server 2012 Hyper-V. S
161 on the original Hyper-V release in Windows Ser
162 has been removed.
163
164 A Linux guest on Hyper-V outputs in dmesg the
165 it is running on. This version is in the form
166 number and is for display purposes only. Linux
167 test this version number at runtime to determi
168 and functionality. Hyper-V indicates feature/f
169 via flags in synthetic MSRs that Hyper-V provi
170 and the guest code tests these flags.
171
172 VMBus has its own protocol version that is neg
173 initial VMBus connection from the guest to Hyp
174 number is also output to dmesg during boot. T
175 is checked in a few places in the code to dete
176 functionality is present.
177
178 Furthermore, each synthetic device on VMBus al
179 version that is separate from the VMBus protoc
180 drivers for these synthetic devices typically
181 protocol version, and may test that protocol v
182 if specific device functionality is present.
183
184 Code Packaging
185 --------------
186 Hyper-V related code appears in the Linux kern
187 main areas:
188
189 1. drivers/hv
190
191 2. arch/x86/hyperv and arch/arm64/hyperv
192
193 3. individual device driver areas such as driv
194 drivers/clocksource, etc.
195
196 A few miscellaneous files appear elsewhere. Se
197 "Hyper-V/Azure CORE AND DRIVERS" and "DRM DRIV
198 SYNTHETIC VIDEO DEVICE" in the MAINTAINERS fil
199
200 The code in #1 and #2 is built only when CONFI
201 Similarly, the code for most Hyper-V related d
202 when CONFIG_HYPERV is set.
203
204 Most Hyper-V related code in #1 and #3 can be
205 The architecture specific code in #2 must be b
206 drivers/hv/hv_common.c is low-level code that
207 architectures and must be built-in.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.