Bug#759018: [Xen-devel] [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 at verizon.com>

    -Don Slutz

> Signed-off-by: Ian Campbell <ijc at hellion.org.uk>
> Cc: Ian Jackson <Ian.Jackson at eu.citrix.com>
> Cc: Colin Watson <cjwatson at debian.org>
> Cc: 759018 at 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).
> +