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>

authored by

Hugo Osvaldo Barrera and committed by

Jonathan Corbet 8 months ago 8e3b02d2 3a866087

+33 -8

2 changed files

expand all

Documentation

admin-guide

efi-stub.rst

arch

x86

boot.rst

Documentation/admin-guide/efi-stub.rst

··· 79 79 which understands relative paths, whereas the rest of the command line 80 80 is passed to bzImage.efi. 81 81 82 + .. hint:: 83 + It is also possible to provide an initrd using a Linux-specific UEFI 84 + protocol at boot time. See :ref:`pe-coff-entry-point` for details. 82 85 83 86 The "dtb=" option 84 87 -----------------

+30 -8

Documentation/arch/x86/boot.rst

··· 1431 1431 All other fields should be zero. 1432 1432 1433 1433 .. note:: 1434 - The EFI Handover Protocol is deprecated in favour of the ordinary PE/COFF 1435 - entry point, combined with the LINUX_EFI_INITRD_MEDIA_GUID based initrd 1436 - loading protocol (refer to [0] for an example of the bootloader side of 1437 - this), which removes the need for any knowledge on the part of the EFI 1438 - bootloader regarding the internal representation of boot_params or any 1439 - requirements/limitations regarding the placement of the command line 1440 - and ramdisk in memory, or the placement of the kernel image itself. 1434 + The EFI Handover Protocol is deprecated in favour of the ordinary PE/COFF 1435 + entry point described below. 1441 1436 1442 - [0] https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0 1437 + .. _pe-coff-entry-point: 1438 + 1439 + PE/COFF entry point 1440 + =================== 1441 + 1442 + When compiled with ``CONFIG_EFI_STUB=y``, the kernel can be executed as a 1443 + regular PE/COFF binary. See Documentation/admin-guide/efi-stub.rst for 1444 + implementation details. 1445 + 1446 + The stub loader can request the initrd via a UEFI protocol. For this to work, 1447 + the firmware or bootloader needs to register a handle which carries 1448 + implementations of the ``EFI_LOAD_FILE2`` protocol and the device path 1449 + protocol exposing the ``LINUX_EFI_INITRD_MEDIA_GUID`` vendor media device path. 1450 + In this case, a kernel booting via the EFI stub will invoke 1451 + ``LoadFile2::LoadFile()`` method on the registered protocol to instruct the 1452 + firmware to load the initrd into a memory location chosen by the kernel/EFI 1453 + stub. 1454 + 1455 + This approach removes the need for any knowledge on the part of the EFI 1456 + bootloader regarding the internal representation of boot_params or any 1457 + requirements/limitations regarding the placement of the command line and 1458 + ramdisk in memory, or the placement of the kernel image itself. 1459 + 1460 + For sample implementations, refer to `the original u-boot implementation`_ or 1461 + `the OVMF implementation`_. 1462 + 1463 + .. _the original u-boot implementation: https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0 1464 + .. _the OVMF implementation: https://github.com/tianocore/edk2/blob/1780373897f12c25075f8883e073144506441168/OvmfPkg/LinuxInitrdDynamicShellCommand/LinuxInitrdDynamicShellCommand.c

Configure Feed

Configure Feed