[PATCH] docs: update EFI stub description

[Atish Patra]

On Sat, Feb 6, 2021 at 2:02 AM Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
>
> * 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 at gmx.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.
>

Should we change the title of the paragraph to something like "How to
install EFI image"
 RISC-V image location can be added as well.
>
> @@ -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.
>

Some more clarification is required here as this option is only
enabled with EFI_ARMSTUB_DTB_LOADER.
That config option is not enabled for RISC-V to avoid legacy.

>  "dtb=" is processed in the same manner as the "initrd=" option that is
>  described above.
> --
> 2.30.0
>
>
> _______________________________________________
> linux-riscv mailing list
> linux-riscv at lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/linux-riscv



-- 
Regards,
Atish