docs/sphinx: How Xen Boots on x86
diff mbox series

Message ID 20191206193429.29165-1-andrew.cooper3@citrix.com
State New
Headers show
Series
  • docs/sphinx: How Xen Boots on x86
Related show

Commit Message

Andrew Cooper Dec. 6, 2019, 7:34 p.m. UTC
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.

A rendered version is available here:
  https://andrewcoop-xen.readthedocs.io/en/docs-devel/hypervisor-guide/x86/how-xen-boots.html

---
 docs/hypervisor-guide/index.rst             |   2 +
 docs/hypervisor-guide/x86/how-xen-boots.rst | 101 ++++++++++++++++++++++++++++
 docs/hypervisor-guide/{ => x86}/index.rst   |   6 +-
 3 files changed, 106 insertions(+), 3 deletions(-)
 create mode 100644 docs/hypervisor-guide/x86/how-xen-boots.rst
 copy docs/hypervisor-guide/{ => x86}/index.rst (51%)

Comments

Jan Beulich Dec. 9, 2019, 3:20 p.m. UTC | #1
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
Andrew Cooper Dec. 9, 2019, 4:42 p.m. UTC | #2
On 09/12/2019 15:20, Jan Beulich wrote:
> 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?

At least one version of iPXE seems to prefer MB2 over PE, which is why I
was asked "where are Xen's entrypoints?" in the first place.

>
>> --- /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"?

Link time behaviour is (deliberately) in a later section.

>
>> +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.

I don't follow your concern.

Everything which needs to be is position independent (subject to being
loaded on a 2M boundary IIRC), and this property is requested by the MB2
header.

>
>> +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.

Ok., because by definition, it can stack.

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

I wasn't planning to consider chainloading, as it isn't really relevant
to how Xen starts, and can be stacked in many more interesting ways than
usefully be described.

~Andrew
Jan Beulich Dec. 10, 2019, 7:52 a.m. UTC | #3
On 09.12.2019 17:42, Andrew Cooper wrote:
> On 09/12/2019 15:20, Jan Beulich wrote:
>> On 06.12.2019 20:34, Andrew Cooper wrote:
>>> +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"?
> 
> Link time behaviour is (deliberately) in a later section.

I realize(d) this, but the statement above is simply not true without
also mentioning required linker capabilities: The object files won't
have "full EFI support included" in this case. So I'd expect a "see
also" here at the very least.

>>> +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.
> 
> I don't follow your concern.
> 
> Everything which needs to be is position independent (subject to being
> loaded on a 2M boundary IIRC), and this property is requested by the MB2
> header.

Oh, sorry, it had been too many years of sym_phys() before it became
sym_offs(). You're right.

>>> +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.
> 
> Ok., because by definition, it can stack.

How does stacking come into play here?

Jan
Andrew Cooper Dec. 10, 2019, 9:55 a.m. UTC | #4
On 10/12/2019 07:52, Jan Beulich wrote:
> On 09.12.2019 17:42, Andrew Cooper wrote:
>> On 09/12/2019 15:20, Jan Beulich wrote:
>>> On 06.12.2019 20:34, Andrew Cooper wrote:
>>>> +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"?
>> Link time behaviour is (deliberately) in a later section.
> I realize(d) this, but the statement above is simply not true without
> also mentioning required linker capabilities: The object files won't
> have "full EFI support included" in this case. So I'd expect a "see
> also" here at the very least.

Note how XEN_BUILD_EFI and XEN_BUILD_PE are different, one by compiler
support for ms_abi, and one by linker support for i386pep.

Linker support for i386pep is not required at all to get EFI support in
Xen.  This is how the MB2+EFI path is constructed.


>
>>>> +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.
>> I don't follow your concern.
>>
>> Everything which needs to be is position independent (subject to being
>> loaded on a 2M boundary IIRC), and this property is requested by the MB2
>> header.
> Oh, sorry, it had been too many years of sym_phys() before it became
> sym_offs(). You're right.

Yeah - it was fixed in the MB1 days, but this is no longer the case.

>
>>>> +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.
>> Ok., because by definition, it can stack.
> How does stacking come into play here?

Mis-paste on my behalf (that text was an early version discussing
chainloading).  That should have ended at ok.

~Andrew
Jan Beulich Dec. 10, 2019, 10:04 a.m. UTC | #5
On 10.12.2019 10:55, Andrew Cooper wrote:
> On 10/12/2019 07:52, Jan Beulich wrote:
>> On 09.12.2019 17:42, Andrew Cooper wrote:
>>> On 09/12/2019 15:20, Jan Beulich wrote:
>>>> On 06.12.2019 20:34, Andrew Cooper wrote:
>>>>> +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"?
>>> Link time behaviour is (deliberately) in a later section.
>> I realize(d) this, but the statement above is simply not true without
>> also mentioning required linker capabilities: The object files won't
>> have "full EFI support included" in this case. So I'd expect a "see
>> also" here at the very least.
> 
> Note how XEN_BUILD_EFI and XEN_BUILD_PE are different, one by compiler
> support for ms_abi, and one by linker support for i386pep.
> 
> Linker support for i386pep is not required at all to get EFI support in
> Xen.  This is how the MB2+EFI path is constructed.

Hmm, indeed. Meaning the build reporting "EFI support disabled" has
been wrong since the splitting of the two. Should now be something
like "Not generating xen.efi", I guess.

With the minor re-stating of 32-bit mode and the PE32+ naming
adjustment then
Reviewed-by: Jan Beulich <jbeulich@suse.com>

Jan

Patch
diff mbox series

diff --git a/docs/hypervisor-guide/index.rst b/docs/hypervisor-guide/index.rst
index 8ea8fcb145..e4393b0697 100644
--- a/docs/hypervisor-guide/index.rst
+++ b/docs/hypervisor-guide/index.rst
@@ -7,3 +7,5 @@  Hypervisor documentation
    :maxdepth: 2
 
    code-coverage
+
+   x86/index
diff --git a/docs/hypervisor-guide/x86/how-xen-boots.rst b/docs/hypervisor-guide/x86/how-xen-boots.rst
new file mode 100644
index 0000000000..99774b7183
--- /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.
+
+
+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.
+
+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.
+
+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
+``efi_start`` as its entry symbol.
+
+.. note::
+
+   xen.efi does contain all MB1/MB2/PVH tags included in the rest of the
+   build.  However, entry via anything other than the EFI64 protocol is
+   unsupported, and won't work.
+
+
+Boot
+----
+
+Xen, once loaded into memory, identifies its position in order to relocate
+system structures.  For 32bit entrypoints, this necessarily requires a call
+instruction, and therefore a stack, but none of the ABIs provide one.
+
+Overall, given that on a BIOS-based system, the IVT and BDA occupy the first
+5/16ths of the first page of RAM, with the rest free to use, Xen assumes the
+top of the page is safe to use.
diff --git a/docs/hypervisor-guide/index.rst b/docs/hypervisor-guide/x86/index.rst
similarity index 51%
copy from docs/hypervisor-guide/index.rst
copy to docs/hypervisor-guide/x86/index.rst
index 8ea8fcb145..c10cd1d7c0 100644
--- a/docs/hypervisor-guide/index.rst
+++ b/docs/hypervisor-guide/x86/index.rst
@@ -1,9 +1,9 @@ 
 .. SPDX-License-Identifier: CC-BY-4.0
 
-Hypervisor documentation
-========================
+x86
+===
 
 .. toctree::
    :maxdepth: 2
 
-   code-coverage
+   how-xen-boots