[PATCH] docs: Introduce specification for pv bootloader chainloading paths/formats.

[PATCH] docs: Introduce specification for pv bootloader chainloading paths/formats.

[Ian Campbell]

In order to support pvgrub (or other bootloader) from dom0 chainloading a
pvgrub (or other) from within the domU filesystem we need a standard for where
the stage 1 bootloader should look and what it should expect to find there.

Add a document along those lines.

Signed-off-by: Ian Campbell <ijc@hellion.org.uk>
Cc: Ian Jackson <Ian.Jackson@eu.citrix.com>
Cc: Colin Watson <cjwatson@debian.org>
Cc: 759018@bugs.debian.org
---
 docs/misc/xenpv-bootloader.markdown | 58 +++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 docs/misc/xenpv-bootloader.markdown

diff --git a/docs/misc/xenpv-bootloader.markdown b/docs/misc/xenpv-bootloader.markdown
new file mode 100644
index 0000000..a5a0665
--- /dev/null
+++ b/docs/misc/xenpv-bootloader.markdown
@@ -0,0 +1,58 @@
+# Xen PV Bootloader Protocol
+
+## Introduction
+
+One method for booting a Xen PV guest is to use a PV bootloader, that
+is, a bootloader which is itself a PV kernel but which behaves as a
+bootloader (examples include the pvgrub-legacy and grub2 targeting
+Xen).
+
+In many cases the user wishes to manage this PV bootloader from within
+the guest, and therefore wishes to chainload something from the guest
+filesystem, most likely via a stage 1 PV bootloader provided by dom0.
+
+The purpose of this document is to define the paths within the guest
+filesystem where a stage 1 bootloader should look for the in-guest PV
+bootloader to load and the protocol/format expected from the
+to-be-chainloaded bootloader.
+
+## Protocol
+
+### x86
+
+The bootloader binary should be an ELF file of the appropriate type
+(32- or 64-bit). It should contain the standard Xen ELF notes allowing
+it to be loaded by the Xen toolstack domain builder (TBD: Reference).
+
+### ARM
+
+TBD
+
+## Paths
+
+The second stage bootloader should be installed into the guest filesystem as:
+
+ * `/boot/xen/pvboot-<ARCH>.elf`
+
+Where `<ARCH>` is the first element of the GNU triplet e.g. one of:
+
+ * i386 (nb only i386, not i686 etc), corresponding to the Xen x86\_32(p) arch;
+ * x86\_64, corresponding to the Xen x86\_64 arch;
+ * arm, corresponding to the Xen arm32 arch;
+ * aarch64 corresponding to the Xen arm64 arch;
+
+It is allowable for `/boot` to be a separate filesystem from `/` and
+therefore stage 1 bootloaders should search
+`/boot/xen/pvboot-<ARCH>.elf` and `/xen/pvboot-<ARCH>.elf` (in that
+order). The `xen` directory should be on the same filesystem as /boot
+and therefore it is not necessary to search for /pvboot-<ARCH>.elf.
+
+On processors which have 32- and 64-bit variants (i.e. x86\_32/x86\_64
+or arm32/arm64) it is not in general possible under Xen for a
+bootloader to boot a kernel of a different width from itself, and this
+extends to chainloading from a stage one. Therefore it is permissible
+to have both `/boot/xen/pvboot-i386.elf` and
+`/boot/xen/pvboot-x86\_64.elf` present in a guest to be used by the
+appropriate stage 1 (e.g. for systems with 32-bit userspace and an
+optional 64-bit kernel).
+
-- 
2.0.1

Re: [PATCH] docs: Introduce specification for pv bootloader chainloading paths/formats.

[Don Slutz]

On 08/26/14 14:46, Ian Campbell wrote:
> In order to support pvgrub (or other bootloader) from dom0 chainloading a
> pvgrub (or other) from within the domU filesystem we need a standard for where
> the stage 1 bootloader should look and what it should expect to find there.
>
> Add a document along those lines.

