"Fossies" - the Fresh Open Source Software Archive

Member "qemu-5.2.0/docs/hyperv.txt" (8 Dec 2020, 9553 Bytes) of package /linux/misc/qemu-5.2.0.tar.xz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "hyperv.txt": 5.1.0_vs_5.2.0.

    1 Hyper-V Enlightenments
    2 ======================
    5 1. Description
    6 ===============
    7 In some cases when implementing a hardware interface in software is slow, KVM
    8 implements its own paravirtualized interfaces. This works well for Linux as
    9 guest support for such features is added simultaneously with the feature itself.
   10 It may, however, be hard-to-impossible to add support for these interfaces to
   11 proprietary OSes, namely, Microsoft Windows.
   13 KVM on x86 implements Hyper-V Enlightenments for Windows guests. These features
   14 make Windows and Hyper-V guests think they're running on top of a Hyper-V
   15 compatible hypervisor and use Hyper-V specific features.
   18 2. Setup
   19 =========
   20 No Hyper-V enlightenments are enabled by default by either KVM or QEMU. In
   21 QEMU, individual enlightenments can be enabled through CPU flags, e.g:
   23   qemu-system-x86_64 --enable-kvm --cpu host,hv_relaxed,hv_vpindex,hv_time, ...
   25 Sometimes there are dependencies between enlightenments, QEMU is supposed to
   26 check that the supplied configuration is sane.
   28 When any set of the Hyper-V enlightenments is enabled, QEMU changes hypervisor
   29 identification (CPUID 0x40000000..0x4000000A) to Hyper-V. KVM identification
   30 and features are kept in leaves 0x40000100..0x40000101.
   33 3. Existing enlightenments
   34 ===========================
   36 3.1. hv-relaxed
   37 ================
   38 This feature tells guest OS to disable watchdog timeouts as it is running on a
   39 hypervisor. It is known that some Windows versions will do this even when they
   40 see 'hypervisor' CPU flag.
   42 3.2. hv-vapic
   43 ==============
   44 Provides so-called VP Assist page MSR to guest allowing it to work with APIC
   45 more efficiently. In particular, this enlightenment allows paravirtualized
   46 (exit-less) EOI processing.
   48 3.3. hv-spinlocks=xxx
   49 ======================
   50 Enables paravirtualized spinlocks. The parameter indicates how many times
   51 spinlock acquisition should be attempted before indicating the situation to the
   52 hypervisor. A special value 0xffffffff indicates "never notify".
   54 3.4. hv-vpindex
   55 ================
   56 Provides HV_X64_MSR_VP_INDEX (0x40000002) MSR to the guest which has Virtual
   57 processor index information. This enlightenment makes sense in conjunction with
   58 hv-synic, hv-stimer and other enlightenments which require the guest to know its
   59 Virtual Processor indices (e.g. when VP index needs to be passed in a
   60 hypercall).
   62 3.5. hv-runtime
   63 ================
   64 Provides HV_X64_MSR_VP_RUNTIME (0x40000010) MSR to the guest. The MSR keeps the
   65 virtual processor run time in 100ns units. This gives guest operating system an
   66 idea of how much time was 'stolen' from it (when the virtual CPU was preempted
   67 to perform some other work).
   69 3.6. hv-crash
   70 ==============
   71 Provides HV_X64_MSR_CRASH_P0..HV_X64_MSR_CRASH_P5 (0x40000100..0x40000105) and
   72 HV_X64_MSR_CRASH_CTL (0x40000105) MSRs to the guest. These MSRs are written to
   73 by the guest when it crashes, HV_X64_MSR_CRASH_P0..HV_X64_MSR_CRASH_P5 MSRs
   74 contain additional crash information. This information is outputted in QEMU log
   75 and through QAPI.
   76 Note: unlike under genuine Hyper-V, write to HV_X64_MSR_CRASH_CTL causes guest
   77 to shutdown. This effectively blocks crash dump generation by Windows.
   79 3.7. hv-time
   80 =============
   81 Enables two Hyper-V-specific clocksources available to the guest: MSR-based
   82 Hyper-V clocksource (HV_X64_MSR_TIME_REF_COUNT, 0x40000020) and Reference TSC
   83 page (enabled via MSR HV_X64_MSR_REFERENCE_TSC, 0x40000021). Both clocksources
   84 are per-guest, Reference TSC page clocksource allows for exit-less time stamp
   85 readings. Using this enlightenment leads to significant speedup of all timestamp
   86 related operations.
   88 3.8. hv-synic
   89 ==============
   90 Enables Hyper-V Synthetic interrupt controller - an extension of a local APIC.
   91 When enabled, this enlightenment provides additional communication facilities
   92 to the guest: SynIC messages and Events. This is a pre-requisite for
   93 implementing VMBus devices (not yet in QEMU). Additionally, this enlightenment
   94 is needed to enable Hyper-V synthetic timers. SynIC is controlled through MSRs
   95 HV_X64_MSR_SCONTROL..HV_X64_MSR_EOM (0x40000080..0x40000084) and
   96 HV_X64_MSR_SINT0..HV_X64_MSR_SINT15 (0x40000090..0x4000009F)
   98 Requires: hv-vpindex
  100 3.9. hv-stimer
  101 ===============
  102 Enables Hyper-V synthetic timers. There are four synthetic timers per virtual
  103 CPU controlled through HV_X64_MSR_STIMER0_CONFIG..HV_X64_MSR_STIMER3_COUNT
  104 (0x400000B0..0x400000B7) MSRs. These timers can work either in single-shot or
  105 periodic mode. It is known that certain Windows versions revert to using HPET
  106 (or even RTC when HPET is unavailable) extensively when this enlightenment is
  107 not provided; this can lead to significant CPU consumption, even when virtual
  108 CPU is idle.
  110 Requires: hv-vpindex, hv-synic, hv-time
  112 3.10. hv-tlbflush
  113 ==================
  114 Enables paravirtualized TLB shoot-down mechanism. On x86 architecture, remote
  115 TLB flush procedure requires sending IPIs and waiting for other CPUs to perform
  116 local TLB flush. In virtualized environment some virtual CPUs may not even be
  117 scheduled at the time of the call and may not require flushing (or, flushing
  118 may be postponed until the virtual CPU is scheduled). hv-tlbflush enlightenment
  119 implements TLB shoot-down through hypervisor enabling the optimization.
  121 Requires: hv-vpindex
  123 3.11. hv-ipi
  124 =============
  125 Enables paravirtualized IPI send mechanism. HvCallSendSyntheticClusterIpi
  126 hypercall may target more than 64 virtual CPUs simultaneously, doing the same
  127 through APIC requires more than one access (and thus exit to the hypervisor).
  129 Requires: hv-vpindex
  131 3.12. hv-vendor-id=xxx
  132 =======================
  133 This changes Hyper-V identification in CPUID 0x40000000.EBX-EDX from the default
  134 "Microsoft Hv". The parameter should be no longer than 12 characters. According
  135 to the specification, guests shouldn't use this information and it is unknown
  136 if there is a Windows version which acts differently.
  137 Note: hv-vendor-id is not an enlightenment and thus doesn't enable Hyper-V
  138 identification when specified without some other enlightenment.
  140 3.13. hv-reset
  141 ===============
  142 Provides HV_X64_MSR_RESET (0x40000003) MSR to the guest allowing it to reset
  143 itself by writing to it. Even when this MSR is enabled, it is not a recommended
  144 way for Windows to perform system reboot and thus it may not be used.
  146 3.14. hv-frequencies
  147 ============================================
  148 Provides HV_X64_MSR_TSC_FREQUENCY (0x40000022) and HV_X64_MSR_APIC_FREQUENCY
  149 (0x40000023) allowing the guest to get its TSC/APIC frequencies without doing
  150 measurements.
  152 3.15 hv-reenlightenment
  153 ========================
  154 The enlightenment is nested specific, it targets Hyper-V on KVM guests. When
  155 enabled, it provides HV_X64_MSR_REENLIGHTENMENT_CONTROL (0x40000106),
  157 (0x40000108) MSRs allowing the guest to get notified when TSC frequency changes
  158 (only happens on migration) and keep using old frequency (through emulation in
  159 the hypervisor) until it is ready to switch to the new one. This, in conjunction
  160 with hv-frequencies, allows Hyper-V on KVM to pass stable clocksource (Reference
  161 TSC page) to its own guests.
  163 Recommended: hv-frequencies
  165 3.16. hv-evmcs
  166 ===============
  167 The enlightenment is nested specific, it targets Hyper-V on KVM guests. When
  168 enabled, it provides Enlightened VMCS feature to the guest. The feature
  169 implements paravirtualized protocol between L0 (KVM) and L1 (Hyper-V)
  170 hypervisors making L2 exits to the hypervisor faster. The feature is Intel-only.
  171 Note: some virtualization features (e.g. Posted Interrupts) are disabled when
  172 hv-evmcs is enabled. It may make sense to measure your nested workload with and
  173 without the feature to find out if enabling it is beneficial.
  175 Requires: hv-vapic
  177 3.17. hv-stimer-direct
  178 =======================
  179 Hyper-V specification allows synthetic timer operation in two modes: "classic",
  180 when expiration event is delivered as SynIC message and "direct", when the event
  181 is delivered via normal interrupt. It is known that nested Hyper-V can only
  182 use synthetic timers in direct mode and thus 'hv-stimer-direct' needs to be
  183 enabled.
  185 Requires: hv-vpindex, hv-synic, hv-time, hv-stimer
  187 3.17. hv-no-nonarch-coresharing=on/off/auto
  188 ===========================================
  189 This enlightenment tells guest OS that virtual processors will never share a
  190 physical core unless they are reported as sibling SMT threads. This information
  191 is required by Windows and Hyper-V guests to properly mitigate SMT related CPU
  192 vulnerabilities.
  193 When the option is set to 'auto' QEMU will enable the feature only when KVM
  194 reports that non-architectural coresharing is impossible, this means that
  195 hyper-threading is not supported or completely disabled on the host. This
  196 setting also prevents migration as SMT settings on the destination may differ.
  197 When the option is set to 'on' QEMU will always enable the feature, regardless
  198 of host setup. To keep guests secure, this can only be used in conjunction with
  199 exposing correct vCPU topology and vCPU pinning.
  201 4. Development features
  202 ========================
  203 In some cases (e.g. during development) it may make sense to use QEMU in
  204 'pass-through' mode and give Windows guests all enlightenments currently
  205 supported by KVM. This pass-through mode is enabled by "hv-passthrough" CPU
  206 flag.
  207 Note: enabling this flag effectively prevents migration as supported features
  208 may differ between target and destination.
  211 4. Useful links
  212 ================
  213 Hyper-V Top Level Functional specification and other information:
  214 https://github.com/MicrosoftDocs/Virtualization-Documentation