Re: [PATCH v3 28/28] docs: update Xen-on-KVM documentation

From: David Woodhouse <dwmw2@infradead.org>
To: Kevin Wolf <kwolf@redhat.com>, Andrew Cooper <andrew.cooper3@citrix.com>
Cc: "Eric Blake" <eblake@redhat.com>,
	qemu-devel@nongnu.org, "Hanna Reitz" <hreitz@redhat.com>,
	"Stefano Stabellini" <sstabellini@kernel.org>,
	"Anthony Perard" <anthony.perard@citrix.com>,
	"Paul Durrant" <paul@xen.org>,
	"Marc-André Lureau" <marcandre.lureau@redhat.com>,
	"Paolo Bonzini" <pbonzini@redhat.com>,
	"Michael S. Tsirkin" <mst@redhat.com>,
	"Marcel Apfelbaum" <marcel.apfelbaum@gmail.com>,
	"Richard Henderson" <richard.henderson@linaro.org>,
	"Eduardo Habkost" <eduardo@habkost.net>,
	"Jason Wang" <jasowang@redhat.com>,
	"Marcelo Tosatti" <mtosatti@redhat.com>,
	qemu-block@nongnu.org, xen-devel@lists.xenproject.org,
	kvm@vger.kernel.org, "Bernhard Beschow" <shentey@gmail.com>,
	"Joel Upham" <jupham125@gmail.com>
Subject: Re: [PATCH v3 28/28] docs: update Xen-on-KVM documentation
Date: Thu, 26 Oct 2023 17:25:42 +0100	[thread overview]
Message-ID: <7ff6cd4ffe20b54dfb6b5b527d3a85ff3870df55.camel@infradead.org> (raw)
In-Reply-To: <dfed5bba4882921b2c0fe685c9be4444d7e4bd45.camel@infradead.org>

[-- Attachment #1: Type: text/plain, Size: 2943 bytes --]

On Thu, 2023-10-26 at 10:25 +0100, David Woodhouse wrote:
> 
> > So it would have been entirely possible to use -initrd 'bzImage
> > console=hvc0 root=/dev/xvda1' if Xen worked like that.
> 
> Xen does allow that too. I didn't realise our multiboot loader did though.
> 
> So yes, you *can* use  -initrd 'bzImage root=/dev/xvda1'. 
> 
> And you can even load more than one module, it seems. Separate them by
> commas, so -initrd 'bzImage,initrd.img' should work.
> 
> You can even do both at the same time. If you have commas on the kernel
> command line, *double* them:
> 
>  -initrd 'bzImage root=/dev/xvda earlyprintk=xen,,keep,initrd.img'
> 
> I'll update the documentation accordingly.

https://git.infradead.org/users/dwmw2/qemu.git/commitdiff/0b13c0ae39b

+Booting Xen PV guests
+---------------------
+
+Booting PV guest kernels is possible by using the Xen PV shim (a version of Xen
+itself, designed to run inside a Xen HVM guest and provide memory management
+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 first
+multiboot "module". For example:
+
+.. parsed-literal::
+
+  |qemu_system| --accel kvm,xen-version=0x40011,kernel-irqchip=split \\
+       -chardev stdio,id=char0 -device xen-console,chardev=char0 \\
+       -display none  -m 1G  -kernel xen -initrd bzImage \\
+       -append "pv-shim console=xen,pv -- console=hvc0 root=/dev/xvda1" \\
+       -drive file=${GUEST_IMAGE},if=xen
+
+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 serial
+port; it must have a Xen console or it will panic.
+
+The example above provides the guest kernel command line after a separator
+(" ``--`` ") on the Xen command line, and does not provide the guest kernel
+with an actual initramfs, which would need to listed as a second multiboot
+module. For more complicated alternatives, see the
+:ref:`documentation <initrd-reference-label>` for the ``-initrd`` option.
+

I also fixed up the -initrd documentation so that it actually mentions
how to quote commas, using a Xen PV launch as an example:

 ``-initrd "file1 arg=foo,file2"``
     This syntax is only available with multiboot.

-    Use file1 and file2 as modules and pass arg=foo as parameter to the
-    first module.
+    Use file1 and file2 as modules and pass ``arg=foo`` as parameter to the
+    first module. Commas can be provided in module parameters by doubling
+    them on the command line to escape them:
+
+``-initrd "bzImage earlyprintk=xen,,keep root=/dev/xvda1,initrd.img"``
+    Multiboot only. Use bzImage as the first module with
+    "``earlyprintk=xen,keep root=/dev/xvda1``" as its command line,
+    and initrd.img as the second module.

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5965 bytes --]