[PATCH v6 0/4] whpx: i386: even more updates

[PATCH v6 0/4] whpx: i386: even more updates

[Mohamed Mediouni]

Demoting some warnings that appeared too often
and adding some documentation.

v5 to v6:

Remove emulation of SLDT and STR from this revision.
Will continue seeing what to emulate or not for QEMU 11.1.

The issues there turned out that target/i386/emulate causes
state corruption across the board when using the i386-softmmu
target. So disable WHPX support for that target as a workaround.

Mohamed Mediouni (4):
  meson.build: remove i386-softmmu WHPX support
  docs: add WHPX section with initial info
  whpx: i386: trace unsupported MSR accesses
  target/i386: emulate: remove redundant logging for unmapped MMIO
    access

 MAINTAINERS                   |   1 +
 docs/system/index.rst         |   1 +
 docs/system/whpx.rst          | 144 ++++++++++++++++++++++++++++++++++
 meson.build                   |   3 +-
 target/i386/emulate/x86_mmu.c |   3 -
 target/i386/whpx/trace-events |   1 +
 target/i386/whpx/trace.h      |   2 +
 target/i386/whpx/whpx-all.c   |   5 +-
 8 files changed, 154 insertions(+), 6 deletions(-)
 create mode 100644 docs/system/whpx.rst
 create mode 100644 target/i386/whpx/trace-events
 create mode 100644 target/i386/whpx/trace.h

-- 
2.50.1 (Apple Git-155)

[PATCH v6 1/4] meson.build: remove i386-softmmu WHPX support

[Mohamed Mediouni]

target/i386/emulate is pretty much incompatible
with i386-softmmu and fixing that doesn't look
worthwhile given the binary unification goals...

Signed-off-by: Mohamed Mediouni <mohamed@unpredictable.fr>
---
 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/meson.build b/meson.build
index e6f17dd5f7..6f77309075 100644
--- a/meson.build
+++ b/meson.build
@@ -314,7 +314,7 @@ elif cpu == 'x86_64'
     'CONFIG_HVF': ['x86_64-softmmu'],
     'CONFIG_NITRO': ['x86_64-softmmu'],
     'CONFIG_NVMM': ['i386-softmmu', 'x86_64-softmmu'],
-    'CONFIG_WHPX': ['i386-softmmu', 'x86_64-softmmu'],
+    'CONFIG_WHPX': ['x86_64-softmmu'],
     'CONFIG_MSHV': ['x86_64-softmmu'],
   }
 endif
-- 
2.50.1 (Apple Git-155)

[PATCH v6 2/4] docs: add WHPX section with initial info

[Mohamed Mediouni]

Signed-off-by: Mohamed Mediouni <mohamed@unpredictable.fr>
---
 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 <magnuskulke@linux.microsoft.com>
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..2f906ec586
--- /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 fuctionality 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.
-- 
2.50.1 (Apple Git-155)

Re: [PATCH v6 2/4] docs: add WHPX section with initial info

[Paolo Bonzini]

On 3/27/26 02:11, Mohamed Mediouni wrote:
> Signed-off-by: Mohamed Mediouni <mohamed@unpredictable.fr>
> ---
>   MAINTAINERS           |   1 +
>   docs/system/index.rst |   1 +
>   docs/system/whpx.rst  | 144 ++++++++++++++++++++++++++++++++++++++++++
>   3 files changed, 146 insertions(+)
>   create mode 100644 docs/system/whpx.rst

Needs a few fixes since this is rST not Markdown:

diff --git a/docs/system/whpx.rst b/docs/system/whpx.rst
index 2f906ec5866..3e1979028c9 100644
--- a/docs/system/whpx.rst
+++ b/docs/system/whpx.rst
@@ -5,8 +5,8 @@ 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.
+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
@@ -20,11 +20,11 @@ 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,
+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`
+``DISM /online /Enable-Feature /FeatureName:HypervisorPlatform /All``
  
  Minimum OS version
  ^^^^^^^^^^^^^^^^^^
@@ -58,8 +58,8 @@ Launching a virtual machine on arm64 with WHPX acceleration::
          -device usb-kbd -device usb-tablet \
          -hda OS.qcow2
  
-On arm64, for non-Windows guests, `-device virtio-gpu-pci` provides
-additional fuctionality compared to `-device ramfb`, but is
+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.
  
@@ -69,10 +69,10 @@ Some tracing options
  x86_64
  ^^^^^^
  
-`-trace whpx_unsupported_msr_access` can be used to log accesses
+``-trace whpx_unsupported_msr_access`` can be used to log accesses
  to undocumented MSRs.
  
-`-d invalid_mem` allows to trace accesses to unmapped
+``-d invalid_mem`` allows to trace accesses to unmapped
  GPAs.
  
  Known issues on x86_64
@@ -88,19 +88,19 @@ 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
+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`
+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``
+^^^^^^^^^^^^
  
-`-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`.
+``-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.
@@ -111,10 +111,10 @@ 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`.
+The same also applies to ``info registers``.
  
--cpu `type` ignored
-^^^^^^^^^^^^^^^^^^^
+``-cpu type`` ignored
+^^^^^^^^^^^^^^^^^^^^^
  
  In this release, -cpu is an ignored argument.
  
@@ -127,7 +127,7 @@ 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`.
+Workaround: for affected use cases, use ``-M kernel-irqchip=off``.
  
  Known issues on Windows 11
  ^^^^^^^^^^^^^^^^^^^^^^^^^^

Adjust and applied, thanks.