Looks good to me, so

Reviewed-by:  Don Slutz <dslutz@verizon.com>

    -Don Slutz

> Signed-off-by: Ian Campbell <ijc@hellion.org.uk>
> Cc: Ian Jackson <Ian.Jackson@eu.citrix.com>
> Cc: Colin Watson <cjwatson@debian.org>
> Cc: 759018@bugs.debian.org
> ---
>   docs/misc/xenpv-bootloader.markdown | 58 +++++++++++++++++++++++++++++++++++++
>   1 file changed, 58 insertions(+)
>   create mode 100644 docs/misc/xenpv-bootloader.markdown
>
> diff --git a/docs/misc/xenpv-bootloader.markdown b/docs/misc/xenpv-bootloader.markdown
> new file mode 100644
> index 0000000..a5a0665
> --- /dev/null
> +++ b/docs/misc/xenpv-bootloader.markdown
> @@ -0,0 +1,58 @@
> +# Xen PV Bootloader Protocol
> +
> +## Introduction
> +
> +One method for booting a Xen PV guest is to use a PV bootloader, that
> +is, a bootloader which is itself a PV kernel but which behaves as a
> +bootloader (examples include the pvgrub-legacy and grub2 targeting
> +Xen).
> +
> +In many cases the user wishes to manage this PV bootloader from within
> +the guest, and therefore wishes to chainload something from the guest
> +filesystem, most likely via a stage 1 PV bootloader provided by dom0.
> +
> +The purpose of this document is to define the paths within the guest
> +filesystem where a stage 1 bootloader should look for the in-guest PV
> +bootloader to load and the protocol/format expected from the
> +to-be-chainloaded bootloader.
> +
> +## Protocol
> +
> +### x86
> +
> +The bootloader binary should be an ELF file of the appropriate type
> +(32- or 64-bit). It should contain the standard Xen ELF notes allowing
> +it to be loaded by the Xen toolstack domain builder (TBD: Reference).
> +
> +### ARM
> +
> +TBD
> +
> +## Paths
> +
> +The second stage bootloader should be installed into the guest filesystem as:
> +
> + * `/boot/xen/pvboot-<ARCH>.elf`
> +
> +Where `<ARCH>` is the first element of the GNU triplet e.g. one of:
> +
> + * i386 (nb only i386, not i686 etc), corresponding to the Xen x86\_32(p) arch;
> + * x86\_64, corresponding to the Xen x86\_64 arch;
> + * arm, corresponding to the Xen arm32 arch;
> + * aarch64 corresponding to the Xen arm64 arch;
> +
> +It is allowable for `/boot` to be a separate filesystem from `/` and
> +therefore stage 1 bootloaders should search
> +`/boot/xen/pvboot-<ARCH>.elf` and `/xen/pvboot-<ARCH>.elf` (in that
> +order). The `xen` directory should be on the same filesystem as /boot
> +and therefore it is not necessary to search for /pvboot-<ARCH>.elf.
> +
> +On processors which have 32- and 64-bit variants (i.e. x86\_32/x86\_64
> +or arm32/arm64) it is not in general possible under Xen for a
> +bootloader to boot a kernel of a different width from itself, and this
> +extends to chainloading from a stage one. Therefore it is permissible
> +to have both `/boot/xen/pvboot-i386.elf` and
> +`/boot/xen/pvboot-x86\_64.elf` present in a guest to be used by the
> +appropriate stage 1 (e.g. for systems with 32-bit userspace and an
> +optional 64-bit kernel).
> +

Re: [PATCH] docs: Introduce specification for pv bootloader chainloading paths/formats.

[Colin Watson]

