[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v12 59/60] i386/xen: Document Xen HVM emulation
From: |
David Woodhouse |
Subject: |
[PATCH v12 59/60] i386/xen: Document Xen HVM emulation |
Date: |
Mon, 20 Feb 2023 20:47:35 +0000 |
From: David Woodhouse <dwmw@amazon.co.uk>
Signed-off-by: David Woodhouse <dwmw2@amazon.co.uk>
Reviewed-by: Paul Durrant <paul@xen.org>
---
docs/system/i386/xen.rst | 76 +++++++++++++++++++++++++++++++++++++
docs/system/target-i386.rst | 1 +
2 files changed, 77 insertions(+)
create mode 100644 docs/system/i386/xen.rst
diff --git a/docs/system/i386/xen.rst b/docs/system/i386/xen.rst
new file mode 100644
index 0000000000..a00523b492
--- /dev/null
+++ b/docs/system/i386/xen.rst
@@ -0,0 +1,76 @@
+Xen HVM guest support
+=====================
+
+
+Description
+-----------
+
+KVM has support for hosting Xen guests, intercepting Xen hypercalls and event
+channel (Xen PV interrupt) delivery. This allows guests which expect to be
+run under Xen to be hosted in QEMU under Linux/KVM instead.
+
+Setup
+-----
+
+Xen mode is enabled by setting the ``xen-version`` property of the KVM
+accelerator, for example for Xen 4.10:
+
+.. parsed-literal::
+
+ |qemu_system| --accel kvm,xen-version=0x4000a
+
+Additionally, virtual APIC support can be advertised to the guest through the
+``xen-vapic`` CPU flag:
+
+.. parsed-literal::
+
+ |qemu_system| --accel kvm,xen-version=0x4000a --cpu host,+xen_vapic
+
+When Xen support is enabled, QEMU changes hypervisor identification (CPUID
+0x40000000..0x4000000A) to Xen. The KVM identification and features are not
+advertised to a Xen guest. If Hyper-V is also enabled, the Xen identification
+moves to leaves 0x40000100..0x4000010A.
+
+The Xen platform device is enabled automatically for a Xen guest. This allows
+a guest to unplug all emulated devices, in order to use Xen PV block and
network
+drivers instead. Note that until the Xen PV device back ends are enabled to
work
+with Xen mode in QEMU, that is unlikely to cause significant joy. Linux guests
+can be dissuaded from this by adding 'xen_emul_unplug=never' on their command
+line, and it can also be noted that AHCI disk controllers are exempt from being
+unplugged, as are passthrough VFIO PCI devices.
+
+Properties
+----------
+
+The following properties exist on the KVM accelerator object:
+
+``xen-version``
+ This property contains the Xen version in ``XENVER_version`` form, with the
+ major version in the top 16 bits and the minor version in the low 16 bits.
+ Setting this property enables the Xen guest support.
+
+``xen-evtchn-max-pirq``
+ Xen PIRQs represent an emulated physical interrupt, either GSI or MSI, which
+ can be routed to an event channel instead of to the emulated I/O or local
+ APIC. By default, QEMU permits only 256 PIRQs because this allows maximum
+ compatibility with 32-bit MSI where the higher bits of the PIRQ# would need
+ to be in the upper 64 bits of the MSI message. For guests with large numbers
+ of PCI devices (and none which are limited to 32-bit addressing) it may be
+ desirable to increase this value.
+
+``xen-gnttab-max-frames``
+ Xen grant tables are the means by which a Xen guest grants access to its
+ memory for PV back ends (disk, network, etc.). Since QEMU only supports v1
+ grant tables which are 8 bytes in size, each page (each frame) of the grant
+ table can reference 512 pages of guest memory. The default number of frames
+ is 64, allowing for 32768 pages of guest memory to be accessed by PV backends
+ through simultaneous grants. For guests with large numbers of PV devices and
+ high throughput, it may be desirable to increase this value.
+
+OS requirements
+---------------
+
+The minimal Xen support in the KVM accelerator requires the host to be running
+Linux v5.12 or newer. Later versions add optimisations: Linux v5.17 added
+acceleration of interrupt delivery via the Xen PIRQ mechanism, and Linux v5.19
+accelerated Xen PV timers and inter-processor interrupts (IPIs).
diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst
index e64c013077..77c2f3b979 100644
--- a/docs/system/target-i386.rst
+++ b/docs/system/target-i386.rst
@@ -27,6 +27,7 @@ Architectural features
i386/cpu
i386/hyperv
+ i386/xen
i386/kvm-pv
i386/sgx
i386/amd-memory-encryption
--
2.39.0
- [PATCH v12 48/60] i386/xen: Reserve Xen special pages for console, xenstore rings, (continued)
- [PATCH v12 48/60] i386/xen: Reserve Xen special pages for console, xenstore rings, David Woodhouse, 2023/02/20
- [PATCH v12 11/60] i386/xen: implement HYPERVISOR_sched_op, SCHEDOP_shutdown, David Woodhouse, 2023/02/20
- [PATCH v12 14/60] xen: Permit --xen-domid argument when accel is KVM, David Woodhouse, 2023/02/20
- [PATCH v12 34/60] hw/xen: Implement EVTCHNOP_send, David Woodhouse, 2023/02/20
- [PATCH v12 52/60] hw/xen: Add basic ring handling to xenstore, David Woodhouse, 2023/02/20
- [PATCH v12 33/60] hw/xen: Implement EVTCHNOP_bind_ipi, David Woodhouse, 2023/02/20
- [PATCH v12 04/60] i386/kvm: Add xen-version KVM accelerator property and init KVM Xen support, David Woodhouse, 2023/02/20
- [PATCH v12 19/60] i386/xen: implement HYPERVISOR_hvm_op, David Woodhouse, 2023/02/20
- [PATCH v12 15/60] i386/xen: add pc_machine_kvm_type to initialize XEN_EMULATE mode, David Woodhouse, 2023/02/20
- [PATCH v12 25/60] i386/xen: implement HVMOP_set_evtchn_upcall_vector, David Woodhouse, 2023/02/20
- [PATCH v12 59/60] i386/xen: Document Xen HVM emulation,
David Woodhouse <=
- [PATCH v12 18/60] i386/xen: implement XENMEM_add_to_physmap_batch, David Woodhouse, 2023/02/20
- [PATCH v12 43/60] hw/xen: Add xen_gnttab device for grant table emulation, David Woodhouse, 2023/02/20
- [PATCH v12 12/60] i386/xen: Implement SCHEDOP_poll and SCHEDOP_yield, David Woodhouse, 2023/02/20
- [PATCH v12 13/60] hw/xen: Add xen_overlay device for emulating shared xenheap pages, David Woodhouse, 2023/02/20
- [PATCH v12 50/60] hw/xen: Add backend implementation of interdomain event channel support, David Woodhouse, 2023/02/20
- [PATCH v12 27/60] hw/xen: Add xen_evtchn device for event channel emulation, David Woodhouse, 2023/02/20
- [PATCH v12 51/60] hw/xen: Add xen_xenstore device for xenstore emulation, David Woodhouse, 2023/02/20
- [PATCH v12 06/60] i386/hvm: Set Xen vCPU ID in KVM, David Woodhouse, 2023/02/20
- [PATCH v12 55/60] hw/xen: Implement emulated PIRQ hypercall support, David Woodhouse, 2023/02/20
- [PATCH v12 24/60] i386/xen: implement HYPERVISOR_event_channel_op, David Woodhouse, 2023/02/20