0001 =================
0002 The EFI Boot Stub
0003 =================
0004
0005 On the x86 and ARM platforms, a kernel zImage/bzImage can masquerade
0006 as a PE/COFF image, thereby convincing EFI firmware loaders to load
0007 it as an EFI executable. The code that modifies the bzImage header,
0008 along with the EFI-specific entry point that the firmware loader
0009 jumps to are collectively known as the "EFI boot stub", and live in
0010 arch/x86/boot/header.S and drivers/firmware/efi/libstub/x86-stub.c,
0011 respectively. For ARM the EFI stub is implemented in
0012 arch/arm/boot/compressed/efi-header.S and
0013 drivers/firmware/efi/libstub/arm32-stub.c. EFI stub code that is shared
0014 between architectures is in drivers/firmware/efi/libstub.
0015
0016 For arm64, there is no compressed kernel support, so the Image itself
0017 masquerades as a PE/COFF image and the EFI stub is linked into the
0018 kernel. The arm64 EFI stub lives in arch/arm64/kernel/efi-entry.S
0019 and drivers/firmware/efi/libstub/arm64-stub.c.
0020
0021 By using the EFI boot stub it's possible to boot a Linux kernel
0022 without the use of a conventional EFI boot loader, such as grub or
0023 elilo. Since the EFI boot stub performs the jobs of a boot loader, in
0024 a certain sense it *IS* the boot loader.
0025
0026 The EFI boot stub is enabled with the CONFIG_EFI_STUB kernel option.
0027
0028
0029 How to install bzImage.efi
0030 --------------------------
0031
0032 The bzImage located in arch/x86/boot/bzImage must be copied to the EFI
0033 System Partition (ESP) and renamed with the extension ".efi". Without
0034 the extension the EFI firmware loader will refuse to execute it. It's
0035 not possible to execute bzImage.efi from the usual Linux file systems
0036 because EFI firmware doesn't have support for them. For ARM the
0037 arch/arm/boot/zImage should be copied to the system partition, and it
0038 may not need to be renamed. Similarly for arm64, arch/arm64/boot/Image
0039 should be copied but not necessarily renamed.
0040
0041
0042 Passing kernel parameters from the EFI shell
0043 --------------------------------------------
0044
0045 Arguments to the kernel can be passed after bzImage.efi, e.g.::
0046
0047 fs0:> bzImage.efi console=ttyS0 root=/dev/sda4
0048
0049
0050 The "initrd=" option
0051 --------------------
0052
0053 Like most boot loaders, the EFI stub allows the user to specify
0054 multiple initrd files using the "initrd=" option. This is the only EFI
0055 stub-specific command line parameter, everything else is passed to the
0056 kernel when it boots.
0057
0058 The path to the initrd file must be an absolute path from the
0059 beginning of the ESP, relative path names do not work. Also, the path
0060 is an EFI-style path and directory elements must be separated with
0061 backslashes (\). For example, given the following directory layout::
0062
0063 fs0:>
0064 Kernels\
0065 bzImage.efi
0066 initrd-large.img
0067
0068 Ramdisks\
0069 initrd-small.img
0070 initrd-medium.img
0071
0072 to boot with the initrd-large.img file if the current working
0073 directory is fs0:\Kernels, the following command must be used::
0074
0075 fs0:\Kernels> bzImage.efi initrd=\Kernels\initrd-large.img
0076
0077 Notice how bzImage.efi can be specified with a relative path. That's
0078 because the image we're executing is interpreted by the EFI shell,
0079 which understands relative paths, whereas the rest of the command line
0080 is passed to bzImage.efi.
0081
0082
0083 The "dtb=" option
0084 -----------------
0085
0086 For the ARM and arm64 architectures, a device tree must be provided to
0087 the kernel. Normally firmware shall supply the device tree via the
0088 EFI CONFIGURATION TABLE. However, the "dtb=" command line option can
0089 be used to override the firmware supplied device tree, or to supply
0090 one when firmware is unable to.
0091
0092 Please note: Firmware adds runtime configuration information to the
0093 device tree before booting the kernel. If dtb= is used to override
0094 the device tree, then any runtime data provided by firmware will be
0095 lost. The dtb= option should only be used either as a debug tool, or
0096 as a last resort when a device tree is not provided in the EFI
0097 CONFIGURATION TABLE.
0098
0099 "dtb=" is processed in the same manner as the "initrd=" option that is
0100 described above.
