Docs: explain how to enable QEMU hardware acceleration on Windows

Describes how to enable QEMU hardware acceleration on Windows using the Windows Hypervisor Platform feature.
Author: https://github.com/peterdn Commit: https://github.com/SerenityOS/serenity/commit/e36fce9cfc6 Pull-request: https://github.com/SerenityOS/serenity/pull/3135
2025-04-21 03:55:24 +00:00 · 2020-08-14 13:19:30 +01:00 · 2020-08-14 13:19:30 +01:00 · e36fce9cfc · 2024-07-19 03:39:02 +09:00
commit e36fce9cfc
parent d00df4e721
1 changed files with 19 additions and 0 deletions
--- a/Documentation/NotesOnWSL.md
+++ b/Documentation/NotesOnWSL.md
@ -45,6 +45,25 @@ By default this will be located at `/mnt/c/Program Files/qemu/qemu-system-i386.e

 - `make run` as usual.

+#### Hardware acceleration
+
+The steps above will run QEMU in software virtualisation mode, which is very slow.
+QEMU supports hardware acceleration on Windows via the [Windows Hypervisor Platform](https://docs.microsoft.com/en-us/virtualization/api/) (WHPX), a user-mode virtualisation API that can be used alongside Hyper-V.
+This is important to note as WSL2 itself runs on top of Hyper-V, which conflicts with other acceleration technologies such as Intel HAXM.
+
+To run SerenityOS in a WHPX-enabled QEMU VM:
+
+- If you have not already done so, enable Windows Hypervisor Platform, either using "Turn Windows features on or off", or by running the following command in an elevated PowerShell session: \
+`dism /Online /Enable-Feature /All /FeatureName:HypervisorPlatform`
+
+- Specify QEMU acceleration option: \
+`export SERENITY_EXTRA_QEMU_ARGS="-accel whpx"`
+
+- Disable Virtual Machine eXtensions on the vCPU, otherwise some versions of QEMU will crash out with a "WHPX: Unexpected VP exit code 4" error: \
+`export SERENITY_QEMU_CPU="max,vmx=off"`
+
+- `make run` as usual.
+
 ### Note on filesystems

 WSL2 filesystem performance for IO heavy tasks (such as compiling a large C++ project) on the host Windows filesystem is terrible.