system/i386/hyperv.rst

1 Hyper-V Enlightenments
6 -----------
11 It may, however, be hard-to-impossible to add support for these interfaces to
14 KVM on x86 implements Hyper-V Enlightenments for Windows guests. These features
15 make Windows and Hyper-V guests think they're running on top of a Hyper-V
16 compatible hypervisor and use Hyper-V specific features.
20 -----
22 No Hyper-V enlightenments are enabled by default by either KVM or QEMU. In
25 .. parsed-literal::
27   |qemu_system| --enable-kvm --cpu host,hv_relaxed,hv_vpindex,hv_time, ...
32 When any set of the Hyper-V enlightenments is enabled, QEMU changes hypervisor
33 identification (CPUID 0x40000000..0x4000000A) to Hyper-V. KVM identification
38 -----------------------
40 ``hv-relaxed``
45 ``hv-vapic``
46   Provides so-called VP Assist page MSR to guest allowing it to work with APIC
48   (exit-less) EOI processing.
50 ``hv-spinlocks`` = xxx
55 ``hv-vpindex``
58   hv-synic, hv-stimer and other enlightenments which require the guest to know its
62 ``hv-runtime``
68 ``hv-crash``
74   Note: unlike under genuine Hyper-V, write to HV_X64_MSR_CRASH_CTL causes guest
77 ``hv-time``
78   Enables two Hyper-V-specific clocksources available to the guest: MSR-based
79   Hyper-V clocksource (HV_X64_MSR_TIME_REF_COUNT, 0x40000020) and Reference TSC
81   are per-guest, Reference TSC page clocksource allows for exit-less time stamp
85 ``hv-synic``
86   Enables Hyper-V Synthetic interrupt controller - an extension of a local APIC.
88   to the guest: SynIC messages and Events. This is a pre-requisite for
90   is needed to enable Hyper-V synthetic timers. SynIC is controlled through MSRs
94   Requires: ``hv-vpindex``
96 ``hv-stimer``
97   Enables Hyper-V synthetic timers. There are four synthetic timers per virtual
99   (0x400000B0..0x400000B7) MSRs. These timers can work either in single-shot or
105   Requires: ``hv-vpindex``, ``hv-synic``, ``hv-time``
107 ``hv-tlbflush``
108   Enables paravirtualized TLB shoot-down mechanism. On x86 architecture, remote
112   may be postponed until the virtual CPU is scheduled). hv-tlbflush enlightenment
113   implements TLB shoot-down through hypervisor enabling the optimization.
115   Requires: ``hv-vpindex``
117 ``hv-ipi``
122   Requires: ``hv-vpindex``
124 ``hv-vendor-id`` = xxx
125   This changes Hyper-V identification in CPUID 0x40000000.EBX-EDX from the default
128   if there is a Windows version which acts differently.
129   Note: hv-vendor-id is not an enlightenment and thus doesn't enable Hyper-V
132 ``hv-reset``
137 ``hv-frequencies``
142 ``hv-reenlightenment``
143   The enlightenment is nested specific, it targets Hyper-V on KVM guests. When
149   with ``hv-frequencies``, allows Hyper-V on KVM to pass stable clocksource
152   Note, KVM doesn't fully support re-enlightenment notifications and doesn't
153   emulate TSC accesses after migration so 'tsc-frequency=' CPU option also has to
157   Recommended: ``hv-frequencies``
159 ``hv-evmcs``
160   The enlightenment is nested specific, it targets Hyper-V on KVM guests. When
161   enabled, it provides Enlightened VMCS version 1 feature to the guest. The feature
162   implements paravirtualized protocol between L0 (KVM) and L1 (Hyper-V)
163   hypervisors making L2 exits to the hypervisor faster. The feature is Intel-only.
166   hv-evmcs is enabled. It may make sense to measure your nested workload with and
169   Requires: ``hv-vapic``
171 ``hv-stimer-direct``
172   Hyper-V specification allows synthetic timer operation in two modes: "classic",
174   is delivered via normal interrupt. It is known that nested Hyper-V can only
175   use synthetic timers in direct mode and thus ``hv-stimer-direct`` needs to be
178   Requires: ``hv-vpindex``, ``hv-synic``, ``hv-time``, ``hv-stimer``
180 ``hv-avic`` (``hv-apicv``)
181   The enlightenment allows to use Hyper-V SynIC with hardware APICv/AVIC enabled.
182   Normally, Hyper-V SynIC disables these hardware feature and suggests the guest
187 ``hv-no-nonarch-coresharing`` = on/off/auto
190   is required by Windows and Hyper-V guests to properly mitigate SMT related CPU
194   reports that non-architectural coresharing is impossible, this means that
195   hyper-threading is not supported or completely disabled on the host. This
201 ``hv-version-id-build``, ``hv-version-id-major``, ``hv-version-id-minor``, ``hv-version-id-spack``,…
202   This changes Hyper-V version identification in CPUID 0x40000002.EAX-EDX from the
205   - ``hv-version-id-build`` sets 'Build Number' (32 bits)
206   - ``hv-version-id-major`` sets 'Major Version' (16 bits)
207   - ``hv-version-id-minor`` sets 'Minor Version' (16 bits)
208   - ``hv-version-id-spack`` sets 'Service Pack' (32 bits)
209   - ``hv-version-id-sbranch`` sets 'Service Branch' (8 bits)
210   - ``hv-version-id-snumber`` sets 'Service Number' (24 bits)
212   Note: hv-version-id-* are not enlightenments and thus don't enable Hyper-V
215 ``hv-syndbg``
216   Enables Hyper-V synthetic debugger interface, this is a special interface used
224   This enlightenment requires a VMBus device (-device vmbus-bridge,irq=15).
226 …Requires: ``hv-relaxed``, ``hv_time``, ``hv-vapic``, ``hv-vpindex``, ``hv-synic``, ``hv-runtime``,…
228 ``hv-emsr-bitmap``
229   The enlightenment is nested specific, it targets Hyper-V on KVM guests. When
230   enabled, it allows L0 (KVM) and L1 (Hyper-V) hypervisors to collaborate to
231   avoid unnecessary updates to L2 MSR-Bitmap upon vmexits. While the protocol is
233   Enlightened VMCS (``hv-evmcs``) feature to also be enabled.
235   Recommended: ``hv-evmcs`` (Intel)
237 ``hv-xmm-input``
238   Hyper-V specification allows to pass parameters for certain hypercalls using XMM
242 ``hv-tlbflush-ext``
243   Allow for extended GVA ranges to be passed to Hyper-V TLB flush hypercalls
246   Requires: ``hv-tlbflush``
248 ``hv-tlbflush-direct``
249   The enlightenment is nested specific, it targets Hyper-V on KVM guests. When
251   guest without the need to exit to L1 (Hyper-V) hypervisor. While the feature is
253   Enlightened VMCS (``hv-evmcs``) feature to also be enabled.
255   Requires: ``hv-vapic``
257   Recommended: ``hv-evmcs`` (Intel)
260 ----------------------
262 ``hv-passthrough``
264   'pass-through' mode and give Windows guests all enlightenments currently
267   Note: ``hv-passthrough`` flag only enables enlightenments which are known to QEMU
268   (have corresponding 'hv-' flag) and copies ``hv-spinlocks`` and ``hv-vendor-id``
269   values from KVM to QEMU. ``hv-passthrough`` overrides all other 'hv-' settings on
272   Note: ``hv-passthrough`` does not enable ``hv-syndbg`` which can prevent certain
274   ``hv-syndbg`` can be enabled additionally.
276   Note: ``hv-passthrough`` effectively prevents migration as the list of enabled
279 ``hv-enforce-cpuid``
280   By default, KVM allows the guest to use all currently supported Hyper-V
281   enlightenments when Hyper-V CPUID interface was exposed, regardless of if
282   some features were not announced in guest visible CPUIDs. ``hv-enforce-cpuid``
283   feature alters this behavior and only allows the guest to use exposed Hyper-V
287 ---------------
289 To achieve the best performance of Windows and Hyper-V guests and unless there
291 emulating specific Hyper-V version, ...), it is recommended to enable all
292 currently implemented Hyper-V enlightenments with the following exceptions:
294 - ``hv-syndbg``, ``hv-passthrough``, ``hv-enforce-cpuid`` should not be enabled
296 - ``hv-reset`` can be avoided as modern Hyper-V versions don't expose it.
297 - ``hv-evmcs`` can (and should) be enabled on Intel CPUs only. While the feature
298   is only used in nested configurations (Hyper-V, WSL2), enabling it for regular
300 - ``hv-no-nonarch-coresharing`` must only be enabled if vCPUs are properly pinned
301   so no non-architectural core sharing is possible.
302 - ``hv-vendor-id``, ``hv-version-id-build``, ``hv-version-id-major``,
303   ``hv-version-id-minor``, ``hv-version-id-spack``, ``hv-version-id-sbranch``,
304   ``hv-version-id-snumber`` can be left unchanged, guests are not supposed to
305   behave differently when different Hyper-V version is presented to them.
306 - ``hv-crash`` must only be enabled if the crash information is consumed via
309 - ``hv-reenlightenment`` can only be used on hardware which supports TSC
311 - ``hv-spinlocks`` should be set to e.g. 0xfff when host CPUs are overcommited
314 - ``hv-avic``/``hv-apicv`` should not be enabled if the hardware does not
318 ------------
319 Hyper-V Top Level Functional specification and other information:
321 - https://github.com/MicrosoftDocs/Virtualization-Documentation
322 - https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/tlfs/tlfs