Message-Id: <c30fb598-2878-4bdd-ab84-4f4d07d0db5d@app.fastmail.com>
Date: Thu, 11 Sep 2025 13:22:54 +0200
From: "Hugo Osvaldo Barrera" <hugo@...nothugo.nl>
To: "Ard Biesheuvel" <ardb@...nel.org>, "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>
Subject: Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID



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

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

Powered by blists - more mailing lists