Signed-off-by: Mohamed Mediouni <mohamed@unpredictable.fr>
---
 MAINTAINERS           |  1 +
 docs/system/index.rst |  1 +
 docs/system/whpx.rst  | 83 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 85 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..a3a7ecd38f
--- /dev/null
+++ b/docs/system/whpx.rst
@@ -0,0 +1,83 @@
+Windows Hypervisor Platform
+===========================
+
+Common
+------
+
+Windows Hypervisor Platform is available for installation through
+Windows Features (`optionalfeatures.exe`).
+
+VM state save/restore is not implemented.
+
+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.
+
+`-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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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 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
+-----
+
+OS baseline
+^^^^^^^^^^^
+
+On Windows 11, 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 shipped with a pre-release
+version of the Windows Hypervisor Platform API, which is not 
+supported in QEMU.
+
+ISA feature support
+^^^^^^^^^^^^^^^^^^^
+
+SVE and SME are not currently supported.
-- 
2.50.1 (Apple Git-155)

On Thu, 26 Mar 2026 at 13:52, Mohamed Mediouni <mohamed@unpredictable.fr> wrote:
>
> Signed-off-by: Mohamed Mediouni <mohamed@unpredictable.fr>
> ---
>  MAINTAINERS           |  1 +
>  docs/system/index.rst |  1 +
>  docs/system/whpx.rst  | 83 +++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 85 insertions(+)
>  create mode 100644 docs/system/whpx.rst

> diff --git a/docs/system/whpx.rst b/docs/system/whpx.rst
> new file mode 100644
> index 0000000000..a3a7ecd38f
> --- /dev/null
> +++ b/docs/system/whpx.rst
> @@ -0,0 +1,83 @@
> +Windows Hypervisor Platform
> +===========================
> +
> +Common
> +------
> +
> +Windows Hypervisor Platform is available for installation through
> +Windows Features (`optionalfeatures.exe`).
> +
> +VM state save/restore is not implemented.

Thanks for writing up this documentation. A suggestion
for the structure:

I think it would be helpful if we started the documentation
with some introductory text:

 * what is Windows Hypervisor Platform?
 * why might you want to use it?
 * how do you tell QEMU to use it?

before we dive into the details of known issues with our
current support.

thanks
-- PMM