major changes for windows support

Author: CMGS

.github/workflows/build-os-images.yml

@@ -5,6 +5,7 @@ on:
     branches: [master]
     paths:
       - "os-image/**"
+      - "!os-image/windows/**"
   workflow_dispatch:
     inputs:
       no-cache:

KNOWN_ISSUES.md

@@ -70,3 +70,23 @@ This applies to **all CNI plugins** where the upstream network provides DHCP (br
 ```
 
 Cocoon detects when CNI returns no IP allocation and automatically configures the guest for DHCP — cloudimg VMs get `DHCP=ipv4` in their Netplan config, and OCI VMs get DHCP systemd-networkd units generated by the initramfs.
+
+## Windows VM requires Cloud Hypervisor v50.2
+
+Cloud Hypervisor v51.x has a regression ([#7849](https://github.com/cloud-hypervisor/cloud-hypervisor/issues/7849)) that causes Windows to BSOD (`DRIVER_IRQL_NOT_LESS_OR_EQUAL` in `viostor.sys`) when DISCARD/WRITE_ZEROES features are advertised with default-zero config values, violating virtio spec v1.2. The fix (PR #7852) is merged but not yet included in any release.
+
+**Recommendation**: use Cloud Hypervisor **v50.2** for Windows VMs.
+
+## Windows VM requires virtio-win 0.1.240
+
+virtio-win 0.1.271+ network drivers are incompatible with Cloud Hypervisor due to incomplete virtio-net control queue implementation ([#7925](https://github.com/cloud-hypervisor/cloud-hypervisor/issues/7925)). CH only handles `CTRL_MQ` and `CTRL_GUEST_OFFLOADS`; all other commands (`CTRL_RX`, `CTRL_MAC`, `CTRL_VLAN`, `CTRL_ANNOUNCE`) return `VIRTIO_NET_ERR`.
+
+| Version  | Behavior on VIRTIO_NET_ERR                               |
+|----------|----------------------------------------------------------|
+| 0.1.240  | Tolerates error, continues working                       |
+| 0.1.271  | May silently fail, NIC unusable                          |
+| 0.1.285+ | Fail-fast: NdisMRemoveMiniport(), Problem Code 43        |
+
+0.1.285 introduced commit `50e7db9` ("indicate driver error on unexpected CX behavior") with zero-tolerance on control queue errors. Root cause is a CH bug — correct fix is to return `VIRTIO_NET_OK` for unsupported commands instead of `VIRTIO_NET_ERR`. No upstream PR exists yet.
+
+**Recommendation**: use virtio-win **0.1.240** for Windows VMs on Cloud Hypervisor.

README.md

@@ -29,7 +29,7 @@ Lightweight MicroVM engine built on [Cloud Hypervisor](https://github.com/cloud-
 
 - Linux with KVM (x86_64 or aarch64)
 - Root access (sudo)
-- [Cloud Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor) v51.0+
+- [Cloud Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor) v51.0+ (v50.2 for Windows VMs — see [KNOWN_ISSUES.md](KNOWN_ISSUES.md))
 - `qemu-img` (from qemu-utils, for cloud images)
 - UEFI firmware (`CLOUDHV.fd`, for cloud images)
 - CNI plugins (`bridge`, `host-local`, `loopback`)
@@ -168,6 +168,7 @@ Applies to `cocoon vm create`, `cocoon vm run`, and `cocoon vm debug`:
 | `--storage` | `10G`            | COW disk size (e.g., 10G, 20G)                |
 | `--nics`    | `1`              | Number of network interfaces (0 = no network) |
 | `--network` | empty (default)  | CNI conflist name (empty = first conflist)     |
+| `--windows` | `false`          | Windows guest (UEFI boot, kvm_hyperv=on, no cidata) |
 
 ### Clone Flags
 
@@ -276,6 +277,35 @@ Cloudimg VMs receive a NoCloud cidata disk (FAT12 with `CIDATA` volume label) co
 
 The cidata disk is **automatically excluded on subsequent boots** — after the first successful start, the VM record is marked as `first_booted` and the cidata disk is no longer attached, preventing cloud-init from re-running.
 
+## Windows Support
+
+Cocoon supports Windows guests via the `--windows` flag:
+
+```bash
+cocoon vm run --windows --name win11 --cpu 2 --memory 4G --storage 40G <cloudimg-url>
+```
+
+The `--windows` flag:
+- Forces UEFI firmware boot (cloudimg path)
+- Enables Hyper-V enlightenments (`kvm_hyperv=on`)
+- Skips cloud-init cidata disk generation (Windows does not use cloud-init)
+
+### Requirements
+
+- Cloud Hypervisor **v50.2** (v51.x has a Windows regression — see [KNOWN_ISSUES.md](KNOWN_ISSUES.md))
+- virtio-win **0.1.240** drivers pre-installed in the image (see [KNOWN_ISSUES.md](KNOWN_ISSUES.md))
+
+### Image Preparation
+
+Windows images must be prepared manually — Microsoft licensing prohibits automated distribution of Windows disk images. See [`os-image/windows/`](os-image/windows/) for the complete build guide and `autounattend.xml` for unattended installation.
+
+### Post-Clone Networking
+
+- **DHCP networks**: no action needed, Windows DHCP client auto-configures
+- **Static IP**: configure via SAC serial console (`cocoon vm console`)
+
+For more details, see the [Cloud Hypervisor Windows documentation](https://github.com/cloud-hypervisor/cloud-hypervisor/blob/main/docs/windows.md).
+
 ## VM Lifecycle
 
 | State      | Description                                              |

cmd/core/helpers.go

@@ -160,6 +160,7 @@ func VMConfigFromFlags(cmd *cobra.Command, image string) (*types.VMConfig, error
 	memStr, _ := cmd.Flags().GetString("memory")
 	storStr, _ := cmd.Flags().GetString("storage")
 	network, _ := cmd.Flags().GetString("network")
+	windows, _ := cmd.Flags().GetBool("windows")
 
 	if vmName == "" {
 		vmName = sanitizeVMName(image)
@@ -181,6 +182,7 @@ func VMConfigFromFlags(cmd *cobra.Command, image string) (*types.VMConfig, error
 		Storage: storBytes,
 		Image:   image,
 		Network: network,
+		Windows: windows,
 	}
 	if err := cfg.Validate(); err != nil {
 		return nil, err
@@ -241,6 +243,7 @@ func CloneVMConfigFromFlags(cmd *cobra.Command, snapCfg *types.SnapshotConfig) (
 		Storage: storBytes,
 		Image:   snapCfg.Image,
 		Network: network,
+		Windows: snapCfg.Windows,
 	}
 	if err := cfg.Validate(); err != nil {
 		return nil, err

cmd/vm/commands.go

@@ -142,6 +142,7 @@ func addVMFlags(cmd *cobra.Command) {
 	cmd.Flags().String("storage", "10G", "COW disk size") //nolint:mnd
 	cmd.Flags().Int("nics", 1, "number of network interfaces (0 = no network); multiple NICs with auto IP config only works for cloudimg; OCI images auto-configure only the last NIC, others require manual setup inside the guest")
 	cmd.Flags().String("network", "", "CNI conflist name (empty = default)")
+	cmd.Flags().Bool("windows", false, "Windows guest (UEFI boot, kvm_hyperv=on, no cidata)")
 }
 
 func addCloneFlags(cmd *cobra.Command) {

cmd/vm/handler.go

@@ -484,9 +484,9 @@ func (h Handler) Debug(cmd *cobra.Command, args []string) error {
 	}
 
 	if boot.KernelPath != "" {
-		printRunOCI(storageConfigs, boot, vmCfg.Name, vmCfg.Image, cowPath, chBin, vmCfg.CPU, maxCPU, memoryMB, balloon, cowSizeGB)
+		printRunOCI(storageConfigs, boot, vmCfg.Name, vmCfg.Image, cowPath, chBin, vmCfg.CPU, maxCPU, memoryMB, balloon, cowSizeGB, vmCfg.Windows)
 	} else {
-		printRunCloudimg(storageConfigs, boot, vmCfg.Name, vmCfg.Image, cowPath, chBin, vmCfg.CPU, maxCPU, memoryMB, balloon, cowSizeGB)
+		printRunCloudimg(storageConfigs, boot, vmCfg.Name, vmCfg.Image, cowPath, chBin, vmCfg.CPU, maxCPU, memoryMB, balloon, cowSizeGB, vmCfg.Windows)
 	}
 	return nil
 }
@@ -524,6 +524,9 @@ func (h Handler) createVM(cmd *cobra.Command, image string) (context.Context, *t
 	if err != nil {
 		return nil, nil, nil, err
 	}
+	if vmCfg.Windows && bootCfg.KernelPath != "" {
+		return nil, nil, nil, fmt.Errorf("--windows requires cloudimg (UEFI boot), got OCI direct boot image")
+	}
 	cmdcore.EnsureFirmwarePath(conf, bootCfg)
 
 	vmID, err := utils.GenerateID()
@@ -589,6 +592,16 @@ func batchVMCmd(ctx context.Context, name, pastTense string, fn func(context.Con
 // printPostCloneHints outputs commands the user should run inside the guest
 // after a clone to reconfigure network and release balloon memory.
 func printPostCloneHints(vm *types.VM, networkConfigs []*types.NetworkConfig) {
+	if vm.Config.Windows {
+		fmt.Println()
+		fmt.Println("Windows clone: NICs hot-swapped with new MAC addresses.")
+		fmt.Println("  DHCP networks: no action needed.")
+		fmt.Println("  Static IP: configure via SAC serial console (cocoon vm console):")
+		fmt.Println("    https://github.com/cloud-hypervisor/cloud-hypervisor/blob/main/docs/windows.md")
+		fmt.Println()
+		return
+	}
+
 	isCloudimg := slices.ContainsFunc(vm.StorageConfigs, func(sc *types.StorageConfig) bool {
 		return strings.HasSuffix(sc.Path, ".qcow2")
 	})
@@ -705,7 +718,7 @@ func printBashArray(name string, nics []nicHint, field func(nicHint) string) {
 	fmt.Println(")")
 }
 
-func printRunOCI(configs []*types.StorageConfig, boot *types.BootConfig, vmName, image, cowPath, chBin string, cpu, maxCPU, memory, balloon, cowSize int) {
+func printRunOCI(configs []*types.StorageConfig, boot *types.BootConfig, vmName, image, cowPath, chBin string, cpu, maxCPU, memory, balloon, cowSize int, windows bool) {
 	if cowPath == "" {
 		cowPath = fmt.Sprintf("cow-%s.raw", vmName)
 	}
@@ -735,10 +748,10 @@ func printRunOCI(configs []*types.StorageConfig, boot *types.BootConfig, vmName,
 	}
 	fmt.Printf(" \\\n")
 	fmt.Printf("  --cmdline \"%s\" \\\n", cmdline)
-	printCommonCHArgs(cpu, maxCPU, memory, balloon)
+	printCommonCHArgs(cpu, maxCPU, memory, balloon, windows)
 }
 
-func printRunCloudimg(configs []*types.StorageConfig, boot *types.BootConfig, vmName, image, cowPath, chBin string, cpu, maxCPU, memory, balloon, cowSize int) {
+func printRunCloudimg(configs []*types.StorageConfig, boot *types.BootConfig, vmName, image, cowPath, chBin string, cpu, maxCPU, memory, balloon, cowSize int, windows bool) {
 	if cowPath == "" {
 		cowPath = fmt.Sprintf("cow-%s.qcow2", vmName)
 	}
@@ -758,7 +771,7 @@ func printRunCloudimg(configs []*types.StorageConfig, boot *types.BootConfig, vm
 	fmt.Printf("  --disk \\\n")
 	diskArgs := cloudhypervisor.DebugDiskCLIArgs([]*types.StorageConfig{{Path: cowPath, RO: false}}, cpu)
 	fmt.Printf("    \"%s\" \\\n", diskArgs[0])
-	printCommonCHArgs(cpu, maxCPU, memory, balloon)
+	printCommonCHArgs(cpu, maxCPU, memory, balloon, windows)
 }
 
 // vmIPs extracts a comma-separated IP string from a VM's NetworkConfigs.
@@ -778,8 +791,12 @@ func vmIPs(vm *types.VM) string {
 // printCommonCHArgs outputs CH args for manual debugging.
 // --serial tty outputs to the current terminal for interactive debugging,
 // which intentionally differs from the automated path (Console: Pty / Serial: Socket).
-func printCommonCHArgs(cpu, maxCPU, memory, balloon int) {
-	fmt.Printf("  --cpus boot=%d,max=%d \\\n", cpu, maxCPU)
+func printCommonCHArgs(cpu, maxCPU, memory, balloon int, windows bool) {
+	cpuExtra := ""
+	if windows {
+		cpuExtra = ",kvm_hyperv=on"
+	}
+	fmt.Printf("  --cpus boot=%d,max=%d%s \\\n", cpu, maxCPU, cpuExtra)
 	fmt.Printf("  --memory size=%dM \\\n", memory)
 	fmt.Printf("  --rng src=/dev/urandom \\\n")
 	fmt.Printf("  --balloon size=%dM,deflate_on_oom=on,free_page_reporting=on \\\n", balloon)

hypervisor/cloudhypervisor/api.go

@@ -40,8 +40,9 @@ type chPayload struct {
 }
 
 type chCPUs struct {
-	BootVCPUs int `json:"boot_vcpus"`
-	MaxVCPUs  int `json:"max_vcpus"`
+	BootVCPUs int  `json:"boot_vcpus"`
+	MaxVCPUs  int  `json:"max_vcpus"`
+	KVMHyperV bool `json:"kvm_hyperv,omitempty"`
 }
 
 type chMemory struct {
@@ -50,17 +51,22 @@ type chMemory struct {
 }
 
 type chDisk struct {
-	ID            string `json:"id,omitempty"`
-	Path          string `json:"path"`
-	ReadOnly      bool   `json:"readonly,omitempty"`
-	DirectIO      bool   `json:"direct,omitempty"`
-	Sparse        bool   `json:"sparse,omitempty"`
-	ImageType     string `json:"image_type,omitempty"`
-	BackingFiles  bool   `json:"backing_files,omitempty"`
-	NumQueues     int    `json:"num_queues,omitempty"`
-	QueueSize     int    `json:"queue_size,omitempty"`
-	QueueAffinity string `json:"queue_affinity,omitempty"`
-	Serial        string `json:"serial,omitempty"`
+	ID            string            `json:"id,omitempty"`
+	Path          string            `json:"path"`
+	ReadOnly      bool              `json:"readonly,omitempty"`
+	DirectIO      bool              `json:"direct,omitempty"`
+	Sparse        bool              `json:"sparse,omitempty"`
+	ImageType     string            `json:"image_type,omitempty"`
+	BackingFiles  bool              `json:"backing_files,omitempty"`
+	NumQueues     int               `json:"num_queues,omitempty"`
+	QueueSize     int               `json:"queue_size,omitempty"`
+	QueueAffinity []chQueueAffinity `json:"queue_affinity,omitempty"`
+	Serial        string            `json:"serial,omitempty"`
+}
+
+type chQueueAffinity struct {
+	QueueIndex int   `json:"queue_index"`
+	HostCPUs   []int `json:"host_cpus"`
 }
 
 type chBalloon struct {

hypervisor/cloudhypervisor/args.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"path/filepath"
 	"runtime"
+	"strconv"
 	"strings"
 
 	"github.com/projecteru2/core/log"
@@ -38,7 +39,7 @@ func buildVMConfig(ctx context.Context, rec *hypervisor.VMRecord, consoleSockPat
 	}
 
 	cfg := &chVMConfig{
-		CPUs:     chCPUs{BootVCPUs: cpu, MaxVCPUs: maxVCPUs},
+		CPUs:     chCPUs{BootVCPUs: cpu, MaxVCPUs: maxVCPUs, KVMHyperV: rec.Config.Windows},
 		Memory:   chMemory{Size: mem, HugePages: utils.DetectHugePages()},
 		RNG:      chRNG{Src: "/dev/urandom"},
 		Watchdog: true,
@@ -132,11 +133,10 @@ func storageConfigToDisk(storageConfig *types.StorageConfig, cpuCount int) chDis
 	// cross-core cache bouncing on writable disks. Skip for readonly
 	// disks where IO is low and fully served by page cache.
 	if cpuCount > 1 && !storageConfig.RO {
-		parts := make([]string, cpuCount)
-		for i := range parts {
-			parts[i] = fmt.Sprintf("%d@[%d]", i, i)
+		d.QueueAffinity = make([]chQueueAffinity, cpuCount)
+		for i := range d.QueueAffinity {
+			d.QueueAffinity[i] = chQueueAffinity{QueueIndex: i, HostCPUs: []int{i}}
 		}
-		d.QueueAffinity = "[" + strings.Join(parts, ",") + "]"
 	}
 	return d
 }
@@ -157,7 +157,11 @@ func DebugDiskCLIArgs(storageConfigs []*types.StorageConfig, cpuCount int) []str
 func buildCLIArgs(cfg *chVMConfig, socketPath string) []string {
 	args := []string{"--api-socket", socketPath}
 
-	args = append(args, "--cpus", fmt.Sprintf("boot=%d,max=%d", cfg.CPUs.BootVCPUs, cfg.CPUs.MaxVCPUs))
+	var cpuKV kvBuilder
+	cpuKV.add(fmt.Sprintf("boot=%d", cfg.CPUs.BootVCPUs))
+	cpuKV.add(fmt.Sprintf("max=%d", cfg.CPUs.MaxVCPUs))
+	cpuKV.addIf(cfg.CPUs.KVMHyperV, "kvm_hyperv=on")
+	args = append(args, "--cpus", cpuKV.String())
 
 	mem := fmt.Sprintf("size=%d", cfg.Memory.Size)
 	if cfg.Memory.HugePages {
@@ -235,7 +239,9 @@ func diskToCLIArg(d chDisk) string {
 	b.addIf(d.BackingFiles, "backing_files=on")
 	b.addIf(d.NumQueues > 0, fmt.Sprintf("num_queues=%d", d.NumQueues))
 	b.addIf(d.QueueSize > 0, fmt.Sprintf("queue_size=%d", d.QueueSize))
-	b.addIf(d.QueueAffinity != "", "queue_affinity="+d.QueueAffinity)
+	if len(d.QueueAffinity) > 0 {
+		b.add("queue_affinity=" + queueAffinityToCLI(d.QueueAffinity))
+	}
 	b.addIf(d.Serial != "", "serial="+d.Serial)
 	return b.String()
 }
@@ -273,6 +279,20 @@ func runtimeFiletoCLIArg(c *chRuntimeFile) string {
 	}
 }
 
+// queueAffinityToCLI converts structured queue affinity to CH CLI format.
+// e.g. []chQueueAffinity{{0,[0]},{1,[1]}} → "[0@[0],1@[1]]"
+func queueAffinityToCLI(qa []chQueueAffinity) string {
+	parts := make([]string, len(qa))
+	for i, a := range qa {
+		cpus := make([]string, len(a.HostCPUs))
+		for j, c := range a.HostCPUs {
+			cpus[j] = strconv.Itoa(c)
+		}
+		parts[i] = fmt.Sprintf("%d@[%s]", a.QueueIndex, strings.Join(cpus, ","))
+	}
+	return "[" + strings.Join(parts, ",") + "]"
+}
+
 // isCidataDisk reports whether a storage config is the cloud-init cidata disk.
 func isCidataDisk(sc *types.StorageConfig) bool {
 	return filepath.Base(sc.Path) == cidataFile

hypervisor/cloudhypervisor/clone.go

@@ -94,7 +94,8 @@ func (ch *CloudHypervisor) cloneAfterExtract(ctx context.Context, vmID string, v
 
 	// vm.restore requires config/state device tree equality.
 	// If snapshot had no cidata disk, patch only snapshot disks and hotplug cidata later.
-	patchStorageConfigs := restorePatchStorageConfigs(storageConfigs, directBoot, hadCidataInSnapshot)
+	// Windows VMs never have cidata, so skip the trim entirely.
+	patchStorageConfigs := restorePatchStorageConfigs(storageConfigs, directBoot, vmCfg.Windows || hadCidataInSnapshot)
 
 	consoleSock := consoleSockPath(runDir)
 	if err = patchCHConfig(chConfigPath, &patchOptions{
@@ -138,7 +139,7 @@ func (ch *CloudHypervisor) cloneAfterExtract(ctx context.Context, vmID string, v
 		return nil, fmt.Errorf("launch CH: %w", err)
 	}
 
-	if err := ch.restoreAndResumeClone(ctx, pid, sockPath, runDir, directBoot, hadCidataInSnapshot, storageConfigs, networkConfigs, chCfg, vmCfg.CPU); err != nil {
+	if err := ch.restoreAndResumeClone(ctx, pid, sockPath, runDir, directBoot, vmCfg.Windows, hadCidataInSnapshot, storageConfigs, networkConfigs, chCfg, vmCfg.CPU); err != nil {
 		return nil, err
 	}
 
@@ -179,7 +180,7 @@ func (ch *CloudHypervisor) restoreAndResumeClone(
 	ctx context.Context,
 	pid int,
 	sockPath, runDir string,
-	directBoot, hadCidataInSnapshot bool,
+	directBoot, windows, hadCidataInSnapshot bool,
 	storageConfigs []*types.StorageConfig,
 	networkConfigs []*types.NetworkConfig,
 	snapshotCfg *chVMConfig,
@@ -203,7 +204,7 @@ func (ch *CloudHypervisor) restoreAndResumeClone(
 		return fmt.Errorf("hot-swap NICs: %w", err)
 	}
 
-	if !directBoot && !hadCidataInSnapshot {
+	if !directBoot && !windows && !hadCidataInSnapshot {
 		if len(storageConfigs) == 0 {
 			return fmt.Errorf("vm.add-disk (cidata): missing storage config")
 		}
@@ -219,7 +220,7 @@ func (ch *CloudHypervisor) restoreAndResumeClone(
 }
 
 func (ch *CloudHypervisor) ensureCloneCidata(vmID string, vmCfg *types.VMConfig, networkConfigs []*types.NetworkConfig, storageConfigs []*types.StorageConfig, directBoot bool) ([]*types.StorageConfig, error) {
-	if directBoot {
+	if directBoot || vmCfg.Windows {
 		return storageConfigs, nil
 	}
 	if err := ch.generateCidata(vmID, vmCfg, networkConfigs); err != nil {

hypervisor/cloudhypervisor/create.go

@@ -156,6 +156,13 @@ func (ch *CloudHypervisor) prepareCloudimg(ctx context.Context, vmID string, vmC
 		}
 	}
 
+	// Windows: no cloud-init cidata disk.
+	if vmCfg.Windows {
+		return []*types.StorageConfig{
+			{Path: overlayPath, RO: false},
+		}, nil
+	}
+
 	// Generate cloud-init cidata disk.
 	if err := ch.generateCidata(vmID, vmCfg, networkConfigs); err != nil {
 		return nil, err