On Tue, Aug 26, 2014 at 07:46:58PM +0100, Ian Campbell wrote:
> +## Protocol
> +
> +### x86
> +
> +The bootloader binary should be an ELF file of the appropriate type
> +(32- or 64-bit). It should contain the standard Xen ELF notes allowing
> +it to be loaded by the Xen toolstack domain builder (TBD: Reference).
> +
> +### ARM
> +
> +TBD
> +
> +## Paths
> +
> +The second stage bootloader should be installed into the guest filesystem as:
> +
> + * `/boot/xen/pvboot-<ARCH>.elf`

It just occurred to me that not every (future) platform may necessarily
want this to be ELF, so maybe we shouldn't hardcode that in the
architecture-independent part of the name.  If you think this might be a
reasonable concern then you might want to adjust this.  Otherwise LGTM.

Reviewed-by: Colin Watson <cjwatson@debian.org>

Thanks,

-- 
Colin Watson                                       [cjwatson@debian.org]

Re: [PATCH] docs: Introduce specification for pv bootloader chainloading paths/formats.

[Ian Campbell]

On Wed, 2014-08-27 at 00:02 +0100, Colin Watson wrote:
> On Tue, Aug 26, 2014 at 07:46:58PM +0100, Ian Campbell wrote:
> > +## Protocol
> > +
> > +### x86
> > +
> > +The bootloader binary should be an ELF file of the appropriate type
> > +(32- or 64-bit). It should contain the standard Xen ELF notes allowing
> > +it to be loaded by the Xen toolstack domain builder (TBD: Reference).
> > +
> > +### ARM
> > +
> > +TBD
> > +
> > +## Paths
> > +
> > +The second stage bootloader should be installed into the guest filesystem as:
> > +
> > + * `/boot/xen/pvboot-<ARCH>.elf`
> 
> It just occurred to me that not every (future) platform may necessarily
> want this to be ELF, so maybe we shouldn't hardcode that in the
> architecture-independent part of the name.  If you think this might be a
> reasonable concern then you might want to adjust this.

This crossed my mind too (it might even be the case on arm*, not sure
yet). My thinking was that this spec would already need adjusting for
this (to describe the non-ELF thing, if nothing else) so this it could
be tweaked then too.

Or I could e.g. omit all the vestigial ARM stuff and explicitly list the
two x86 options, bypassing the whole question of future arches, who
would then need to add themselves to this doc.

>   Otherwise LGTM.
> 
> Reviewed-by: Colin Watson <cjwatson@debian.org>

Thanks.

Re: [PATCH] docs: Introduce specification for pv bootloader chainloading paths/formats.

[Ian Campbell]

On Wed, 2014-08-27 at 00:16 +0100, Ian Campbell wrote:
> > It just occurred to me that not every (future) platform may necessarily
> > want this to be ELF, so maybe we shouldn't hardcode that in the
> > architecture-independent part of the name.  If you think this might be a
> > reasonable concern then you might want to adjust this.
> 
> This crossed my mind too (it might even be the case on arm*, not sure
> yet). My thinking was that this spec would already need adjusting for
> this (to describe the non-ELF thing, if nothing else) so this it could
> be tweaked then too.
> 
> Or I could e.g. omit all the vestigial ARM stuff and explicitly list the
> two x86 options, bypassing the whole question of future arches, who
> would then need to add themselves to this doc.

While talking to Colin IRL a couple of nights ago I realised that this
stuff is most likely more specific to x86 PV than I had originally
thought. ARM for example is far more likely to follow the ARM VM spec[0]
and use a UEFI firmware as the stage 1 and the EFI bootprotocol to find
and execute the stage 2 (e.g. grub.efi from the ESP). And who knows what
any future arches might do.

So I intend to update the doc to be less arch agnostic and make it just
cover x86. If some future arch wants something along these lines then
they would have to patch this spec anyway.

Ian.

[0]
http://lists.linaro.org/pipermail/cross-distro/2014-March/000668.html
> 
> >   Otherwise LGTM.
> > 
> > Reviewed-by: Colin Watson <cjwatson@debian.org>
> 
> Thanks.
> 
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xen.org
> http://lists.xen.org/xen-devel