| 1 | Windows Hypervisor Platform |
| 2 | =========================== |
| 3 | |
| 4 | Windows Hypervisor Platform is the Windows API for use of |
| 5 | third-party virtual machine monitors with hardware acceleration |
| 6 | on Hyper-V. |
| 7 | |
| 8 | It's implemented on top of ``Vid``, which is itself implemented |
| 9 | on the same set of hypercalls as the ``mshv`` driver on Linux. |
| 10 | |
| 11 | WHPX is the name of the Windows Hypervisor Platform accelerator |
| 12 | backend in QEMU. It enables using QEMU with hardware acceleration |
| 13 | on both x86_64 and arm64 Windows machines. |
| 14 | |
| 15 | Prerequisites |
| 16 | ------------- |
| 17 | |
| 18 | WHPX requires the Windows Hypervisor Platform feature to be installed. |
| 19 | |
| 20 | Installation |
| 21 | ^^^^^^^^^^^^ |
| 22 | On client editions of Windows, that means installation through |
| 23 | Windows Features (``optionalfeatures.exe``). On server editions, |
| 24 | feature-based installation in Server Manager can be used. |
| 25 | |
| 26 | Alternatively, command line installation is also possible through: |
| 27 | ``DISM /online /Enable-Feature /FeatureName:HypervisorPlatform /All`` |
| 28 | |
| 29 | Minimum OS version |
| 30 | ^^^^^^^^^^^^^^^^^^ |
| 31 | |
| 32 | On x86_64, QEMU's Windows Hypervisor Platform backend is tested |
| 33 | starting from Windows 10 version 2004. Earlier Windows 10 releases |
| 34 | *might* work but are not tested. |
| 35 | |
| 36 | On arm64, Windows 11 24H2 with the April 2025 optional updates |
| 37 | or May 2025 security updates is the minimum required release. |
| 38 | |
| 39 | Prior releases of Windows 11 version 24H2 on ARM64 shipped |
| 40 | with a pre-release version of the Windows Hypervisor Platform |
| 41 | API, which is not supported in QEMU. |
| 42 | |
| 43 | Quick Start |
| 44 | ----------- |
| 45 | |
| 46 | Launching a virtual machine on x86_64 with WHPX acceleration:: |
| 47 | |
| 48 | $ qemu-system-x86_64.exe -accel whpx -M pc \ |
| 49 | -smp cores=2 -m 2G -device ich9-usb-ehci1 \ |
| 50 | -device usb-tablet -hda OS.qcow2 |
| 51 | |
| 52 | Launching a virtual machine on arm64 with WHPX acceleration:: |
| 53 | |
| 54 | $ qemu-system-aarch64.exe -accel whpx -M virt \ |
| 55 | -cpu host -smp cores=2 -m 2G \ |
| 56 | -bios edk2-aarch64-code.fd \ |
| 57 | -device ramfb -device nec-usb-xhci \ |
| 58 | -device usb-kbd -device usb-tablet \ |
| 59 | -hda OS.qcow2 |
| 60 | |
| 61 | On arm64, for non-Windows guests, ``-device virtio-gpu-pci`` provides |
| 62 | additional functionality compared to ``-device ramfb``, but is |
| 63 | incompatible with Windows's UEFI GOP implementation, which |
| 64 | expects a linear framebuffer to be available. |
| 65 | |
| 66 | Accelerator options |
| 67 | -------------------- |
| 68 | |
| 69 | x86_64 |
| 70 | ^^^^^^ |
| 71 | |
| 72 | ``-trace whpx_unsupported_msr_access`` can be used to log accesses |
| 73 | to undocumented MSRs. |
| 74 | |
| 75 | ``-d invalid_mem`` allows to trace accesses to unmapped |
| 76 | GPAs. |
| 77 | |
| 78 | ``-accel whpx,ssd=off`` disables the separate security domain feature, |
| 79 | as in a BTB flush when entering/exiting the guest. This results in a |
| 80 | significant MMIO performance increase at the detriment of security |
| 81 | mitigations. |
| 82 | |
| 83 | Known issues on x86_64 |
| 84 | ---------------------- |
| 85 | |
| 86 | Guests using legacy VGA modes |
| 87 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 88 | |
| 89 | In guests using VGA modes that QEMU doesn't pass through framebuffer |
| 90 | memory for, performance will be quite suboptimal. |
| 91 | |
| 92 | Workaround: for affected guests, use a more modern graphics mode. |
| 93 | Alternatively, use TCG to run those guests. |
| 94 | |
| 95 | Guests using MMX, SSE or AVX instructions for MMIO |
| 96 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 97 | |
| 98 | Currently, ``target/i386/emulate`` does not support guests that use |
| 99 | MMX, SSE or AVX instructions for access to MMIO memory ranges. |
| 100 | |
| 101 | Attempts to run such guests will result in an ``Unimplemented handler`` |
| 102 | warning for MMX and a failure to decode for newer instructions. |
| 103 | |
| 104 | PIC interrupts on Windows 10 |
| 105 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 106 | |
| 107 | On Windows 10, a legacy PIC interrupt injected does not wake the guest |
| 108 | from an HLT when using the Hyper-V provided interrupt controller. |
| 109 | |
| 110 | As such, on Windows 10, using the Hyper-V interrupt controller is |
| 111 | disabled by default. You can enable it via ``-M q35,pic=off`` which |
| 112 | disables the PIC. In that configuration, using a UEFI is recommended. |
| 113 | |
| 114 | On this release, ``-M kernel-irqchip=`` is not expected to be manually |
| 115 | set during normal operation. It remains as a debugging option. |
| 116 | |
| 117 | Known issues on Windows 11 |
| 118 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 119 | |
| 120 | arm64 |
| 121 | ----- |
| 122 | |
| 123 | ISA feature support |
| 124 | ^^^^^^^^^^^^^^^^^^^ |
| 125 | |
| 126 | SVE and SME are not currently supported. |