Message-Id: <20210206100115.58074-1-xypron.glpk@gmx.de>
Date:   Sat,  6 Feb 2021 11:01:15 +0100
From:   Heinrich Schuchardt <xypron.glpk@....de>
To:     Ard Biesheuvel <ardb@...nel.org>, Jonathan Corbet <corbet@....net>
Cc:     Paul Walmsley <paul.walmsley@...ive.com>,
        Palmer Dabbelt <palmer@...belt.com>,
        Albert Ou <aou@...s.berkeley.edu>, linux-efi@...r.kernel.org,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        linux-riscv@...ts.infradead.org,
        Heinrich Schuchardt <xypron.glpk@....de>
Subject: [PATCH] docs: update EFI stub description

* Mention RISC-V.
* Update code references.
* initrd= does not specify a path relative on the ESP but to the partition
  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@....de>
---
 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
--- 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 bzImage 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 uses
+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 execute 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=" option. This 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 of
+the partition from which the kernel was loaded, 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::

   fs0:>
 	Kernels\
@@ -83,18 +89,19 @@ is passed to bzImage.efi.
 The "dtb=" 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=" 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=" 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= is used to override
 the device tree, then any runtime data provided by firmware will be
 lost. The dtb= 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=" is processed in the same manner as the "initrd=" option that is
 described above.
--
2.30.0

Powered by blists - more mailing lists