[PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[PATCH] x86/Documentation: 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]
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

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Randy Dunlap]

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

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Bagas Sanjaya]

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

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

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

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[H. Peter Anvin]

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.

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Ard Biesheuvel]

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.

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Ard Biesheuvel]

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?

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Hugo Osvaldo Barrera]

On Thu, 11 Sep 2025, at 08:46, Ard Biesheuvel wrote:
> 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.
>> +

This should be a link rather than a path to the source file.

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

Might be worth mentioning that this protocol is defined in the UEFI spec,
section 13.2.

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

It's a UEFI stub loader which can load the Linux kernel and provide it with an
initramfs using the above described protocol.

The original version of this patch was based on my notes researching _how_
to implement this stub loader. The implementation is quite minimal, so I think
it serves as a useful reference example.

-- 
Hugo

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Bagas Sanjaya]

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

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

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

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Bagas Sanjaya]

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

On Thu, Sep 11, 2025 at 01:22:54PM +0200, Hugo Osvaldo Barrera wrote:
> On Thu, 11 Sep 2025, at 08:46, Ard Biesheuvel wrote:
> > On Wed, 10 Sept 2025 at 03:58, Bagas Sanjaya <bagasdotme@gmail.com> 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.
> >> +
> 
> This should be a link rather than a path to the source file.

I think you miss the point of Jon's comment on your original submission [1].
Long story short, in Sphinx, one would cross-reference to other documentation
files (so-called internal linking) either with :doc: or :ref: directives. In
case of kernel docs, there is third and preferred way: simply mentioning the
full docs path. The latter is preferred as it is simpler and also allows
building only portion of docs (with make SPHINXDIRS=<dir>) without triggering
any reference warnings. Hence why I did addressing his comment.
For more information, see Documentation/doc-guide/sphinx.rst.

Thanks.

[1]: https://lore.kernel.org/all/87ecx1x4su.fsf@trenco.lwn.net/

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

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

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Hugo Osvaldo Barrera]

On Thu, 11 Sep 2025, at 13:50, Bagas Sanjaya wrote:
> On Thu, Sep 11, 2025 at 01:22:54PM +0200, Hugo Osvaldo Barrera wrote:
>> On Thu, 11 Sep 2025, at 08:46, Ard Biesheuvel wrote:
>> > On Wed, 10 Sept 2025 at 03:58, Bagas Sanjaya <bagasdotme@gmail.com> 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.
>> >> +
>> 
>> This should be a link rather than a path to the source file.
>
> I think you miss the point of Jon's comment on your original submission [1].
> Long story short, in Sphinx, one would cross-reference to other documentation
> files (so-called internal linking) either with :doc: or :ref: directives. In
> case of kernel docs, there is third and preferred way: simply mentioning the
> full docs path. The latter is preferred as it is simpler and also allows
> building only portion of docs (with make SPHINXDIRS=<dir>) without triggering
> any reference warnings. Hence why I did addressing his comment.
> For more information, see Documentation/doc-guide/sphinx.rst.
>

The RST files are source files to produce documentation in HTML and PDF. If you
write the path to another source file, the resulting HTML files don't have
any link and the reference is completely lost.

Given the path Documentation/admin-guide/efi-stub.rst, if I'm looking at
https://www.kernel.org/doc/html/latest/arch/x86/boot.html, I'd have on idea
where this path is pointing me to.

WRT Jon's comment on the original submission, I do agree that the label
is unnecessary, since we can link to the page directly without a label at
the top.

> Thanks.
>
> [1]: https://lore.kernel.org/all/87ecx1x4su.fsf@trenco.lwn.net/
>
> -- 
> An old man doll... just what I always wanted! - Clara
>
> Attachments:
> * signature.asc

-- 
Hugo

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Ard Biesheuvel]

On Thu, 11 Sept 2025 at 13:23, Hugo Osvaldo Barrera <hugo@whynothugo.nl> wrote:
>
>
>
> On Thu, 11 Sep 2025, at 08:46, Ard Biesheuvel wrote:
> > On Wed, 10 Sept 2025 at 03:58, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> >>
> >> From: Hugo Osvaldo Barrera <hugo@whynothugo.nl>
> >>
...
> >> +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?
>
> It's a UEFI stub loader which can load the Linux kernel and provide it with an
> initramfs using the above described protocol.
>
> The original version of this patch was based on my notes researching _how_
> to implement this stub loader. The implementation is quite minimal, so I think
> it serves as a useful reference example.
>

I think one example reference is sufficient, and I think piggybacking
a plug of your own project onto a documentation refactoring patch is
slightly dodgy, to be completely honest.

Where is candyboot used, and what does it add to the existing u-boot
reference, which is the most widely used EFI implementation after EDK2
for non-x86 systems? If anything, we should be referring to the OVMF
implementation here.

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Hugo Osvaldo Barrera]

On Thu, 11 Sep 2025, at 14:49, Ard Biesheuvel wrote:
> On Thu, 11 Sept 2025 at 13:23, Hugo Osvaldo Barrera <hugo@whynothugo.nl> wrote:
>>
>>
>>
>> On Thu, 11 Sep 2025, at 08:46, Ard Biesheuvel wrote:
>> > On Wed, 10 Sept 2025 at 03:58, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>> >>
>> >> From: Hugo Osvaldo Barrera <hugo@whynothugo.nl>
>> >>
> ...
>> >> +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?
>>
>> It's a UEFI stub loader which can load the Linux kernel and provide it with an
>> initramfs using the above described protocol.
>>
>> The original version of this patch was based on my notes researching _how_
>> to implement this stub loader. The implementation is quite minimal, so I think
>> it serves as a useful reference example.
>>
>
> I think one example reference is sufficient, and I think piggybacking
> a plug of your own project onto a documentation refactoring patch is
> slightly dodgy, to be completely honest.

