linux-kernel - Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <CAMj1kXHCi1pr3XNzwe7b7EFBkPGjkppeNWNSvy4wU1VBHj9kfA@mail.gmail.com>
Date: Thu, 11 Sep 2025 08:46:50 +0200
From: Ard Biesheuvel <ardb@...nel.org>
To: Bagas Sanjaya <bagasdotme@...il.com>
Cc: Linux Kernel Mailing List <linux-kernel@...r.kernel.org>, 
	Linux Documentation <linux-doc@...r.kernel.org>, Linux EFI <linux-efi@...r.kernel.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>, Hugo Osvaldo Barrera <hugo@...nothugo.nl>
Subject: Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

On Wed, 10 Sept 2025 at 03:58, Bagas Sanjaya <bagasdotme@...il.com> 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]
> Co-developed-by: Bagas Sanjaya <bagasdotme@...il.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@...il.com>
> ---
>  Documentation/admin-guide/efi-stub.rst |  3 +++
>  Documentation/arch/x86/boot.rst        | 35 ++++++++++++++++++++------
>  2 files changed, 30 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/admin-guide/efi-stub.rst b/Documentation/admin-guide/efi-stub.rst
> index 090f3a185e1897..2f0f040f6913a4 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 UEFI boot services. See
> +   :ref:`pe-coff-entry-point` for details.
>

Better say 'using a Linux-specific UEFI protocol at boot time'. The
boot services are a specific set of APIs none of which have anything
to do with initrd loading.

>  The "dtb=" option
>  -----------------
> diff --git a/Documentation/arch/x86/boot.rst b/Documentation/arch/x86/boot.rst
> index 77e6163288db08..fadbe66517bdf2 100644
> --- a/Documentation/arch/x86/boot.rst
> +++ b/Documentation/arch/x86/boot.rst
> @@ -1431,12 +1431,31 @@ 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.
> +
> +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 implements the

... 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.

> +``EFI_LOAD_FILE2`` protocol with the ``LINUX_EFI_INITRD_MEDIA_GUID`` device
> +path. In this case, a kernel booting via the EFI stub will use the ``LoadFile``
> +function on the registered handle to obtain a reference to the initrd.
> +

... 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 implementation in candyboot`_.
> +
> +.. _the original u-boot implementation: https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0
> +.. _the implementation in candyboot: https://git.sr.ht/~whynothugo/candyboot/tree/4097b2538d7f1cf85f03922bf42409490b666202/item/src/main.rs#L225
>

What is candyboot, and why are we adding this plug for it into the
Linux documentation?