From nobody Sat Apr 27 06:45:09 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=none (zohomail.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=fail(p=none dis=none) header.from=citrix.com ARC-Seal: i=1; a=rsa-sha256; t=1575660939; cv=none; d=zohomail.com; s=zohoarc; b=Wl2Jdmh76nS7fWffmCJ8K4TPmYRLC+aGXzeKFIogrHPBCwxDGfAKr0BxS8+lHLtis5iawAGpYXescZk734dKGw5MDK4CYFQJjDe52v4MQvURwA4NFVwyW40ZWoIbGRw+rkueY81o4S80tiumjGgiwVjmGjwzYAqdNBsPK1zcVzg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575660939; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=mjyP+oD1FRTR8SHFPJLDZlif543b1AAEHa0BClwDOu0=; b=l6ietbB25PBnHbv5GFk0qD0FPU5xt6Nd8DvU+0G6gZG8QOAturoalKQ4UuCezfPbMWxXKsf9P3AwGEprCx/6D8g2EZwFbTHlnb4CPhlhpr0zBwn0W/kWMiX85ut6FJqC+F6J2Bdkg2UudwBQgbQS5Z47GhP7dt+rR5v338Uvomg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=none (zohomail.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1575660939701341.4827480938999; Fri, 6 Dec 2019 11:35:39 -0800 (PST) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1idJN7-0001az-RC; Fri, 06 Dec 2019 19:34:37 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1idJN7-0001au-22 for xen-devel@lists.xenproject.org; Fri, 06 Dec 2019 19:34:37 +0000 Received: from esa5.hc3370-68.iphmx.com (unknown [216.71.155.168]) by us1-rack-iad1.inumbo.com (Halon) with ESMTPS id 6f3b059c-185f-11ea-a1e1-bc764e2007e4; Fri, 06 Dec 2019 19:34:36 +0000 (UTC) X-Inumbo-ID: 6f3b059c-185f-11ea-a1e1-bc764e2007e4 DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=citrix.com; s=securemail; t=1575660875; h=from:to:cc:subject:date:message-id:mime-version: content-transfer-encoding; bh=9xeg/lE+AiTk29Rz6mGelIt7ZZQlE1fFWW+0IAsb6DQ=; b=JD6R+R3VonBwKVfuIOKjATwnPJTMcSiw724QU2Gxq6iuVjj7bQ7u/q3B cxuzJtC9ylEaQTRhd7qwmhET56WY/tOD31uLFQvUTHHaM0cn0atv4ba+1 F+Q6fibrXy6C1C0/Zbzfj48nyAc7IJpg/t14hIoox6Ic0z3YX+2x8lo8U g=; Authentication-Results: esa5.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none; spf=None smtp.pra=andrew.cooper3@citrix.com; spf=Pass smtp.mailfrom=Andrew.Cooper3@citrix.com; spf=None smtp.helo=postmaster@mail.citrix.com Received-SPF: none (zohomail.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Received-SPF: None (esa5.hc3370-68.iphmx.com: no sender authenticity information available from domain of andrew.cooper3@citrix.com) identity=pra; client-ip=162.221.158.21; receiver=esa5.hc3370-68.iphmx.com; envelope-from="Andrew.Cooper3@citrix.com"; x-sender="andrew.cooper3@citrix.com"; x-conformance=sidf_compatible Received-SPF: Pass (esa5.hc3370-68.iphmx.com: domain of Andrew.Cooper3@citrix.com designates 162.221.158.21 as permitted sender) identity=mailfrom; client-ip=162.221.158.21; receiver=esa5.hc3370-68.iphmx.com; envelope-from="Andrew.Cooper3@citrix.com"; x-sender="Andrew.Cooper3@citrix.com"; x-conformance=sidf_compatible; x-record-type="v=spf1"; x-record-text="v=spf1 ip4:209.167.231.154 ip4:178.63.86.133 ip4:195.66.111.40/30 ip4:85.115.9.32/28 ip4:199.102.83.4 ip4:192.28.146.160 ip4:192.28.146.107 ip4:216.52.6.88 ip4:216.52.6.188 ip4:162.221.158.21 ip4:162.221.156.83 ip4:168.245.78.127 ~all" Received-SPF: None (esa5.hc3370-68.iphmx.com: no sender authenticity information available from domain of postmaster@mail.citrix.com) identity=helo; client-ip=162.221.158.21; receiver=esa5.hc3370-68.iphmx.com; envelope-from="Andrew.Cooper3@citrix.com"; x-sender="postmaster@mail.citrix.com"; x-conformance=sidf_compatible IronPort-SDR: MITqXG25IynX/d1NwW6XwDzXTvCRulWZ3dN9lDkwkb0SQYtGfPG8cZSRFIfp9S0u8GlqTZVt4z q4q/kj8MBQ8GpHpm0fUJ4WDfORSJO1ZlM27MMHTns/8nk0kdxn3BfYLQEJeg/Nn+7gPzews2TL /q72P1ZrdiKwJprRN6K8jDvjXxPsle0uMq/5PYYbipPdpdgkSwoutI8vW7OmvUFs+lDURqpT3o Y0D3qFO5r0Th+dS6pYYJ97SoHlqz+w3J7K0VyznfUVN6DJOyBB5F2XQmKoccYiDsZUs+tzDl7S n00= X-SBRS: 2.7 X-MesageID: 9683212 X-Ironport-Server: esa5.hc3370-68.iphmx.com X-Remote-IP: 162.221.158.21 X-Policy: $RELAYED X-IronPort-AV: E=Sophos;i="5.69,285,1571716800"; d="scan'208";a="9683212" From: Andrew Cooper To: Xen-devel Date: Fri, 6 Dec 2019 19:34:29 +0000 Message-ID: <20191206193429.29165-1-andrew.cooper3@citrix.com> X-Mailer: git-send-email 2.11.0 MIME-Version: 1.0 Subject: [Xen-devel] [PATCH] docs/sphinx: How Xen Boots on x86 X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Andrew Cooper , Wei Liu , Jan Beulich , =?UTF-8?q?Roger=20Pau=20Monn=C3=A9?= Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Begin to document how the x86 build of Xen boots. It is by no means comple= te, but is a start. Signed-off-by: Andrew Cooper Reviewed-by: Jan Beulich --- CC: Jan Beulich CC: Wei Liu CC: Roger Pau Monn=C3=A9 This came about while I sat in SFO waiting for a delayed flight, and was as= ked 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/{ =3D> 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/{ =3D> 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 =20 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 t= he +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 call= s, +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. E= ntry +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 alignme= nt. +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 havin= g a +fixed load address, its contents are relocatable. + +Any bootloader which unzips the binary and follows the ELF headers will pl= ace +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 protocol= s, +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 fir= st +5/16ths of the first page of RAM, with the rest free to use, Xen assumes t= he +top of the page is safe to use. diff --git a/docs/hypervisor-guide/index.rst b/docs/hypervisor-guide/x86/in= dex.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 =20 -Hypervisor documentation -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +x86 +=3D=3D=3D =20 .. toctree:: :maxdepth: 2 =20 - code-coverage + how-xen-boots --=20 2.11.0 _______________________________________________ Xen-devel mailing list Xen-devel@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel