[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

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@xxxxxxxxxx>
CC: Jan Beulich <JBeulich@xxxxxxxx>
CC: Wei Liu <wl@xxxxxxx>
CC: Roger Pau Monné <roger.pau@xxxxxxxxxx>

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:

 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%)

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
+   x86/index
diff --git a/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
+A build of xen produces ``xen.gz`` and optionally ``xen.efi`` as final
+ * 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.
+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.
+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.
+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.
+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 
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
 .. toctree::
    :maxdepth: 2
-   code-coverage
+   how-xen-boots

Xen-devel mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.