I don't know what kind of reaction you're expecting. The documentation
improvements were a side-effect of developing candyboot. You're free to
exclude the mention if you feel it is inadequate, but I don't appreciate
the personal attack.

> Where is candyboot used, and what does it add to the existing u-boot
> reference, which is the most widely used EFI implementation after EDK2
> for non-x86 systems?

candyboot can be used to produce a single bootable UEFI binary bundling
the kernel, cmdline and initrd. This binary can be signed to boot using
SecureBoot on regular consumer hardware. It is typically useful is
situations where u-boot isn't supported, and useless in most situations
where u-boot is usable.

The use-case is somewhat tangential here; the reference is merely as a
minimal (single file) reference implementation of the feature being
described here.

> If anything, we should be referring to the OVMF implementation here.

Agreed (I didn't know of its existence), here's a link to it:

https://github.com/tianocore/edk2/blob/502f0dfda4f2c4d1cc091f68b6467b6ef12cab45/OvmfPkg/QemuKernelLoaderFsDxe/QemuKernelLoaderFsDxe.c#L908

-- 
Hugo

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Ard Biesheuvel]

On Thu, 11 Sept 2025 at 16:08, Hugo Osvaldo Barrera <hugo@whynothugo.nl> wrote:
>
>
> On Thu, 11 Sep 2025, at 14:49, Ard Biesheuvel wrote:
> > On Thu, 11 Sept 2025 at 13:23, Hugo Osvaldo Barrera <hugo@whynothugo.nl> wrote:
> >>
> >>
> >>
> >> On Thu, 11 Sep 2025, at 08:46, Ard Biesheuvel wrote:
> >> > On Wed, 10 Sept 2025 at 03:58, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> >> >>
> >> >> From: Hugo Osvaldo Barrera <hugo@whynothugo.nl>
> >> >>
> > ...
> >> >> +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?
> >>
> >> It's a UEFI stub loader which can load the Linux kernel and provide it with an
> >> initramfs using the above described protocol.
> >>
> >> The original version of this patch was based on my notes researching _how_
> >> to implement this stub loader. The implementation is quite minimal, so I think
> >> it serves as a useful reference example.
> >>
> >
> > I think one example reference is sufficient, and I think piggybacking
> > a plug of your own project onto a documentation refactoring patch is
> > slightly dodgy, to be completely honest.
>
> I don't know what kind of reaction you're expecting. The documentation
> improvements were a side-effect of developing candyboot. You're free to
> exclude the mention if you feel it is inadequate, but I don't appreciate
> the personal attack.
>

No personal attack intended. I merely commented on the changes
themselves, not on your person, and the patch incorporates a reference
to your own project without calling that out in the commit log. I'm
sure it is a project you care about, and it looks like nice work (no
irony here) but it also looks like self-promotion being injected into
the Linux Documentation, given that the project in question is one of
many that implement LINUX_EFI_INITRD_MEDIA_GUID, including GRUB and
OVMF/edk2 which are much more widely known and much more relevant to
the audience.

And I am not the Documentation/ maintainer, so it is not up to me to
include or exclude the reference - that is the maintainer's job, which
is why I felt it appropriate to bring this to the attention of the
submitter and of the other people following this thread.

And this is all I am going to say about this.

Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

[Randy Dunlap]

Hi,

On 9/11/25 5:16 AM, Hugo Osvaldo Barrera wrote:
> 
> 
> On Thu, 11 Sep 2025, at 13:50, Bagas Sanjaya wrote:
>> On Thu, Sep 11, 2025 at 01:22:54PM +0200, Hugo Osvaldo Barrera wrote:
>>> On Thu, 11 Sep 2025, at 08:46, Ard Biesheuvel wrote:
>>>> On Wed, 10 Sept 2025 at 03:58, Bagas Sanjaya <bagasdotme@gmail.com> 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.
>>>>> +
>>>
>>> This should be a link rather than a path to the source file.
>>
>> I think you miss the point of Jon's comment on your original submission [1].
>> Long story short, in Sphinx, one would cross-reference to other documentation
>> files (so-called internal linking) either with :doc: or :ref: directives. In
>> case of kernel docs, there is third and preferred way: simply mentioning the
>> full docs path. The latter is preferred as it is simpler and also allows
>> building only portion of docs (with make SPHINXDIRS=<dir>) without triggering
>> any reference warnings. Hence why I did addressing his comment.
>> For more information, see Documentation/doc-guide/sphinx.rst.
>>
> 
> The RST files are source files to produce documentation in HTML and PDF. If you
> write the path to another source file, the resulting HTML files don't have
> any link and the reference is completely lost.
> 
> Given the path Documentation/admin-guide/efi-stub.rst, if I'm looking at
> https://www.kernel.org/doc/html/latest/arch/x86/boot.html, I'd have on idea
> where this path is pointing me to.

I applied the original patch from Bagas. I'm looking at
arch/x86/boot.html. It shows me:

1.16. PE/COFF entry point

  When compiled with CONFIG_EFI_STUB=y, the kernel can be executed as a regular PE/COFF binary. See The EFI Boot Stub for implementation details.

where "The EFI Boot Stub" is (in my browser) in blue and underlined and is a link to
admin-guide/efi-stub.html


Is this what you are saying will not happen or am I
completely confused?  Kernel documentation automarkup handles
Documentation/.../*.rst file links automatically.



> WRT Jon's comment on the original submission, I do agree that the label
> is unnecessary, since we can link to the page directly without a label at
> the top.

Thanks.
-- 
~Randy