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
52   spinlock acquisition should be attempted before indicating the situation to the
55 ``hv-vpindex``
58   hv-synic, hv-stimer and other enlightenments which require the guest to know its
62 ``hv-runtime``
64   virtual processor run time in 100ns units. This gives guest operating system an
65   idea of how much time was 'stolen' from it (when the virtual CPU was preempted
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
111   scheduled at the time of the call and may not require flushing (or, flushing
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
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
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