| Windows Hypervisor Platform |
| =========================== |
| |
| Windows Hypervisor Platform is the Windows API for use of |
| third-party virtual machine monitors with hardware acceleration |
| on Hyper-V. |
| |
| It's implemented on top of ``Vid``, which is itself implemented |
| on the same set of hypercalls as the ``mshv`` driver on Linux. |
| |
| WHPX is the name of the Windows Hypervisor Platform accelerator |
| backend in QEMU. It enables using QEMU with hardware acceleration |
| on both x86_64 and arm64 Windows machines. |
| |
| Prerequisites |
| ------------- |
| |
| WHPX requires the Windows Hypervisor Platform feature to be installed. |
| |
| Installation |
| ^^^^^^^^^^^^ |
| On client editions of Windows, that means installation through |
| Windows Features (``optionalfeatures.exe``). On server editions, |
| feature-based installation in Server Manager can be used. |
| |
| Alternatively, command line installation is also possible through: |
| ``DISM /online /Enable-Feature /FeatureName:HypervisorPlatform /All`` |
| |
| Minimum OS version |
| ^^^^^^^^^^^^^^^^^^ |
| |
| On x86_64, QEMU's Windows Hypervisor Platform backend is tested |
| starting from Windows 10 version 2004. Earlier Windows 10 releases |
| *might* work but are not tested. |
| |
| On arm64, Windows 11 24H2 with the April 2025 optional updates |
| or May 2025 security updates is the minimum required release. |
| |
| Prior releases of Windows 11 version 24H2 on ARM64 shipped |
| with a pre-release version of the Windows Hypervisor Platform |
| API, which is not supported in QEMU. |
| |
| Quick Start |
| ----------- |
| |
| Launching a virtual machine on x86_64 with WHPX acceleration:: |
| |
| $ qemu-system-x86_64.exe -accel whpx -M pc \ |
| -smp cores=2 -m 2G -device ich9-usb-ehci1 \ |
| -device usb-tablet -hda OS.qcow2 |
| |
| Launching a virtual machine on arm64 with WHPX acceleration:: |
| |
| $ qemu-system-aarch64.exe -accel whpx -M virt \ |
| -cpu host -smp cores=2 -m 2G \ |
| -bios edk2-aarch64-code.fd \ |
| -device ramfb -device nec-usb-xhci \ |
| -device usb-kbd -device usb-tablet \ |
| -hda OS.qcow2 |
| |
| On arm64, for non-Windows guests, ``-device virtio-gpu-pci`` provides |
| additional functionality compared to ``-device ramfb``, but is |
| incompatible with Windows's UEFI GOP implementation, which |
| expects a linear framebuffer to be available. |
| |
| Some tracing options |
| -------------------- |
| |
| x86_64 |
| ^^^^^^ |
| |
| ``-trace whpx_unsupported_msr_access`` can be used to log accesses |
| to undocumented MSRs. |
| |
| ``-d invalid_mem`` allows to trace accesses to unmapped |
| GPAs. |
| |
| Known issues on x86_64 |
| ---------------------- |
| |
| Guests using legacy VGA modes |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| In guests using VGA modes that QEMU doesn't pass through framebuffer |
| memory for, performance will be quite suboptimal. |
| |
| Workaround: for affected guests, use a more modern graphics mode. |
| Alternatively, use TCG to run those guests. |
| |
| Guests using MMX, SSE or AVX instructions for MMIO |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Currently, ``target/i386/emulate`` does not support guests that use |
| MMX, SSE or AVX instructions for access to MMIO memory ranges. |
| |
| Attempts to run such guests will result in an ``Unimplemented handler`` |
| warning for MMX and a failure to decode for newer instructions. |
| |
| ``-M isapc`` |
| ^^^^^^^^^^^^ |
| |
| ``-M isapc`` doesn't disable the Hyper-V LAPIC on its own yet. To |
| be able to use that machine, use ``-accel whpx,hyperv=off,kernel-irqchip=off``. |
| |
| However, in QEMU 11.0, the guest will still be a 64-bit x86 |
| ISA machine with all the corresponding CPUID leaves exposed. |
| |
| gdbstub |
| ^^^^^^^ |
| |
| As save/restore of xsave state is not currently present, state |
| exposed through GDB will be incomplete. |
| |
| The same also applies to ``info registers``. |
| |
| ``-cpu type`` ignored |
| ^^^^^^^^^^^^^^^^^^^^^ |
| |
| In this release, -cpu is an ignored argument. |
| |
| PIC interrupts on Windows 10 |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| On Windows 10, a legacy PIC interrupt injected does not wake the guest |
| from an HLT when using the Hyper-V provided interrupt controller. |
| |
| This has been addressed in QEMU 11.0 on Windows 11 platforms but |
| functionality to make it available on Windows 10 isn't present. |
| |
| Workaround: for affected use cases, use ``-M kernel-irqchip=off``. |
| |
| Known issues on Windows 11 |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Nested virtualisation-specific Hyper-V enlightenments are not |
| currently exposed. |
| |
| arm64 |
| ----- |
| |
| ISA feature support |
| ^^^^^^^^^^^^^^^^^^^ |
| |
| SVE and SME are not currently supported. |
