| Message ID | 20250428131206.8656-2-hugo@whynothugo.nl |
|---|---|
| State | New |
| Headers | show |
| Series | x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID | expand |
Hugo Osvaldo Barrera <hugo@whynothugo.nl> writes: > 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> > --- > Documentation/admin-guide/efi-stub.rst | 5 ++++ > Documentation/arch/x86/boot.rst | 36 +++++++++++++++++++------- > 2 files changed, 32 insertions(+), 9 deletions(-) > > diff --git a/Documentation/admin-guide/efi-stub.rst b/Documentation/admin-guide/efi-stub.rst > index 090f3a185e18..3af702259f1d 100644 > --- a/Documentation/admin-guide/efi-stub.rst > +++ b/Documentation/admin-guide/efi-stub.rst > @@ -1,3 +1,5 @@ > +.. _efi-boot-stub: This label is unneeded... > ================= > The EFI Boot Stub > ================= > @@ -79,6 +81,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 77e6163288db..2fecf89910ec 100644 > --- a/Documentation/arch/x86/boot.rst > +++ b/Documentation/arch/x86/boot.rst > @@ -1431,12 +1431,30 @@ 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. > - > -[0] https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0 > + The EFI Handover Protocol is deprecated in favour of the ordinary PE/COFF > + entry point described below. > + > +.. _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 :ref:`efi-boot-stub` for implementation details. ...just say "see Documentation/admin-guide/efi-stub.rst here. > + > +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 > -- Thanks, jon
diff --git a/Documentation/admin-guide/efi-stub.rst b/Documentation/admin-guide/efi-stub.rst index 090f3a185e18..3af702259f1d 100644 --- a/Documentation/admin-guide/efi-stub.rst +++ b/Documentation/admin-guide/efi-stub.rst @@ -1,3 +1,5 @@ +.. _efi-boot-stub: + ================= The EFI Boot Stub ================= @@ -79,6 +81,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 77e6163288db..2fecf89910ec 100644 --- a/Documentation/arch/x86/boot.rst +++ b/Documentation/arch/x86/boot.rst @@ -1431,12 +1431,30 @@ 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. - -[0] https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0 + The EFI Handover Protocol is deprecated in favour of the ordinary PE/COFF + entry point described below. + +.. _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 :ref:`efi-boot-stub` 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
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> --- Documentation/admin-guide/efi-stub.rst | 5 ++++ Documentation/arch/x86/boot.rst | 36 +++++++++++++++++++------- 2 files changed, 32 insertions(+), 9 deletions(-)