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
