| 1 | Xen HVM guest support |
| 2 | ===================== |
| 3 | |
| 4 | |
| 5 | Description |
| 6 | ----------- |
| 7 | |
| 8 | KVM has support for hosting Xen guests, intercepting Xen hypercalls and event |
| 9 | channel (Xen PV interrupt) delivery. This allows guests which expect to be |
| 10 | run under Xen to be hosted in QEMU under Linux/KVM instead. |
| 11 | |
| 12 | Using the split irqchip is mandatory for Xen support. |
| 13 | |
| 14 | Setup |
| 15 | ----- |
| 16 | |
| 17 | Xen mode is enabled by setting the ``xen-version`` property of the KVM |
| 18 | accelerator, for example for Xen 4.17: |
| 19 | |
| 20 | .. parsed-literal:: |
| 21 | |
| 22 | |qemu_system| --accel kvm,xen-version=0x40011,kernel-irqchip=split |
| 23 | |
| 24 | Additionally, virtual APIC support can be advertised to the guest through the |
| 25 | ``xen-vapic`` CPU flag: |
| 26 | |
| 27 | .. parsed-literal:: |
| 28 | |
| 29 | |qemu_system| --accel kvm,xen-version=0x40011,kernel-irqchip=split --cpu host,+xen-vapic |
| 30 | |
| 31 | When Xen support is enabled, QEMU changes hypervisor identification (CPUID |
| 32 | 0x40000000..0x4000000A) to Xen. The KVM identification and features are not |
| 33 | advertised to a Xen guest. If Hyper-V is also enabled, the Xen identification |
| 34 | moves to leaves 0x40000100..0x4000010A. |
| 35 | |
| 36 | Properties |
| 37 | ---------- |
| 38 | |
| 39 | The following properties exist on the KVM accelerator object: |
| 40 | |
| 41 | ``xen-version`` |
| 42 | This property contains the Xen version in ``XENVER_version`` form, with the |
| 43 | major version in the top 16 bits and the minor version in the low 16 bits. |
| 44 | Setting this property enables the Xen guest support. If Xen version 4.5 or |
| 45 | greater is specified, the HVM leaf in Xen CPUID is populated. Xen version |
| 46 | 4.6 enables the vCPU ID in CPUID, and version 4.17 advertises vCPU upcall |
| 47 | vector support to the guest. |
| 48 | |
| 49 | ``xen-evtchn-max-pirq`` |
| 50 | Xen PIRQs represent an emulated physical interrupt, either GSI or MSI, which |
| 51 | can be routed to an event channel instead of to the emulated I/O or local |
| 52 | APIC. By default, QEMU permits only 256 PIRQs because this allows maximum |
| 53 | compatibility with 32-bit MSI where the higher bits of the PIRQ# would need |
| 54 | to be in the upper 64 bits of the MSI message. For guests with large numbers |
| 55 | of PCI devices (and none which are limited to 32-bit addressing) it may be |
| 56 | desirable to increase this value. |
| 57 | |
| 58 | ``xen-gnttab-max-frames`` |
| 59 | Xen grant tables are the means by which a Xen guest grants access to its |
| 60 | memory for PV back ends (disk, network, etc.). Since QEMU only supports v1 |
| 61 | grant tables which are 8 bytes in size, each page (each frame) of the grant |
| 62 | table can reference 512 pages of guest memory. The default number of frames |
| 63 | is 64, allowing for 32768 pages of guest memory to be accessed by PV backends |
| 64 | through simultaneous grants. For guests with large numbers of PV devices and |
| 65 | high throughput, it may be desirable to increase this value. |
| 66 | |
| 67 | Xen paravirtual devices |
| 68 | ----------------------- |
| 69 | |
| 70 | The Xen PCI platform device is enabled automatically for a Xen guest. This |
| 71 | allows a guest to unplug all emulated devices, in order to use paravirtual |
| 72 | block and network drivers instead. |
| 73 | |
| 74 | Those paravirtual Xen block, network (and console) devices can be created |
| 75 | through the command line, and/or hot-plugged. |
| 76 | |
| 77 | To provide a Xen console device, define a character device and then a device |
| 78 | of type ``xen-console`` to connect to it. For the Xen console equivalent of |
| 79 | the handy ``-serial mon:stdio`` option, for example: |
| 80 | |
| 81 | .. parsed-literal:: |
| 82 | -chardev stdio,mux=on,id=char0,signal=off \\ |
| 83 | -object monitor-hmp,chardev=char0,id=hmp0 \\ |
| 84 | -device xen-console,chardev=char0 |
| 85 | |
| 86 | The Xen network device is ``xen-net-device``, which becomes the default NIC |
| 87 | model for emulated Xen guests, meaning that just the default NIC provided |
| 88 | by QEMU should automatically work and present a Xen network device to the |
| 89 | guest. |
| 90 | |
| 91 | Disks can be configured with '``-drive file=${GUEST_IMAGE},if=xen``' and will |
| 92 | appear to the guest as ``xvda`` onwards. |
| 93 | |
| 94 | Under Xen, the boot disk is typically available both via IDE emulation, and |
| 95 | as a PV block device. Guest bootloaders typically use IDE to load the guest |
| 96 | kernel, which then unplugs the IDE and continues with the Xen PV block device. |
| 97 | |
| 98 | This configuration can be achieved as follows: |
| 99 | |
| 100 | .. parsed-literal:: |
| 101 | |
| 102 | |qemu_system| --accel kvm,xen-version=0x40011,kernel-irqchip=split \\ |
| 103 | -drive file=${GUEST_IMAGE},if=xen \\ |
| 104 | -drive file=${GUEST_IMAGE},file.locking=off,if=ide |
| 105 | |
| 106 | VirtIO devices can also be used; Linux guests may need to be dissuaded from |
| 107 | umplugging them by adding '``xen_emul_unplug=never``' on their command line. |
| 108 | |
| 109 | Booting Xen PV guests |
| 110 | --------------------- |
| 111 | |
| 112 | Booting PV guest kernels is possible by using the Xen PV shim (a version of Xen |
| 113 | itself, designed to run inside a Xen HVM guest and provide memory management |
| 114 | services for one guest alone). |
| 115 | |
| 116 | The Xen binary is provided as the ``-kernel`` and the guest kernel itself (or |
| 117 | PV Grub image) as the ``-initrd`` image, which actually just means the first |
| 118 | multiboot "module". For example: |
| 119 | |
| 120 | .. parsed-literal:: |
| 121 | |
| 122 | |qemu_system| --accel kvm,xen-version=0x40011,kernel-irqchip=split \\ |
| 123 | -chardev stdio,id=char0 -device xen-console,chardev=char0 \\ |
| 124 | -display none -m 1G -kernel xen -initrd bzImage \\ |
| 125 | -append "pv-shim console=xen,pv -- console=hvc0 root=/dev/xvda1" \\ |
| 126 | -drive file=${GUEST_IMAGE},if=xen |
| 127 | |
| 128 | The Xen image must be built with the ``CONFIG_XEN_GUEST`` and ``CONFIG_PV_SHIM`` |
| 129 | options, and as of Xen 4.17, Xen's PV shim mode does not support using a serial |
| 130 | port; it must have a Xen console or it will panic. |
| 131 | |
| 132 | The example above provides the guest kernel command line after a separator |
| 133 | (" ``--`` ") on the Xen command line, and does not provide the guest kernel |
| 134 | with an actual initramfs, which would need to listed as a second multiboot |
| 135 | module. For more complicated alternatives, see the command line |
| 136 | :ref:`documentation <system/invocation-qemu-options-initrd>` for the |
| 137 | ``-initrd`` option. |
| 138 | |
| 139 | Host OS requirements |
| 140 | -------------------- |
| 141 | |
| 142 | The minimal Xen support in the KVM accelerator requires the host to be running |
| 143 | Linux v5.12 or newer. Later versions add optimisations: Linux v5.17 added |
| 144 | acceleration of interrupt delivery via the Xen PIRQ mechanism, and Linux v5.19 |
| 145 | accelerated Xen PV timers and inter-processor interrupts (IPIs). |