Paolo

[PATCH v6 3/4] whpx: i386: trace unsupported MSR accesses

[Mohamed Mediouni]

Not actionable information for users, so stop
having it displayed unconditionally.

Signed-off-by: Mohamed Mediouni <mohamed@unpredictable.fr>
Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
---
 meson.build                   | 1 +
 target/i386/whpx/trace-events | 1 +
 target/i386/whpx/trace.h      | 2 ++
 target/i386/whpx/whpx-all.c   | 5 +++--
 4 files changed, 7 insertions(+), 2 deletions(-)
 create mode 100644 target/i386/whpx/trace-events
 create mode 100644 target/i386/whpx/trace.h

diff --git a/meson.build b/meson.build
index 6f77309075..8bf1da3169 100644
--- a/meson.build
+++ b/meson.build
@@ -3692,6 +3692,7 @@ if have_system or have_user
     'target/hppa',
     'target/i386',
     'target/i386/kvm',
+    'target/i386/whpx',
     'target/loongarch',
     'target/mips/tcg',
     'target/ppc',
diff --git a/target/i386/whpx/trace-events b/target/i386/whpx/trace-events
new file mode 100644
index 0000000000..ebdfa34b28
--- /dev/null
+++ b/target/i386/whpx/trace-events
@@ -0,0 +1 @@
+whpx_unsupported_msr_access(uint32_t msr, int is_write) "WHPX: Unsupported MSR access (0x%x), IsWrite=%i"
diff --git a/target/i386/whpx/trace.h b/target/i386/whpx/trace.h
new file mode 100644
index 0000000000..b7c090deff
--- /dev/null
+++ b/target/i386/whpx/trace.h
@@ -0,0 +1,2 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+#include "trace/trace-target_i386_whpx.h"
diff --git a/target/i386/whpx/whpx-all.c b/target/i386/whpx/whpx-all.c
index e8fe65f581..9a405118c5 100644
--- a/target/i386/whpx/whpx-all.c
+++ b/target/i386/whpx/whpx-all.c
@@ -41,6 +41,7 @@
 #include "emulate/x86_emu.h"
 #include "emulate/x86_flags.h"
 #include "emulate/x86_mmu.h"
+#include "trace.h"
 
 #include <winhvplatform.h>
 
@@ -1931,8 +1932,8 @@ int whpx_vcpu_run(CPUState *cpu)
                         1 : 3;
 
             if (!is_known_msr) {
-                warn_report("WHPX: Unsupported MSR access (0x%x), IsWrite=%i", 
-                vcpu->exit_ctx.MsrAccess.MsrNumber, vcpu->exit_ctx.MsrAccess.AccessInfo.IsWrite);
+                trace_whpx_unsupported_msr_access(vcpu->exit_ctx.MsrAccess.MsrNumber,
+                    vcpu->exit_ctx.MsrAccess.AccessInfo.IsWrite);
             }
 
             hr = whp_dispatch.WHvSetVirtualProcessorRegisters(
-- 
2.50.1 (Apple Git-155)

[PATCH v6 4/4] target/i386: emulate: remove redundant logging for unmapped MMIO access

[Mohamed Mediouni]

ReactOS's install ISO does a bunch of 4-byte accesses
to 0xffdff124. This doesn't happen for the boot ISO.

It looks to be an access relative to the Windows KPCR
which is at 0xffdff000 but mistakenly done prior to
paging being on...

As this logging is redundant with -d invalid_mem,
remove it.

https://geoffchappell.com/studies/windows/km/ntoskrnl/inc/ntos/i386_x/kpcr.htm

Signed-off-by: Mohamed Mediouni <mohamed@unpredictable.fr>
---
 target/i386/emulate/x86_mmu.c | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/target/i386/emulate/x86_mmu.c b/target/i386/emulate/x86_mmu.c
index c69ae96acb..007de582de 100644
--- a/target/i386/emulate/x86_mmu.c
+++ b/target/i386/emulate/x86_mmu.c
@@ -21,7 +21,6 @@
 #include "cpu.h"
 #include "system/address-spaces.h"
 #include "system/memory.h"
-#include "qemu/error-report.h"
 #include "emulate/x86.h"
 #include "emulate/x86_emu.h"
 #include "emulate/x86_mmu.h"
@@ -287,7 +286,6 @@ static MMUTranslateResult x86_write_mem_ex(CPUState *cpu, void *data, target_ulo
                             MEMTXATTRS_UNSPECIFIED, data, copy);
 
         if (mem_tx_res == MEMTX_DECODE_ERROR) {
-            warn_report("write to unmapped mmio region gpa=0x%" PRIx64 " size=%i", gpa, bytes);
             return MMU_TRANSLATE_GPA_UNMAPPED;
         } else if (mem_tx_res == MEMTX_ACCESS_ERROR) {
             return MMU_TRANSLATE_GPA_NO_WRITE_ACCESS;
@@ -339,7 +337,6 @@ static MMUTranslateResult x86_read_mem_ex(CPUState *cpu, void *data, target_ulon
                            data, copy);
 
         if (mem_tx_res == MEMTX_DECODE_ERROR) {
-            warn_report("read from unmapped mmio region gpa=0x%" PRIx64 " size=%i", gpa, bytes);
             return MMU_TRANSLATE_GPA_UNMAPPED;
         } else if (mem_tx_res == MEMTX_ACCESS_ERROR) {
             return MMU_TRANSLATE_GPA_NO_READ_ACCESS;
-- 
2.50.1 (Apple Git-155)