Message-Id: <b629ff7e-a223-467f-8e32-78f825bd31ac@app.fastmail.com>
Date: Tue, 16 Sep 2025 10:54:39 +0200
From: "Hugo Osvaldo Barrera" <hugo@...nothugo.nl>
To: "Bagas Sanjaya" <bagasdotme@...il.com>,
 "Linux Kernel Mailing List" <linux-kernel@...r.kernel.org>,
 "Linux Documentation" <linux-doc@...r.kernel.org>,
 "Linux EFI" <linux-efi@...r.kernel.org>
Cc: "Ard Biesheuvel" <ardb@...nel.org>, "Jonathan Corbet" <corbet@....net>,
 "Thomas Gleixner" <tglx@...utronix.de>, "Ingo Molnar" <mingo@...hat.com>,
 "Borislav Petkov" <bp@...en8.de>,
 "Dave Hansen" <dave.hansen@...ux.intel.com>, x86@...nel.org,
 "H. Peter Anvin" <hpa@...or.com>, "Randy Dunlap" <rdunlap@...radead.org>
Subject: Re: [PATCH v2] Documentation/x86: explain LINUX_EFI_INITRD_MEDIA_GUID



On Tue, 16 Sep 2025, at 09:32, Bagas Sanjaya wrote:
> From: Hugo Osvaldo Barrera <hugo@...nothugo.nl>
>
> Since the Handover Protocol was deprecated, the recommended approach is
> to provide an initrd using a UEFI boot service with the
> LINUX_EFI_INITRD_MEDIA_GUID device path. Documentation for the new
> approach has been no more than an admonition with a link to an existing
> implementation.
>
> Provide a short explanation of this functionality, to ease future
> implementations without having to reverse engineer existing ones.
>
> Signed-off-by: Hugo Osvaldo Barrera <hugo@...nothugo.nl>
> Link: https://lore.kernel.org/r/20250428131206.8656-2-hugo@whynothugo.nl
> [Bagas: Don't use :ref: link to EFI stub documentation and refer to
> OVMF/edk2 implementation]
> Co-developed-by: Bagas Sanjaya <bagasdotme@...il.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@...il.com>
> ---
> Changes since v1 [1]:
>
>   * Apply wording suggestion (Ard)
>   * Replace candyboot reference with OVMF (Ard)
>   * Invert patch subject prefix
>
> [1]: 
> https://lore.kernel.org/linux-doc/20250910015738.14848-2-bagasdotme@gmail.com/
>
>  Documentation/admin-guide/efi-stub.rst |  3 ++
>  Documentation/arch/x86/boot.rst        | 38 ++++++++++++++++++++------
>  2 files changed, 33 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/admin-guide/efi-stub.rst 
> b/Documentation/admin-guide/efi-stub.rst
> index 090f3a185e1897..f8e7407698bd2a 100644
> --- a/Documentation/admin-guide/efi-stub.rst
> +++ b/Documentation/admin-guide/efi-stub.rst
> @@ -79,6 +79,9 @@ because the image we're executing is interpreted by 
> the EFI shell,
>  which understands relative paths, whereas the rest of the command line
>  is passed to bzImage.efi.
> 
> +.. hint::
> +   It is also possible to provide an initrd using a Linux-specific UEFI
> +   protocol at boot time. See :ref:`pe-coff-entry-point` for details.
> 
>  The "dtb=" option
>  -----------------
> diff --git a/Documentation/arch/x86/boot.rst 
> b/Documentation/arch/x86/boot.rst
> index 77e6163288db08..32eea3d2807e1c 100644
> --- a/Documentation/arch/x86/boot.rst
> +++ b/Documentation/arch/x86/boot.rst
> @@ -1431,12 +1431,34 @@ The boot loader *must* fill out the following 
> fields in bp::
>  All other fields should be zero.
> 
>  .. note::
> -     The EFI Handover Protocol is deprecated in favour of the ordinary PE/COFF
> -     entry point, combined with the LINUX_EFI_INITRD_MEDIA_GUID based initrd
> -     loading protocol (refer to [0] for an example of the bootloader side of
> -     this), which removes the need for any knowledge on the part of the EFI
> -     bootloader regarding the internal representation of boot_params or any
> -     requirements/limitations regarding the placement of the command line
> -     and ramdisk in memory, or the placement of the kernel image itself.
> +   The EFI Handover Protocol is deprecated in favour of the ordinary PE/COFF
> +   entry point described below.
> 
> -[0] 
> https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0
> +.. _pe-coff-entry-point:
> +
> +PE/COFF entry point
> +===================
> +
> +When compiled with ``CONFIG_EFI_STUB=y``, the kernel can be executed 
> as a
> +regular PE/COFF binary. See Documentation/admin-guide/efi-stub.rst for
> +implementation details.

I must insist that it's a terrible idea to replace an actual link with the
name of the source file.

This might be (marginally) more convenient for somebody who's editing the
documentation, but it becomes completely useless for somebody who's READING
the documentation. Documentation needs to target readers.

For someone reading https://www.kernel.org/doc/html/latest/arch/x86/boot.html,
the above filename conveys no useful information.

> +
> +The stub loader can request the initrd via a UEFI protocol. For this 
> to work,
> +the firmware or bootloader needs to register a handle which carries
> +implementations of the ``EFI_LOAD_FILE2`` protocol and the device path
> +protocol exposing the ``LINUX_EFI_INITRD_MEDIA_GUID`` vendor media 
> device path.
> +In this case, a kernel booting via the EFI stub will invoke
> +``LoadFile2::LoadFile()`` method on the registered protocol to 
> instruct the
> +firmware to load the initrd into a memory location chosen by the 
> kernel/EFI
> +stub.
> +
> +This approach removes the need for any knowledge on the part of the EFI
> +bootloader regarding the internal representation of boot_params or any
> +requirements/limitations regarding the placement of the command line 
> and
> +ramdisk in memory, or the placement of the kernel image itself.
> +
> +For sample implementations, refer to `the original u-boot 
> implementation`_ or
> +`the OVMF implementation`_.
> +
> +.. _the original u-boot implementation: 
> https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0
> +.. _the OVMF implementation: 
> https://github.com/tianocore/edk2/blob/1780373897f12c25075f8883e073144506441168/OvmfPkg/LinuxInitrdDynamicShellCommand/LinuxInitrdDynamicShellCommand.c
>
> base-commit: f44a29784f685804d9970cfb0d3439c9e30981d7
> -- 
> An old man doll... just what I always wanted! - Clara

-- 
Hugo

Powered by blists - more mailing lists