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

[Atish Patra]

On Fri, Oct 2, 2020 at 1:04 PM Heinrich Schuchardt <xypron.glpk@xxxxxx> wrote:
>
> On 10/2/20 9:21 PM, Ard Biesheuvel wrote:
> > On Fri, 2 Oct 2020 at 21:14, Heinrich Schuchardt <xypron.glpk@xxxxxx> wrote:
> >>
> >> 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@xxxxxx> 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@xxxxxx>
> >>>> ---
> >>>>  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.

This is only applicable if EFI_GENERIC_STUB_INITRD_CMDLINE_LOADER is enabled.
Should we specify that as well?

> >>>> +* 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.
> >>
> >
> >  I don't see the difference between dt for arm and boot_params for
> > x86. Both can be provided by the bootloader, and will be created from
> > scratch by the efi stub if not. They both carry the command line and
> > address and size of the initrd, and the efi stub will load  the initrd
> > and update this Information, or pass it on unmodified if the
> > bootloader already loaded the initrd into memory.
>
> "The Linux kernel user’s and administrator’s guide" is not targeted for
> developers.
>
> All I have described in this patch are interfaces between Linux and the
> prior boot stage when using the EFI stub. It does not cover how the EFI
> stub communicates with main Linux.
>
> I may already have put too much technical detail here considering the
> audience.
>
> To my knowledge boot_params is not an inbound interface parameter of the
> EFI stub.
>
> Is it of interests for administrators and users to know that the EFI
> stub calls the legacy entry point of Linux? If yes, we should point to
> the documentation of the legacy entry point for all architectures:
>
> https://www.kernel.org/doc/html/latest/x86/boot.html#bit-boot-protocol
> https://www.kernel.org/doc/html/latest/x86/boot.html#id1
> https://www.kernel.org/doc/html/latest/arm/booting.html
> https://www.kernel.org/doc/html/latest/arm64/booting.html
>
> I could not find an appropriate chapter for RISC-V in
> https://www.kernel.org/doc/html/latest/riscv/index.html.
>

Unfortunately, there is no booting document for RISC-V yet. It has
been discussed many times but no patch yet.
If you want to take a stab at it, that would be great.


> As the interface between the EFI stub and main Linux is not exposed to
> the outside world and may rightfully change without notice I suggest to
> not mention it in the admin guide.
>
> Best regards
>
> Heinrich
>
> >
> >
> >
> >> 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
> >>>>
> >>
>


--
Regards,
Atish