1*4882a593Smuzhiyun================= 2*4882a593SmuzhiyunThe EFI Boot Stub 3*4882a593Smuzhiyun================= 4*4882a593Smuzhiyun 5*4882a593SmuzhiyunOn the x86 and ARM platforms, a kernel zImage/bzImage can masquerade 6*4882a593Smuzhiyunas a PE/COFF image, thereby convincing EFI firmware loaders to load 7*4882a593Smuzhiyunit as an EFI executable. The code that modifies the bzImage header, 8*4882a593Smuzhiyunalong with the EFI-specific entry point that the firmware loader 9*4882a593Smuzhiyunjumps to are collectively known as the "EFI boot stub", and live in 10*4882a593Smuzhiyunarch/x86/boot/header.S and arch/x86/boot/compressed/eboot.c, 11*4882a593Smuzhiyunrespectively. For ARM the EFI stub is implemented in 12*4882a593Smuzhiyunarch/arm/boot/compressed/efi-header.S and 13*4882a593Smuzhiyunarch/arm/boot/compressed/efi-stub.c. EFI stub code that is shared 14*4882a593Smuzhiyunbetween architectures is in drivers/firmware/efi/libstub. 15*4882a593Smuzhiyun 16*4882a593SmuzhiyunFor arm64, there is no compressed kernel support, so the Image itself 17*4882a593Smuzhiyunmasquerades as a PE/COFF image and the EFI stub is linked into the 18*4882a593Smuzhiyunkernel. The arm64 EFI stub lives in arch/arm64/kernel/efi-entry.S 19*4882a593Smuzhiyunand drivers/firmware/efi/libstub/arm64-stub.c. 20*4882a593Smuzhiyun 21*4882a593SmuzhiyunBy using the EFI boot stub it's possible to boot a Linux kernel 22*4882a593Smuzhiyunwithout the use of a conventional EFI boot loader, such as grub or 23*4882a593Smuzhiyunelilo. Since the EFI boot stub performs the jobs of a boot loader, in 24*4882a593Smuzhiyuna certain sense it *IS* the boot loader. 25*4882a593Smuzhiyun 26*4882a593SmuzhiyunThe EFI boot stub is enabled with the CONFIG_EFI_STUB kernel option. 27*4882a593Smuzhiyun 28*4882a593Smuzhiyun 29*4882a593SmuzhiyunHow to install bzImage.efi 30*4882a593Smuzhiyun-------------------------- 31*4882a593Smuzhiyun 32*4882a593SmuzhiyunThe bzImage located in arch/x86/boot/bzImage must be copied to the EFI 33*4882a593SmuzhiyunSystem Partition (ESP) and renamed with the extension ".efi". Without 34*4882a593Smuzhiyunthe extension the EFI firmware loader will refuse to execute it. It's 35*4882a593Smuzhiyunnot possible to execute bzImage.efi from the usual Linux file systems 36*4882a593Smuzhiyunbecause EFI firmware doesn't have support for them. For ARM the 37*4882a593Smuzhiyunarch/arm/boot/zImage should be copied to the system partition, and it 38*4882a593Smuzhiyunmay not need to be renamed. Similarly for arm64, arch/arm64/boot/Image 39*4882a593Smuzhiyunshould be copied but not necessarily renamed. 40*4882a593Smuzhiyun 41*4882a593Smuzhiyun 42*4882a593SmuzhiyunPassing kernel parameters from the EFI shell 43*4882a593Smuzhiyun-------------------------------------------- 44*4882a593Smuzhiyun 45*4882a593SmuzhiyunArguments to the kernel can be passed after bzImage.efi, e.g.:: 46*4882a593Smuzhiyun 47*4882a593Smuzhiyun fs0:> bzImage.efi console=ttyS0 root=/dev/sda4 48*4882a593Smuzhiyun 49*4882a593Smuzhiyun 50*4882a593SmuzhiyunThe "initrd=" option 51*4882a593Smuzhiyun-------------------- 52*4882a593Smuzhiyun 53*4882a593SmuzhiyunLike most boot loaders, the EFI stub allows the user to specify 54*4882a593Smuzhiyunmultiple initrd files using the "initrd=" option. This is the only EFI 55*4882a593Smuzhiyunstub-specific command line parameter, everything else is passed to the 56*4882a593Smuzhiyunkernel when it boots. 57*4882a593Smuzhiyun 58*4882a593SmuzhiyunThe path to the initrd file must be an absolute path from the 59*4882a593Smuzhiyunbeginning of the ESP, relative path names do not work. Also, the path 60*4882a593Smuzhiyunis an EFI-style path and directory elements must be separated with 61*4882a593Smuzhiyunbackslashes (\). For example, given the following directory layout:: 62*4882a593Smuzhiyun 63*4882a593Smuzhiyun fs0:> 64*4882a593Smuzhiyun Kernels\ 65*4882a593Smuzhiyun bzImage.efi 66*4882a593Smuzhiyun initrd-large.img 67*4882a593Smuzhiyun 68*4882a593Smuzhiyun Ramdisks\ 69*4882a593Smuzhiyun initrd-small.img 70*4882a593Smuzhiyun initrd-medium.img 71*4882a593Smuzhiyun 72*4882a593Smuzhiyunto boot with the initrd-large.img file if the current working 73*4882a593Smuzhiyundirectory is fs0:\Kernels, the following command must be used:: 74*4882a593Smuzhiyun 75*4882a593Smuzhiyun fs0:\Kernels> bzImage.efi initrd=\Kernels\initrd-large.img 76*4882a593Smuzhiyun 77*4882a593SmuzhiyunNotice how bzImage.efi can be specified with a relative path. That's 78*4882a593Smuzhiyunbecause the image we're executing is interpreted by the EFI shell, 79*4882a593Smuzhiyunwhich understands relative paths, whereas the rest of the command line 80*4882a593Smuzhiyunis passed to bzImage.efi. 81*4882a593Smuzhiyun 82*4882a593Smuzhiyun 83*4882a593SmuzhiyunThe "dtb=" option 84*4882a593Smuzhiyun----------------- 85*4882a593Smuzhiyun 86*4882a593SmuzhiyunFor the ARM and arm64 architectures, a device tree must be provided to 87*4882a593Smuzhiyunthe kernel. Normally firmware shall supply the device tree via the 88*4882a593SmuzhiyunEFI CONFIGURATION TABLE. However, the "dtb=" command line option can 89*4882a593Smuzhiyunbe used to override the firmware supplied device tree, or to supply 90*4882a593Smuzhiyunone when firmware is unable to. 91*4882a593Smuzhiyun 92*4882a593SmuzhiyunPlease note: Firmware adds runtime configuration information to the 93*4882a593Smuzhiyundevice tree before booting the kernel. If dtb= is used to override 94*4882a593Smuzhiyunthe device tree, then any runtime data provided by firmware will be 95*4882a593Smuzhiyunlost. The dtb= option should only be used either as a debug tool, or 96*4882a593Smuzhiyunas a last resort when a device tree is not provided in the EFI 97*4882a593SmuzhiyunCONFIGURATION TABLE. 98*4882a593Smuzhiyun 99*4882a593Smuzhiyun"dtb=" is processed in the same manner as the "initrd=" option that is 100*4882a593Smuzhiyundescribed above. 101