From ea1169bca45b45764753ba9122c34f5a1157bb09 Mon Sep 17 00:00:00 2001 From: Mohamed Mediouni Date: Fri, 27 Mar 2026 02:11:50 +0100 Subject: [PATCH] docs: add WHPX section with initial info Signed-off-by: Mohamed Mediouni Link: https://lore.kernel.org/r/20260327011152.4126-3-mohamed@unpredictable.fr Signed-off-by: Paolo Bonzini --- MAINTAINERS | 1 + docs/system/index.rst | 1 + docs/system/whpx.rst | 144 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 146 insertions(+) create mode 100644 docs/system/whpx.rst diff --git a/MAINTAINERS b/MAINTAINERS index cd8ba14450..eb7132e39d 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -582,6 +582,7 @@ F: include/system/whpx.h F: include/system/whpx-accel-ops.h F: include/system/whpx-common.h F: include/system/whpx-internal.h +F: docs/system/whpx.rst MSHV M: Magnus Kulke diff --git a/docs/system/index.rst b/docs/system/index.rst index bb948e2993..4509630fa4 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -40,6 +40,7 @@ or Hypervisor.Framework. confidential-guest-support igvm nitro + whpx vm-templating sriov qemu-colo diff --git a/docs/system/whpx.rst b/docs/system/whpx.rst new file mode 100644 index 0000000000..3e1979028c --- /dev/null +++ b/docs/system/whpx.rst @@ -0,0 +1,144 @@ +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.