docs: add WHPX section with initial info
Signed-off-by: Mohamed Mediouni <mohamed@unpredictable.fr> Link: https://lore.kernel.org/r/20260327011152.4126-3-mohamed@unpredictable.fr Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Mohamed Mediouni committed
Mar 27, 2026 at 02:11 UTC
ea1169bca45b45764753ba9122c34f5a1157bb09
3 files changed
+146
MAINTAINERS
+1
@@ -582,6 +582,7 @@ F: include/system/whpx.h
582
F: include/system/whpx-accel-ops.h
583
F: include/system/whpx-common.h
584
F: include/system/whpx-internal.h
585
+F: docs/system/whpx.rst
586
587
MSHV
588
M: Magnus Kulke <magnuskulke@linux.microsoft.com>
docs/system/index.rst
+1
@@ -40,6 +40,7 @@ or Hypervisor.Framework.
40
confidential-guest-support
41
igvm
42
nitro
43
+ whpx
44
vm-templating
45
sriov
46
qemu-colo
docs/system/whpx.rst
new
+144
@@ -0,0 +1,144 @@
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
+Some tracing 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
+Known issues on x86_64
79
+----------------------
80
+
81
+Guests using legacy VGA modes
82
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
83
+
84
+In guests using VGA modes that QEMU doesn't pass through framebuffer
85
+memory for, performance will be quite suboptimal.
86
+
87
+Workaround: for affected guests, use a more modern graphics mode.
88
+Alternatively, use TCG to run those guests.
89
+
90
+Guests using MMX, SSE or AVX instructions for MMIO
91
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
92
+
93
+Currently, ``target/i386/emulate`` does not support guests that use
94
+MMX, SSE or AVX instructions for access to MMIO memory ranges.
95
+
96
+Attempts to run such guests will result in an ``Unimplemented handler``
97
+warning for MMX and a failure to decode for newer instructions.
98
+
99
+``-M isapc``
100
+^^^^^^^^^^^^
101
+
102
+``-M isapc`` doesn't disable the Hyper-V LAPIC on its own yet. To
103
+be able to use that machine, use ``-accel whpx,hyperv=off,kernel-irqchip=off``.
104
+
105
+However, in QEMU 11.0, the guest will still be a 64-bit x86
106
+ISA machine with all the corresponding CPUID leaves exposed.
107
+
108
+gdbstub
109
+^^^^^^^
110
+
111
+As save/restore of xsave state is not currently present, state
112
+exposed through GDB will be incomplete.
113
+
114
+The same also applies to ``info registers``.
115
+
116
+``-cpu type`` ignored
117
+^^^^^^^^^^^^^^^^^^^^^
118
+
119
+In this release, -cpu is an ignored argument.
120
+
121
+PIC interrupts on Windows 10
122
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
123
+
124
+On Windows 10, a legacy PIC interrupt injected does not wake the guest
125
+from an HLT when using the Hyper-V provided interrupt controller.
126
+
127
+This has been addressed in QEMU 11.0 on Windows 11 platforms but
128
+functionality to make it available on Windows 10 isn't present.
129
+
130
+Workaround: for affected use cases, use ``-M kernel-irqchip=off``.
131
+
132
+Known issues on Windows 11
133
+^^^^^^^^^^^^^^^^^^^^^^^^^^
134
+
135
+Nested virtualisation-specific Hyper-V enlightenments are not
136
+currently exposed.
137
+
138
+arm64
139
+-----
140
+
141
+ISA feature support
142
+^^^^^^^^^^^^^^^^^^^
143
+
144
+SVE and SME are not currently supported.