Document that arguments following an EFI application's path on the shell command line become its load options, that bootm populates the load options from global.efi.bootargs.* and that the Linux bootargs follow for EFI-stubbed kernels, both for barebox as EFI payload and as EFI loader.
Assisted-by: Claude:fable-5 Signed-off-by: Ahmad Fatoum <[email protected]> --- Documentation/boards/efi.rst | 53 ++++++++++++++++++++++++++-- Documentation/user/booting-linux.rst | 6 +++- 2 files changed, 56 insertions(+), 3 deletions(-) diff --git a/Documentation/boards/efi.rst b/Documentation/boards/efi.rst index da50fc8ff6cd..05f040660809 100644 --- a/Documentation/boards/efi.rst +++ b/Documentation/boards/efi.rst @@ -110,8 +110,56 @@ means passing control to the calling instance. Note that currently the :ref:`com command will pass the control to the calling instance rather than resetting the CPU. This may change in the future. +Arguments following the path on the command line are passed to the +application as its load options, so an EFI shell can for example be +started with: + +.. code-block:: sh + + barebox:/ /boot/shell.efi -nostartup + Although the Linux Kernel can be directly executed one should use the :ref:`command_bootm` -command. Only the bootm command passes the Kernel commandline to the Kernel. +command. Only the bootm command passes the Kernel commandline to the Kernel +and provides it with an initrd and a device tree. + +.. _efi_load_options: + +Load options +^^^^^^^^^^^^ + +When booting an EFI application via :ref:`command_bootm`, barebox populates +its load options from the :ref:`global device<global_device>` variables +beginning with ``global.efi.bootargs.``. Like the Linux bootargs, these are +concatenated in lexicographical order of their names. For EFI-stubbed Linux +kernels, the ``global.linux.bootargs.``-prefixed +:ref:`kernel arguments <booting_linux>` are appended to the load options, +so that the EFI stub sees both as the kernel command line: + +.. code-block:: sh + + global efi.bootargs.base="efi=debug" + global linux.bootargs.base="console=ttyS0,115200" + + bootm /boot/vmlinuz.efi + + ... + + Kernel command line: efi=debug console=ttyS0,115200 + +This works both when barebox runs as EFI payload and when it acts as +EFI loader for the application. The load options are not used when booting +x86 kernels via the legacy handover protocol (``global.linux.efi.handover``), +as the EFI stub, which would interpret them, is bypassed in that case. + +Like :ref:`boot entries <boot_entries>` do for the Linux +bootargs, boot entries should add load options to variables with ``.dyn`` +in their name, e.g. ``global.efi.bootargs.dyn.initrd``. These are cleared +after each boot entry, so that load options do not leak into subsequently +booted entries. + +.. note:: Unified kernel images (UKIs) are not detected as Linux kernels, + but as regular EFI applications. Only ``global.efi.bootargs.*`` is + passed to them as load options; the Linux bootargs are not appended. Drivers ^^^^^^^ @@ -281,7 +329,8 @@ it's readable at ``/sys/firmware/efi/efivars/barebox-dtb-5b91f69c-8b88-4a2b-9269-5f1d802b5175``, where the blob is prefixed by a four byte EFI variable attribute word. -This is not done when barebox acts as EFI loader for the application. +Unlike the `Load options`_, this is not done when barebox acts as EFI +loader for the application. EFI variables ------------- diff --git a/Documentation/user/booting-linux.rst b/Documentation/user/booting-linux.rst index fa5a355183eb..56a94b890887 100644 --- a/Documentation/user/booting-linux.rst +++ b/Documentation/user/booting-linux.rst @@ -101,6 +101,9 @@ to the bootargs. Variables without a value are skipped: Kernel command line: ignore_loglevel console=ttyO0,115200 earlyprintk +When booting an EFI-stubbed kernel as EFI application, the +:ref:`EFI load options <efi_load_options>` precede the Linux bootargs. + .. _bootargs_concat_order: Concatenation order @@ -167,7 +170,8 @@ This takes the kernel from ``/mnt/mmc1/zImage`` (which could be an boot entries should always add Kernel command line parameters to variables with ``.dyn`` in it. These will be cleared before booting different boot entries. This is done so that following boot entries do not leak command line -parameters from the previous boot entries. +parameters from the previous boot entries. The same applies to the +:ref:`EFI load options <efi_load_options>` in ``global.efi.bootargs.dyn.*``. This entry can be booted with ``boot mmc``. It can also be made the default by setting the :ref:`global.boot.default <magicvar_global_boot_default>` variable -- 2.47.3
