From nobody Wed Nov 27 17:37:12 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org ARC-Seal: i=1; a=rsa-sha256; t=1697730099; cv=none; d=zohomail.com; s=zohoarc; b=cVUN1bV4cASeGCWR7bp6rEFBawsBrHB0LngHtFd7SeEOdVTkr8gYniaiRgpJbJkaqHSZcrKWBCmNAeeJY84vLY/oLb6AuRiVvek/RviPs+MIa5wHSjQlG3vBm7Dfz60gpmlRrfP+53LzT44QFMmj9VaqIR+rNs9wLg+4MBhemzU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1697730099; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=DyY8I/ZKbCu/w/L7sfs0qQaOI3alzNFdd8No8uZAwJY=; b=GvEnFLdKtJGO6agdsKQejZ8M8UhdtPcQ591HxidXDqyQRqUjz58POQdmhSoAwbjfYFLz5OJ8Ssc281HBh6WfCO/IXl7zwj7InV+kgfi5VG/Mp817UIrdE2b19LV8EPv+HQlat9sNr4QBDU2MCWL/IETQbSLwgfFNMK0565AXie8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 169773009986137.12662320259426; Thu, 19 Oct 2023 08:41:39 -0700 (PDT) Received: from list by lists.xenproject.org with outflank-mailman.619426.964539 (Exim 4.92) (envelope-from ) id 1qtV8x-0001Ct-Tt; Thu, 19 Oct 2023 15:41:03 +0000 Received: by outflank-mailman (output) from mailman id 619426.964539; Thu, 19 Oct 2023 15:41:03 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1qtV8x-00018J-3n; Thu, 19 Oct 2023 15:41:03 +0000 Received: by outflank-mailman (input) for mailman id 619426; Thu, 19 Oct 2023 15:40:59 +0000 Received: from se1-gles-flk1-in.inumbo.com ([94.247.172.50] helo=se1-gles-flk1.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1qtV8s-0006dc-SC for xen-devel@lists.xenproject.org; Thu, 19 Oct 2023 15:40:58 +0000 Received: from desiato.infradead.org (desiato.infradead.org [2001:8b0:10b:1:d65d:64ff:fe57:4e05]) by se1-gles-flk1.inumbo.com (Halon) with ESMTPS id e35e1947-6e95-11ee-9b0e-b553b5be7939; Thu, 19 Oct 2023 17:40:55 +0200 (CEST) Received: from [2001:8b0:10b:1::ebe] (helo=i7.infradead.org) by desiato.infradead.org with esmtpsa (Exim 4.96 #2 (Red Hat Linux)) id 1qtV8O-009yD7-0P; Thu, 19 Oct 2023 15:40:28 +0000 Received: from dwoodhou by i7.infradead.org with local (Exim 4.96 #2 (Red Hat Linux)) id 1qtV8N-000PvR-1m; Thu, 19 Oct 2023 16:40:27 +0100 X-Outflank-Mailman: Message body and most headers restored to incoming version X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list X-Inumbo-ID: e35e1947-6e95-11ee-9b0e-b553b5be7939 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=desiato.20200630; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description; bh=DyY8I/ZKbCu/w/L7sfs0qQaOI3alzNFdd8No8uZAwJY=; b=poV1WGsApzadUT0xdj1lGj07Ks IIjmyFgyyhHHCCa4ppA7c3EQcnUM8KZHHQBeW/ta/PnFbfeVmW8WJYyEFhxgqunegGZQFI7xbD1/7 fPB4Yk2ZzuW8AcHkoFs3T9n+3rkqi+i8aAB+lpJyNQkcsIVG+tH0I8kSL4/8hilNGyqXxt4nKc4F2 1VYruLsoyPt9sV7drShBs2y4THHGaJUyrvKdv6jl+1jv58sLf+4BCkRLWbDjZmOpshREMjTG1A2K+ gLfK01j5TZVqkaR5DV0hssWj6h3UaFyg+QWj3v0veF2O6ukerNiljYRn81Xjatg7EQZWYHHVwm/lz kfBK08xg==; From: David Woodhouse To: qemu-devel@nongnu.org Cc: Kevin Wolf , Hanna Reitz , Stefano Stabellini , Anthony Perard , Paul Durrant , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Richard Henderson , Eduardo Habkost , "Michael S. Tsirkin" , Marcel Apfelbaum , Jason Wang , Marcelo Tosatti , Cleber Rosa , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Wainer dos Santos Moschetta , Beraldo Leal , qemu-block@nongnu.org, xen-devel@lists.xenproject.org, kvm@vger.kernel.org, Bernhard Beschow , Joel Upham Subject: [PATCH v2 24/24] docs: update Xen-on-KVM documentation Date: Thu, 19 Oct 2023 16:40:20 +0100 Message-Id: <20231019154020.99080-25-dwmw2@infradead.org> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20231019154020.99080-1-dwmw2@infradead.org> References: <20231019154020.99080-1-dwmw2@infradead.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: David Woodhouse X-SRS-Rewrite: SMTP reverse-path rewritten from by desiato.infradead.org. See http://www.infradead.org/rpr.html X-ZohoMail-DKIM: pass (identity @infradead.org) X-ZM-MESSAGEID: 1697730101303100024 Content-Type: text/plain; charset="utf-8" From: David Woodhouse Add notes about console and network support, and how to launch PV guests. Clean up the disk configuration examples now that that's simpler, and remove the comment about IDE unplug on q35/AHCI now that it's fixed. Signed-off-by: David Woodhouse --- docs/system/i386/xen.rst | 100 ++++++++++++++++++++++++++++----------- 1 file changed, 72 insertions(+), 28 deletions(-) diff --git a/docs/system/i386/xen.rst b/docs/system/i386/xen.rst index f06765e88c..6214c4571e 100644 --- a/docs/system/i386/xen.rst +++ b/docs/system/i386/xen.rst @@ -15,46 +15,24 @@ Setup ----- =20 Xen mode is enabled by setting the ``xen-version`` property of the KVM -accelerator, for example for Xen 4.10: +accelerator, for example for Xen 4.17: =20 .. parsed-literal:: =20 - |qemu_system| --accel kvm,xen-version=3D0x4000a,kernel-irqchip=3Dsplit + |qemu_system| --accel kvm,xen-version=3D0x40011,kernel-irqchip=3Dsplit =20 Additionally, virtual APIC support can be advertised to the guest through = the ``xen-vapic`` CPU flag: =20 .. parsed-literal:: =20 - |qemu_system| --accel kvm,xen-version=3D0x4000a,kernel-irqchip=3Dsplit -= -cpu host,+xen_vapic + |qemu_system| --accel kvm,xen-version=3D0x40011,kernel-irqchip=3Dsplit -= -cpu host,+xen-vapic =20 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 identificat= ion moves to leaves 0x40000100..0x4000010A. =20 -The Xen platform device is enabled automatically for a Xen guest. This all= ows -a guest to unplug all emulated devices, in order to use Xen PV block and n= etwork -drivers instead. Under Xen, the boot disk is typically available both via = IDE -emulation, and as a PV block device. Guest bootloaders typically use IDE t= o load -the guest kernel, which then unplugs the IDE and continues with the Xen PV= block -device. - -This configuration can be achieved as follows - -.. parsed-literal:: - - |qemu_system| -M pc --accel kvm,xen-version=3D0x4000a,kernel-irqchip=3Ds= plit \\ - -drive file=3D${GUEST_IMAGE},if=3Dnone,id=3Ddisk,file.locking=3Doff= -device xen-disk,drive=3Ddisk,vdev=3Dxvda \\ - -drive file=3D${GUEST_IMAGE},index=3D2,media=3Ddisk,file.locking=3D= off,if=3Dide - -It is necessary to use the pc machine type, as the q35 machine uses AHCI i= nstead -of legacy IDE, and AHCI disks are not unplugged through the Xen PV unplug -mechanism. - -VirtIO devices can also be used; Linux guests may need to be dissuaded from -umplugging them by adding 'xen_emul_unplug=3Dnever' on their command line. - Properties ---------- =20 @@ -63,7 +41,10 @@ The following properties exist on the KVM accelerator ob= ject: ``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 bit= s. - Setting this property enables the Xen guest support. + Setting this property enables the Xen guest support. If Xen version 4.5 = or + greater is specified, the HVM leaf in Xen CPUID is populated. Xen version + 4.6 enables the vCPU ID in CPUID, and version 4.17 advertises vCPU upcall + vector support to the guest. =20 ``xen-evtchn-max-pirq`` Xen PIRQs represent an emulated physical interrupt, either GSI or MSI, w= hich @@ -83,8 +64,71 @@ The following properties exist on the KVM accelerator ob= ject: through simultaneous grants. For guests with large numbers of PV devices= and high throughput, it may be desirable to increase this value. =20 -OS requirements ---------------- +Xen paravirtual devices +----------------------- + +The Xen PCI platform device is enabled automatically for a Xen guest. This +allows a guest to unplug all emulated devices, in order to use paravirtual +block and network drivers instead. + +Those paravirtual Xen block, network (and console) devices can be created +through the command line, and/or hot-plugged. + +To provide a Xen console device, define a character device and then a devi= ce +of type ``xen-console`` to connect to it. For the Xen console equivalent of +the handy ``-serial mon:stdio`` option, for example: + +.. parsed-literal:: + -chardev -chardev stdio,mux=3Don,id=3Dchar0,signal=3Doff -mon char0 \\ + -device xen-console,chardev=3Dchar0 + +The Xen network device is ``xen-net-device``, which becomes the default NIC +model for emulated Xen guests, meaning that just the default ``-nic user`` +should automatically work and present a Xen network device to the guest. + +Disks can be configured with '``-drive file=3D${GUEST_IMAGE},if=3Dxen``' a= nd will +appear to the guest as ``xvda`` onwards. + +Under Xen, the boot disk is typically available both via IDE emulation, and +as a PV block device. Guest bootloaders typically use IDE to load the guest +kernel, which then unplugs the IDE and continues with the Xen PV block dev= ice. + +This configuration can be achieved as follows: + +.. parsed-literal:: + + |qemu_system| --accel kvm,xen-version=3D0x40011,kernel-irqchip=3Dsplit \\ + -drive file=3D${GUEST_IMAGE},if=3Dxen \\ + -drive file=3D${GUEST_IMAGE},file.locking=3Doff,if=3Dide + +VirtIO devices can also be used; Linux guests may need to be dissuaded from +umplugging them by adding '``xen_emul_unplug=3Dnever``' on their command l= ine. + +Booting Xen PV guests +--------------------- + +Booting PV guest kernels is possible by using the Xen PV shim (a version o= f Xen +itself, designed to run inside a Xen HVM guest and provide memory manageme= nt +services for one guest alone). + +The Xen binary is provided as the ``-kernel`` and the guest kernel itself = (or +PV Grub image) as the ``-initrd`` image, which actually just means the fir= st +multiboot "module". For example: + +.. parsed-literal:: + + |qemu_system| --accel kvm,xen-version=3D0x40011,kernel-irqchip=3Dsplit \\ + -chardev stdio,id=3Dchar0 -device xen-console,chardev=3Dchar0 \\ + -display none -m 1G -kernel xen -initrd bzImage \\ + -append "pv-shim console=3Dxen,pv -- console=3Dhvc0 root=3D/dev/xvd= a1" \\ + -drive file=3D${GUEST_IMAGE},if=3Dxen + +The Xen image must be built with the ``CONFIG_XEN_GUEST`` and ``CONFIG_PV_= SHIM`` +options, and as of Xen 4.17, Xen's PV shim mode does not support using a s= erial +port; it must have a Xen console or it will panic. + +Host OS requirements +-------------------- =20 The minimal Xen support in the KVM accelerator requires the host to be run= ning Linux v5.12 or newer. Later versions add optimisations: Linux v5.17 added --=20 2.40.1