Re: [PATCH 1/1] docs: admin-guide: fdt and initrd load in EFI stub

[Heinrich Schuchardt <xypron.glpk@gmx.de>]

On 10/2/20 7:21 PM, Ard Biesheuvel wrote:
> Hi Heinrich,
>
> Thanks for documenting this.
>
>
> On Fri, 2 Oct 2020 at 19:11, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>>
>> Describe how a device tree and an initial RAM disk can be passed to the EFI
>> Boot Stub.
>>
>> Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
>> ---
>>  Documentation/admin-guide/efi-stub.rst | 35 ++++++++++++++++++++++++++
>>  1 file changed, 35 insertions(+)
>>
>> diff --git a/Documentation/admin-guide/efi-stub.rst b/Documentation/admin-guide/efi-stub.rst
>> index 833edb0d0bc4..86f50a33884c 100644
>> --- a/Documentation/admin-guide/efi-stub.rst
>> +++ b/Documentation/admin-guide/efi-stub.rst
>> @@ -38,6 +38,34 @@ arch/arm/boot/zImage should be copied to the system partition, and it
>>  may not need to be renamed. Similarly for arm64, arch/arm64/boot/Image
>>  should be copied but not necessarily renamed.
>>
>> +Passing an initial RAM disk to the EFI Boot Stub
>> +------------------------------------------------
>> +
>> +The following means sorted by decreasing priority can be used to provide an
>> +initial RAM disk to the EFI Boot Stub:
>> +
>> +* The firmware may provide a UEFI Load File 2 Protocol. The stub will try to
>> +  load the RAM disk by calling the LoadFile() service of the protocol using
>> +  a vendor device path with the vendor GUID
>> +  5568e427-0x68fc-4f3d-ac74-ca555231cc68.
>> +* Next the EFI stub will try to load the file indicated by the "initrd=" command
>> +  line parameter.
>> +* The prior boot stage may pass the location of the initial RAM disk via the
>> +  "linux,initrd-start" and "linux,initrd-end" properties of the "/chosen" node
>> +  of the device-tree.
>> +
>
> On x86, the boot_params struct is used to pass the address and size of
> the initrd in memory. Maybe include that for completeness?

On x86 boot_params is set in function efi_pe_entry() after loading the
file indicated by the initrd= command line.

boot_params is not accessible by a caller of the EFI stub but is a
structure used at the interface between EFI stub and main kernel. This
interface is not in the scope of the admin-guide.

The main Linux entry point is already described in
Documentation/x86/boot.rst and ./Documentation/x86/zero-page.rst.

We can add Sphinx style documentation for function efi_pe_entry()
mentioning that it fills in boot_params.
drivers/firmware/efi/libstub/x86-stub.c then can be added to
Documentation/driver-api/firmware/efi/index.rst in an x86 chapter. But
these will be separate patches.

Best regards

Heinrich

>
>> +The first two items are inhibited by the "noinitrd" command line parameter.
>> +
>
> Interesting. Are you saying noinitrd is ignored by the kernel itself?
>
> Looking at the code, it might only work for preventing the load of old
> style initrd ramdisks, whereas initramfs images are handled
> separately.
>
> This is something that we should probably fix one way or the other.
>
>
>> +Passing a device-tree to the EFI Boot Stub
>> +------------------------------------------
>> +
>> +A device-tree can be passed to the EFI Boot Stub in decreasing priority using
>> +
>> +* command line option dtb=
>> +* a UEFI configuration table with GUID b1b621d5-f19c-41a5-830b-d9152c69aae0.
>> +
>> +The command line option is only available if CONFIG_EFI_ARMSTUB_DTB_LOADER=y
>> +and secure boot is disabled.
>>
>>  Passing kernel parameters from the EFI shell
>>  --------------------------------------------
>> @@ -46,6 +74,10 @@ Arguments to the kernel can be passed after bzImage.efi, e.g.::
>>
>>         fs0:> bzImage.efi console=ttyS0 root=/dev/sda4
>>
>> +The "noinitrd" option
>> +---------------------
>> +
>> +The "noinitrd" option stops the EFI stub from loading an initial RAM disk.
>>
>>  The "initrd=" option
>>  --------------------
>> @@ -98,3 +130,6 @@ CONFIGURATION TABLE.
>>
>>  "dtb=" is processed in the same manner as the "initrd=" option that is
>>  described above.
>> +
>> +This option is only available if CONFIG_EFI_ARMSTUB_DTB_LOADER=y and secure
>> +boot is disabled.
>> --
>> 2.28.0
>>