Learn Cloud Hypervisor - Windows Guest & UEFI

#Introduction

So far all our guests have been Linux-based. In episode 15 we challenge that assumption and run Windows — Windows 10 or Windows Server — on Cloud Hypervisor. This might sound odd for a "cloud-native" VMM, but Cloud Hypervisor is actually designed to support full Windows guests, and many modern PaaS platforms run Windows workloads with VM isolation.

The main challenges are clear: Windows needs the right UEFI, drivers for virtio devices, and Windows' uncompromising habits (licensing, activation, timers). We cover all of it step by step.

#Why Windows Needs UEFI

#UEFI vs Direct Boot

Linux can be booted directly with PVH (episode 4) without firmware. Windows cannot. Windows requires UEFI firmware (or BIOS, which is even more complicated in Cloud Hypervisor) to find its boot loader on the ESP (EFI System Partition). That's why Windows in Cloud Hypervisor always uses CLOUDHV.fd:

cloud-hypervisor \
  --firmware CLOUDHV.fd \
  --disk path=windows.raw \
  --cpus boot=4 \
  --memory size=8G \
  --serial tty \
  --console off

There's no --kernel here: CLOUDHV.fd (UEFI based on edk2) reads the ESP, runs the Windows Boot Manager, then loads the Windows kernel. --console off --serial tty redirects the console so Windows boot output is visible in the terminal.

#Virtual Hardware Requirements

Windows is pickier about "hardware". At minimum, prepare:

• 4+ vCPUs and 8 GB RAM so the installer is comfortable.
• A disk with enough capacity (Windows 10 needs 20+ GB virtual).
• Working ACPI — Windows depends heavily on it for power management and device detection.

#Installing Windows

#Prepare the ISO and Disk

Download a Windows ISO (an evaluation version is available from Microsoft), then present it as a virtio CD-ROM:

qemu-img create -f raw windows.raw 40G
cloud-hypervisor \
  --firmware CLOUDHV.fd \
  --disk path=windows.raw \
  --disk path=Win10_22H2.iso,readonly=on \
  --cpus boot=4 \
  --memory size=8G \
  --serial tty

#Install Virtio Drivers

The biggest problem during installation: Windows doesn't know virtio-blk/virtio-net. During setup, Windows won't see the virtio disk because there's no driver. The solution is to provide the drivers on another medium:

cloud-hypervisor \
  --firmware CLOUDHV.fd \
  --disk path=windows.raw \
  --disk path=Win10_22H2.iso,readonly=on \
  --disk path=virtio-win.iso,readonly=on \
  --cpus boot=4 \
  --memory size=8G \
  --serial tty

When setup refuses to find a disk, choose "Load driver" and point it at the virtio-win CD-ROM — select the viostor (storage) and NetKVM (network) drivers. The official virtio drivers for Windows are provided in the virtio-win repository (community-maintained, including drivers for Cloud Hypervisor).

#Activation and Licensing

Windows licensing isn't a VMM technical problem, but it's still relevant: make sure you use a valid license for the VM. Modern Windows Server can be installed without activation and used in evaluation mode, with activation done through standard Microsoft methods (KMS or digital license) — Cloud Hypervisor doesn't provide any special mechanism here.

#Upstream edk2 vs the CLOUDHV Fork

#Why There's a Fork

CLOUDHV.fd is an edk2 build forked specifically for Cloud Hypervisor. Why not use upstream edk2 directly? Because Cloud Hypervisor provides a specific firmware interface (e.g., an MMIO device layout consistent with its VMM), and this fork ensures the firmware is optimized for that context — smaller size, faster boot, and relevant device support.

#Especially on AArch64

The most striking differences are on AArch64. On this architecture, upstream edk2 doesn't provide console output and device setup that match Cloud Hypervisor conventions without adjustments. The CLOUDHV fork adds the needed support (e.g., correct serial UART, device tree, and virtio support for booting Arm guests like Windows on Arm or Linux). This is why the official docs recommend CLOUDHV_EFI.fd on aarch64:

cloud-hypervisor \
  --firmware CLOUDHV_EFI.fd \
  --disk path=windows-arm.raw \
  --cpus boot=4 \
  --memory size=8G \
  --serial tty

If you try upstream edk2 on AArch64 and get no output, this is most likely the reason — use the Cloud Hypervisor-maintained fork.

#Windows Best Practices in Cloud Hypervisor

• Set a stable timer: Windows is sensitive to timers; avoid unstable TSC across hosts if you want migration (episode 11).
• Install the Windows qemu-guest-agent (virtio-serial): provides a host↔guest communication channel useful for freezing the filesystem during snapshot.
• Snapshot while idle: Windows writes a lot in the background; snapshotting under load can produce inconsistent state.
• Memory hotplug: Windows supports ACPI memory hotplug well — take advantage of hotplug_size for growth.
• Monitor virtio devices: in Device Manager, make sure there are no devices with an exclamation mark — a device without a driver means lost functionality.

#Common Pitfalls

• Installer doesn't see the disk: load the viostor driver from virtio-win.
• Boot loop after installation: make sure the firmware boot order uses the target disk; CLOUDHV.fd boots from the first disk by default.
• No network: install NetKVM; verify in Device Manager.
• No output on AArch64: use the CLOUDHV fork (CLOUDHV_EFI.fd), not upstream edk2.
• Licensing: use a license compliant with Microsoft's rules for virtual environments.

#Conclusion

Key takeaways:

• Windows must boot via UEFI: --firmware CLOUDHV.fd, no direct PVH boot.
• Virtio drivers (viostor, NetKVM) must be loaded during installation via the virtio-win CD-ROM.
• CLOUDHV.fd is an edk2 fork specific to Cloud Hypervisor; on AArch64 use CLOUDHV_EFI.fd.
• Prepare enough resources (4 vCPUs, 8 GB RAM, 40 GB disk) so the installer is comfortable.
• Mind licensing, timers, and idle-time snapshots for a stable Windows.

In the next episode, episode 16, we'll cover testing & CI — cargo test, integration tests (integration.rs), CI running against kernel 5.15, plus benchmarks for boot time, memory overhead, and throughput compared to QEMU. How this project keeps quality, and how you can test it yourself.