Documentation/admin-guide/efi-stub.rst | 3 ++ Documentation/arch/x86/boot.rst | 38 ++++++++++++++++++++------ 2 files changed, 33 insertions(+), 8 deletions(-)
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>
---
No changes since v2 [1].
EFI/x86 maintainers: Would you like to apply this patch on tip/efi tree
or let Jon handle it through docs-next instead?
[1]: https://lore.kernel.org/linux-doc/20250916073244.590483-1-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: 3a8660878839faadb4f1a6dd72c3179c1df56787
--
An old man doll... just what I always wanted! - ClaraBagas Sanjaya <bagasdotme@gmail.com> writes: > 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> > --- > No changes since v2 [1]. Applied, thanks. jon
On Mon, 13 Oct 2025 at 10:57, 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 and refer to > OVMF/edk2 implementation] > Co-developed-by: Bagas Sanjaya <bagasdotme@gmail.com> > Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> > --- > No changes since v2 [1]. > > EFI/x86 maintainers: Would you like to apply this patch on tip/efi tree > or let Jon handle it through docs-next instead? > Please take this via the documentation tree - thanks. > [1]: https://lore.kernel.org/linux-doc/20250916073244.590483-1-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: 3a8660878839faadb4f1a6dd72c3179c1df56787 > -- > An old man doll... just what I always wanted! - Clara > >
© 2016 - 2025 Red Hat, Inc.