[PATCH v2] Documentation/x86: explain LINUX_EFI_INITRD_MEDIA_GUID

[PATCH v2] Documentation/x86: explain LINUX_EFI_INITRD_MEDIA_GUID

[Bagas Sanjaya]

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 and refer to
OVMF/edk2 implementation]
Co-developed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.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.
+
+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

Re: [PATCH v2] Documentation/x86: explain LINUX_EFI_INITRD_MEDIA_GUID

[Hugo Osvaldo Barrera]

On Tue, 16 Sep 2025, at 09:32, 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 and refer to
> OVMF/edk2 implementation]
> Co-developed-by: Bagas Sanjaya <bagasdotme@gmail.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.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

Re: [PATCH v2] Documentation/x86: explain LINUX_EFI_INITRD_MEDIA_GUID

[Jonathan Corbet]

"Hugo Osvaldo Barrera" <hugo@whynothugo.nl> writes:

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

When the documentation is rendered into HTML, that file reference will
be turned into a link automatically, and people reading it on kernel.org
will not notice the difference.

Thanks,

jon

Re: [PATCH v2] Documentation/x86: explain LINUX_EFI_INITRD_MEDIA_GUID

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1109 bytes --]

On Tue, Sep 16, 2025 at 07:40:21AM -0600, Jonathan Corbet wrote:
> "Hugo Osvaldo Barrera" <hugo@whynothugo.nl> writes:
> 
> >> +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.
> 
> When the documentation is rendered into HTML, that file reference will
> be turned into a link automatically, and people reading it on kernel.org
> will not notice the difference.

That's why I keep the file cross-reference...

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2] Documentation/x86: explain LINUX_EFI_INITRD_MEDIA_GUID

[Hugo Osvaldo Barrera]

On Tue, 16 Sep 2025, at 15:40, Jonathan Corbet wrote:
> "Hugo Osvaldo Barrera" <hugo@whynothugo.nl> writes:
>
>>> +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.
>
> When the documentation is rendered into HTML, that file reference will
> be turned into a link automatically, and people reading it on kernel.org
> will not notice the difference.
>

Thanks for the clarification.
I mis-interpreted this previously.
Sorry for the noise.


-- 
Hugo