Documentation: efi/x86: clarify EFI handover protocol and its requirements
Subsystems (2)
Ard Biesheuvel
maintainerPATCH 1/1 Documentation: efi/x86: clarify EFI handover protocol and its requirements
The EFI handover protocol was introduced on x86 to permit the boot loader to pass a populated boot_params structure as an additional function argument to the entry point. This allows the bootloader to pass the base and size of a initrd image, which is more flexible than relying on the EFI stub's file I/O routines, which can only access the file system from which the kernel image itself was loaded from firmware.
This approach requires a fair amount of internal knowledge regarding the layout of the boot_params structure on the part of the boot loader, as well as knowledge regarding the allowed placement of the initrd in memory, and so it has been deprecated in favour of a new initrd loading method that is based on existing UEFI protocols and best practices.
So update the x86 boot protocol documentation to clarify that the EFI handover protocol has been deprecated, and while at it, add a note that invoking the EFI handover protocol still requires the PE/COFF image to be loader properly (as opposed to simply being copied into memory). Also, drop the code32_start header field from the list of values that need to be provided, as this is no longer required.
--- Documentation/x86/boot.rst | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-)
Documentation/x86/boot.rst +14 -3
@@ -1399,14 +1399,19 @@ must have read/write permission; CS must be __BOOT_CS and DS, ES, SS must be __BOOT_DS; interrupt must be disabled; %rsi must hold the base address of the struct boot_params. -EFI Handover Protocol -===================== +EFI Handover Protocol (deprecated) +================================== This protocol allows boot loaders to defer initialisation to the EFI boot stub. The boot loader is required to load the kernel/initrd(s) from the boot media and jump to the EFI handover protocol entry point which is hdr->handover_offset bytes from the beginning of startup_{32,64}. +The boot loader MUST respect the kernel's PE/COFF metadata when it comes +to section alignment, the memory footprint of the executable image beyond +the size of the file itself, and any other aspect of the PE/COFF header +that may affect correct operation of the image as a PE/COFF binary in the +execution context provided by the EFI firmware. The function prototype for the handover entry point looks like this::
@@ -1419,9 +1424,15 @@ UEFI specification. 'bp' is the boot loader-allocated boot params. The boot loader *must* fill out the following fields in bp:: - - hdr.code32_start - hdr.cmd_line_ptr - hdr.ramdisk_image (if applicable) - hdr.ramdisk_size (if applicable) 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, 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.
Signature · 1 line
2.17.1
Quoted 14 lines · Ard Biesheuvel
The EFI handover protocol was introduced on x86 to permit the boot loader to pass a populated
boot_paramsstructure as an additional function argument to the entry point. This allows the bootloader to pass the base and size of a initrd image, which is more flexible than relying on the EFI stub's file I/O routines, which can only access the file system from which the kernel image itself was loaded from firmware.This approach requires a fair amount of internal knowledge regarding the layout of the
boot_paramsstructure on the part of the boot loader, as well as knowledge regarding the allowed placement of the initrd in memory, and so it has been deprecated in favour of a new initrd loading method that is based on existing UEFI protocols and best practices.
Quoted 4 lines
So update the x86 boot protocol documentation to clarify that the EFI handover protocol has been deprecated, and while at it, add a note that invoking the EFI handover protocol still requires the PE/COFF image to be loader properly (as opposed to simply being copied into memory). Also,
^^ typo
Quoted 54 lines
drop the
code32_startheader field from the list of values that need to be provided, as this is no longer required.Signed-off-by Ard Biesheuvel <[email protected]>--- Documentation/x86/boot.rst | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-)Documentation/x86/boot.rst +14
-3@@ -1399,14 +1399,19 @@ must have read/write permission; CS must be __BOOT_CS and DS, ES, SS must be __BOOT_DS; interrupt must be disabled; %rsi must hold the base address of the struct boot_params. -EFI Handover Protocol -===================== +EFI Handover Protocol (deprecated) +================================== This protocol allows boot loaders to defer initialisation to the EFI boot stub. The boot loader is required to load the kernel/initrd(s) from the boot media and jump to the EFI handover protocol entry point which is hdr->handover_offset bytes from the beginning of startup_{32,64}. +The boot loader MUST respect the kernel's PE/COFF metadata when it comes +to section alignment, the memory footprint of the executable image beyond +the size of the file itself, and any other aspect of the PE/COFF header +that may affect correct operation of the image as a PE/COFF binary in the +execution context provided by the EFI firmware. The function prototype for the handover entry point looks like this::@@ -1419,9 +1424,15 @@ UEFI specification. 'bp' is the boot loader-allocated boot params. The boot loader *must* fill out the following fields in bp:: - - hdr.code32_start - hdr.cmd_line_ptr - hdr.ramdisk_image (if applicable) - hdr.ramdisk_size (if applicable) 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, 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.Signature · 1 line
2.17.1
Quoted 34 lines · Ard Biesheuvel
The EFI handover protocol was introduced on x86 to permit the boot loader to pass a populated
boot_paramsstructure as an additional function argument to the entry point. This allows the bootloader to pass the base and size of a initrd image, which is more flexible than relying on the EFI stub's file I/O routines, which can only access the file system from which the kernel image itself was loaded from firmware.This approach requires a fair amount of internal knowledge regarding the layout of the
boot_paramsstructure on the part of the boot loader, as well as knowledge regarding the allowed placement of the initrd in memory, and so it has been deprecated in favour of a new initrd loading method that is based on existing UEFI protocols and best practices.So update the x86 boot protocol documentation to clarify that the EFI handover protocol has been deprecated, and while at it, add a note that invoking the EFI handover protocol still requires the PE/COFF image to be loader properly (as opposed to simply being copied into memory). Also, drop the
code32_startheader field from the list of values that need to be provided, as this is no longer required.Signed-off-by Ard Biesheuvel <[email protected]>--- Documentation/x86/boot.rst | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-)Documentation/x86/boot.rst +0
-0@@ -1399,14 +1399,19 @@ must have read/write permission; CS must be __BOOT_CS and DS, ES, SS must be __BOOT_DS; interrupt must be disabled; %rsi must hold the base address of the struct boot_params.
Documentation/x86/boot.rst must have read/write permission; CS must be __BOOT_CS and DS, ES, SS · line 1409
Quoted 10 lines
Documentation/x86/boot.rst +2
-2-EFI Handover Protocol -===================== +EFI Handover Protocol (deprecated) +================================== This protocol allows boot loaders to defer initialisation to the EFI boot stub. The boot loader is required to load the kernel/initrd(s) from the boot media and jump to the EFI handover protocol entry point which is hdr->handover_offset bytes from the beginning of startup_{32,64}.
Perhaps a newline here.
Quoted 15 lines
Documentation/x86/boot.rst +5
-1+The boot loader MUST respect the kernel's PE/COFF metadata when it comes +to section alignment, the memory footprint of the executable image beyond +the size of the file itself, and any other aspect of the PE/COFF header +that may affect correct operation of the image as a PE/COFF binary in the +execution context provided by the EFI firmware. The function prototype for the handover entry point looks like this::@@ -1419,9 +1424,15 @@ UEFI specification. 'bp' is the boot loader-allocated boot params. The boot loader *must* fill out the following fields in bp:: - - hdr.code32_start - hdr.cmd_line_ptr - hdr.ramdisk_image (if applicable)
Documentation/x86/boot.rst UEFI specification. 'bp' is the boot loader-allocated boot params. · line 1438
Quoted 10 lines
Documentation/x86/boot.rst +7
-0- hdr.ramdisk_size (if applicable) 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, 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.
Yap, nice.
I wonder if it might be even better if that would point people to efi_load_initrd_dev_path() or better yet to an actual example of how to do it.
Alternatively, the comment over initrd_dev_path almost spells it out what to do so I guess you could repeat that comment here so that it is perfectly clear, as in "We would like you to provide us an initrd in this exact manner." :-)
In any case, thanks!
Signature · 4 lines
Regards/Gruss,
Boris.
https://people.kernel.org/tglx/notes-about-netiquetteArd Biesheuvel
maintainerQuoted 41 lines · Borislav Petkov
Quoted 39 lines · Ard Biesheuvel
The EFI handover protocol was introduced on x86 to permit the boot loader to pass a populated
boot_paramsstructure as an additional function argument to the entry point. This allows the bootloader to pass the base and size of a initrd image, which is more flexible than relying on the EFI stub's file I/O routines, which can only access the file system from which the kernel image itself was loaded from firmware.This approach requires a fair amount of internal knowledge regarding the layout of the
boot_paramsstructure on the part of the boot loader, as well as knowledge regarding the allowed placement of the initrd in memory, and so it has been deprecated in favour of a new initrd loading method that is based on existing UEFI protocols and best practices.So update the x86 boot protocol documentation to clarify that the EFI handover protocol has been deprecated, and while at it, add a note that invoking the EFI handover protocol still requires the PE/COFF image to be loader properly (as opposed to simply being copied into memory). Also, drop the
code32_startheader field from the list of values that need to be provided, as this is no longer required.Signed-off-by Ard Biesheuvel <[email protected]>--- Documentation/x86/boot.rst | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-)Documentation/x86/boot.rst +2
-2@@ -1399,14 +1399,19 @@ must have read/write permission; CS must be __BOOT_CS and DS, ES, SS must be __BOOT_DS; interrupt must be disabled; %rsi must hold the base address of the struct boot_params. -EFI Handover Protocol -===================== +EFI Handover Protocol (deprecated) +==================================
Quoted 8 lines
Documentation/x86/boot.rst must have read/write permission; CS must be __BOOT_CS and DS, ES, SS · line 1409
Quoted 5 lines
Documentation/x86/boot.rst +0
-0This protocol allows boot loaders to defer initialisation to the EFI boot stub. The boot loader is required to load the kernel/initrd(s) from the boot media and jump to the EFI handover protocol entry point which is hdr->handover_offset bytes from the beginning of startup_{32,64}.Perhaps a newline here.
OK
Quoted 28 lines
Quoted 15 lines
Documentation/x86/boot.rst +5
-1+The boot loader MUST respect the kernel's PE/COFF metadata when it comes +to section alignment, the memory footprint of the executable image beyond +the size of the file itself, and any other aspect of the PE/COFF header +that may affect correct operation of the image as a PE/COFF binary in the +execution context provided by the EFI firmware. The function prototype for the handover entry point looks like this::@@ -1419,9 +1424,15 @@ UEFI specification. 'bp' is the boot loader-allocated boot params. The boot loader *must* fill out the following fields in bp:: - - hdr.code32_start - hdr.cmd_line_ptr - hdr.ramdisk_image (if applicable)Documentation/x86/boot.rst UEFI specification. 'bp' is the boot loader-allocated boot params. · line 1438
Quoted 10 lines
Documentation/x86/boot.rst +7
-0- hdr.ramdisk_size (if applicable) 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, 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.Yap, nice.
Quoted 4 lines
I wonder if it might be even better if that would point people to
efi_load_initrd_dev_path()or better yet to an actual example of how to do it.
I'll add a reference to [0] here, which is the u-boot implementation.
Quoted 9 lines
Alternatively, the comment over
initrd_dev_pathalmost spells it out what to do so I guess you could repeat that comment here so that it is perfectly clear, as in "We would like you to provide us an initrd in this exact manner." :-)In any case, thanks!
Reviewed-by Borislav Petkov <[email protected]>
Thanks
[0] https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0