Re: [Xen-devel] [PATCH] docs/sphinx: How Xen Boots on x86

[Jan Beulich <jbeulich@suse.com>]

On 06.12.2019 20:34, Andrew Cooper wrote:
> Begin to document how the x86 build of Xen boots.  It is by no means complete,
> but is a start.
> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
> ---
> CC: Jan Beulich <JBeulich@suse.com>
> CC: Wei Liu <wl@xen.org>
> CC: Roger Pau Monné <roger.pau@citrix.com>
> 
> This came about while I sat in SFO waiting for a delayed flight, and was asked
> a question by the Trenchboot folk.
> 
> Writing it down like this already highlights some issues, such as the EFI
> binary having MB1/MB2 headers.

While at least the MB1 ones aren't really necessary, they also don't
do any harm, do they?

> --- /dev/null
> +++ b/docs/hypervisor-guide/x86/how-xen-boots.rst
> @@ -0,0 +1,101 @@
> +.. SPDX-License-Identifier: CC-BY-4.0
> +
> +How Xen Boots
> +=============
> +
> +This is an at-a-glance reference of Xen's booting capabilities and
> +expectations.
> +
> +
> +Build
> +-----
> +
> +A build of xen produces ``xen.gz`` and optionally ``xen.efi`` as final
> +artefacts.
> +
> + * For BIOS, Xen supports the Multiboot 1 and 2 protocols.
> +
> + * For EFI, Xen supports Multiboot 2 with EFI extensions, and native EFI64.
> +
> + * For virtualisation, Xen supports starting directly with the PVH boot
> +   protocol.
> +
> +
> +Objects
> +~~~~~~~
> +
> +To begin with, most object files are compiled and linked.  This includes the
> +Multiboot 1 and 2 headers and entrypoints, including the Multiboot 2 tags for
> +EFI extensions.  When ``CONFIG_PVH_GUEST`` is selected at build time, this
> +includes the PVH entrypoint and associated ELF notes.
> +
> +Depending on whether the compiler supports ``__attribute__((__ms_abi__))`` or
> +not, either an EFI stub is included which nops/fails applicable setup calls,
> +or full EFI support is included.

Perhaps also mention that the linker needs to support the necessary
binary output format? And perhaps "setup and runtime calls"?

> +Protocols and entrypoints
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +All headers and tags are built in ``xen/arch/x86/boot/head.S``
> +
> +The Multiboot 1 headers request aligned modules and memory information.  Entry
> +is via the start of the binary image, which is the ``start`` symbol.  This
> +entrypoint must be started in 32bit mode.
> +
> +The Multiboot 2 headers are more flexible, and in addition request that the
> +image be loaded as high as possible below the 4G boundary, with 2M alignment.
> +Entry is still via the ``start`` symbol as with MB1.

Perhaps explicitly (re)state this is in 32-bit mode?

> +Headers for the EFI MB2 extensions are also present.  These request that
> +``ExitBootServices()`` not be called, and register ``__efi_mb2_start`` as an
> +alternative entrypoint, entered in 64bit mode.
> +
> +If ``CONFIG_PVH_GUEST`` was selected at build time, an Elf note is included
> +which indicates the ability to use the PVH boot protocol, and registers
> +``__pvh_start`` as the entrypoint, entered in 32bit mode.
> +
> +
> +xen.gz
> +~~~~~~
> +
> +The objects are linked together to form ``xen-syms`` which is an ELF64
> +executable with full debugging symbols.  ``xen.gz`` is formed by stripping
> +``xen-syms``, then repackaging the result as an ELF32 object with a single
> +load section at 2MB, and ``gzip``-ing the result.  Despite the ELF32 having a
> +fixed load address, its contents are relocatable.

This is a little ambiguous I guess - most of the code is PIC and as
such relocatable, but not in a way a boot loader could arrange for.

> +Any bootloader which unzips the binary and follows the ELF headers will place
> +it at the 2M boundary and jump to ``start`` which is the identified entry
> +point.  However, Xen depends on being entered with the MB1 or MB2 protocols,
> +and will terminate otherwise.
> +
> +The MB2+EFI entrypoint depends on being entered with the MB2 protocol, and
> +will terminate if the entry protocol is wrong, or if EFI details aren't
> +provided, or if EFI Boot Services are not available.
> +
> +
> +xen.efi
> +~~~~~~~
> +
> +When a PEI-capable toolchain is found, the objects are linked together and a
> +PE64 binary is created.  It can be run directly from the EFI shell, and has

I think it's commonly called PE32+, not PE64.

Maybe also mention the "chainloader" grub command it can be used with?
Or do we consider this uninteresting enough with modern grub?

Jan

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel