From: Hugo Osvaldo Barrera <hugo@whynothugo.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@whynothugo.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@gmail.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.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.
 
 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
+``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.
+
+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

base-commit: f44a29784f685804d9970cfb0d3439c9e30981d7
-- 
An old man doll... just what I always wanted! - Clara

On Wed, 10 Sept 2025 at 03:58, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> From: Hugo Osvaldo Barrera <hugo@whynothugo.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@whynothugo.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@gmail.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.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?

On Thu, Sep 11, 2025 at 08:46:50AM +0200, Ard Biesheuvel wrote:
> On Wed, 10 Sept 2025 at 03:58, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> > +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.

Thanks for the wording suggestions!

-- 
An old man doll... just what I always wanted! - Clara

Hi Bagas,

This mostly looks good to me. I have a couple of small comments
below.


On 9/9/25 6:57 PM, Bagas Sanjaya wrote:
> From: Hugo Osvaldo Barrera <hugo@whynothugo.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@whynothugo.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@gmail.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.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.
>  
>  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

> +.. _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
> +``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.

drivers/firmware/efi/libstub/efi-stub-helper.c (line 509) says LoadFile2
protocol. Is that the same as the LoadFile function?

https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0
(the link below) also says LoadFile2() 4 times (and LoadFile 0 times).

thanks.
-- 
~Randy

On Tue, Sep 09, 2025 at 08:25:34PM -0700, Randy Dunlap wrote:
> On 9/9/25 6:57 PM, Bagas Sanjaya wrote:
> > +.. _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
> > +``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.
> 
> drivers/firmware/efi/libstub/efi-stub-helper.c (line 509) says LoadFile2
> protocol. Is that the same as the LoadFile function?
> 
> https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0
> (the link below) also says LoadFile2() 4 times (and LoadFile 0 times).

From UEFI spec [1], both LoadFile and LoadFile2 protocol versions of LoadFile()
function has same prototype but somewhat different in behavior. To answer
your question, however, I think so.

EFI folks, what are your opinions?

Thanks.

[1]: https://uefi.org/specs/UEFI/2.10/13_Protocols_Media_Access.html

-- 
An old man doll... just what I always wanted! - Clara

On September 9, 2025 11:01:54 PM PDT, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>On Tue, Sep 09, 2025 at 08:25:34PM -0700, Randy Dunlap wrote:
>> On 9/9/25 6:57 PM, Bagas Sanjaya wrote:
>> > +.. _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
>> > +``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.
>> 
>> drivers/firmware/efi/libstub/efi-stub-helper.c (line 509) says LoadFile2
>> protocol. Is that the same as the LoadFile function?
>> 
>> https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0
>> (the link below) also says LoadFile2() 4 times (and LoadFile 0 times).
>
>From UEFI spec [1], both LoadFile and LoadFile2 protocol versions of LoadFile()
>function has same prototype but somewhat different in behavior. To answer
>your question, however, I think so.
>
>EFI folks, what are your opinions?
>
>Thanks.
>
>[1]: https://uefi.org/specs/UEFI/2.10/13_Protocols_Media_Access.html
>

Sounds like the code was updated but not the documentation.

On Wed, 10 Sept 2025 at 22:10, H. Peter Anvin <hpa@zytor.com> wrote:
>
> On September 9, 2025 11:01:54 PM PDT, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> >On Tue, Sep 09, 2025 at 08:25:34PM -0700, Randy Dunlap wrote:
> >> On 9/9/25 6:57 PM, Bagas Sanjaya wrote:
> >> > +.. _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
> >> > +``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.
> >>
> >> drivers/firmware/efi/libstub/efi-stub-helper.c (line 509) says LoadFile2
> >> protocol. Is that the same as the LoadFile function?
> >>
> >> https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0
> >> (the link below) also says LoadFile2() 4 times (and LoadFile 0 times).
> >
> >From UEFI spec [1], both LoadFile and LoadFile2 protocol versions of LoadFile()
> >function has same prototype but somewhat different in behavior. To answer
> >your question, however, I think so.
> >
> >EFI folks, what are your opinions?
> >
> >Thanks.
> >
> >[1]: https://uefi.org/specs/UEFI/2.10/13_Protocols_Media_Access.html
> >
>
> Sounds like the code was updated but not the documentation.

The UEFI spec defines two protocols, LoadFile and LoadFile2, under two
different GUIDs. They differ slightly in behavior when used to boot
the OS loader from the boot manager, but are identical when used in
other contexts.

The protocol definition (i.e., the struct layout) is identical: they
both implement a LoadFile() method with the same prototype,

So the answer the question: the LoadFile2 *protocol* is not the same
as the LoadFile *function*. And to be pedantic, no LoadFile function
is defined in the spec. It does define LoadFile::LoadFile() and
LoadFile2::LoadFile() protocol methods.