superrob1500
/
mirror-linux
mirror of https://github.com/torvalds/linux
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documentation/x86: explain LINUX_EFI_INITRD_MEDIA_GUID 

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.

[Bagas: Don't use :ref: link to EFI stub documentation and refer to
OVMF/edk2 implementation]

Signed-off-by: Hugo Osvaldo Barrera <hugo@whynothugo.nl>
Link: https://lore.kernel.org/r/20250428131206.8656-2-hugo@whynothugo.nl
Co-developed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251013085718.27085-1-bagasdotme@gmail.com>
pull/1354/merge
Hugo Osvaldo Barrera 2025-10-13 15:57:18 +07:00 committed by Jonathan Corbet
parent 3a86608788
commit 8e3b02d260
2 changed files with 33 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
Documentation/admin-guide/efi-stub.rst
View File

@ -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
-----------------

38
Documentation/arch/x86/boot.rst
View File

@ -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