Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Heinrich Schuchardt <xypron.glpk@gmx.de>
To:     Ard Biesheuvel <ardb@kernel.org>, Jonathan Corbet <corbet@lwn.net>
Cc:     Paul Walmsley <paul.walmsley@sifive.com>,
        Palmer Dabbelt <palmer@dabbelt.com>,
        Albert Ou <aou@eecs.berkeley.edu>, linux-efi@vger.kernel.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        linux-riscv@lists.infradead.org,
        Heinrich Schuchardt <xypron.glpk@gmx.de>
Subject: [PATCH] docs: update EFI stub description
Date:   Sat,  6 Feb 2021 11:01:15 +0100
Message-Id: <20210206100115.58074-1-xypron.glpk@gmx.de>
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

* Mention RISC-V.
* Update code references.
* initrd=3D does not specify a path relative on the ESP but to the partiti=
on
  from which the EFI stub was loaded (as specified in the loaded image
  protocol).
* Mention that ACPI tables and device trees are alternatives.
* Provide the FDT GUID.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
=2D--
 Documentation/admin-guide/efi-stub.rst | 47 +++++++++++++++-----------
 1 file changed, 27 insertions(+), 20 deletions(-)

diff --git a/Documentation/admin-guide/efi-stub.rst b/Documentation/admin-=
guide/efi-stub.rst
index 833edb0d0bc4..9e1bb79e8655 100644
=2D-- a/Documentation/admin-guide/efi-stub.rst
+++ b/Documentation/admin-guide/efi-stub.rst
@@ -8,15 +8,20 @@ it as an EFI executable. The code that modifies the bzIm=
age header,
 along with the EFI-specific entry point that the firmware loader
 jumps to are collectively known as the "EFI boot stub", and live in
 arch/x86/boot/header.S and arch/x86/boot/compressed/eboot.c,
-respectively. For ARM the EFI stub is implemented in
-arch/arm/boot/compressed/efi-header.S and
-arch/arm/boot/compressed/efi-stub.c. EFI stub code that is shared
-between architectures is in drivers/firmware/efi/libstub.
+respectively. For ARM the EFI stub entry point is implemented in
+arch/arm/boot/compressed/efi-header.S.

-For arm64, there is no compressed kernel support, so the Image itself
-masquerades as a PE/COFF image and the EFI stub is linked into the
-kernel. The arm64 EFI stub lives in arch/arm64/kernel/efi-entry.S
-and drivers/firmware/efi/libstub/arm64-stub.c.
+For ARM64 and RISC-V, there is no compressed kernel support, so the Image
+itself masquerades as a PE/COFF image and the EFI stub is linked into the
+kernel. The EFI stub entry point is in  arch/ARM64/kernel/efi-entry.S for
+ARM64 and in arch/riscv/kernel/efi-header.S for RISC-V.
+
+EFI stub code that is shared between architectures is in
+drivers/firmware/efi/libstub.
+
+The common secondary entry point efi_pe_entry() for ARM, ARM64, and RISC-=
V
+into the stub is in drivers/firmware/efi/libstub/efi-stub.c while x86 use=
s
+drivers/firmware/efi/libstub/x86-stub.c.

 By using the EFI boot stub it's possible to boot a Linux kernel
 without the use of a conventional EFI boot loader, such as grub or
@@ -35,7 +40,7 @@ the extension the EFI firmware loader will refuse to exe=
cute it. It's
 not possible to execute bzImage.efi from the usual Linux file systems
 because EFI firmware doesn't have support for them. For ARM the
 arch/arm/boot/zImage should be copied to the system partition, and it
-may not need to be renamed. Similarly for arm64, arch/arm64/boot/Image
+may not need to be renamed. Similarly for ARM64, arch/arm64/boot/Image
 should be copied but not necessarily renamed.


@@ -55,10 +60,11 @@ multiple initrd files using the "initrd=3D" option. Th=
is is the only EFI
 stub-specific command line parameter, everything else is passed to the
 kernel when it boots.

-The path to the initrd file must be an absolute path from the
-beginning of the ESP, relative path names do not work. Also, the path
-is an EFI-style path and directory elements must be separated with
-backslashes (\). For example, given the following directory layout::
+The path to the initrd file must be an absolute path from the beginning o=
f
+the partition from which the kernel was loaded, relative path names do no=
t
+work. Also, the path is an EFI-style path and directory elements must be
+separated with backslashes (\). For example, given the following director=
y
+layout::

   fs0:>
 	Kernels\
@@ -83,18 +89,19 @@ is passed to bzImage.efi.
 The "dtb=3D" option
 -----------------

-For the ARM and arm64 architectures, a device tree must be provided to
-the kernel. Normally firmware shall supply the device tree via the
-EFI CONFIGURATION TABLE. However, the "dtb=3D" command line option can
-be used to override the firmware supplied device tree, or to supply
-one when firmware is unable to.
+If ACPI tables are not available, a device tree must be provided to the
+kernel. Normally the firmware shall supply the device tree as an EFI
+configuration table with GUID b1b621d5-f19c-41a5-830b-d9152c69aae0.
+However, the "dtb=3D" command line option can be used to override the
+firmware supplied device tree, or to supply one when firmware is unable
+to.

 Please note: Firmware adds runtime configuration information to the
 device tree before booting the kernel. If dtb=3D is used to override
 the device tree, then any runtime data provided by firmware will be
 lost. The dtb=3D option should only be used either as a debug tool, or
-as a last resort when a device tree is not provided in the EFI
-CONFIGURATION TABLE.
+as a last resort when a device tree is not provided as an EFI
+configuration table.

 "dtb=3D" is processed in the same manner as the "initrd=3D" option that i=
s
 described above.
=2D-
2.30.0