EFI stub

Resources

Official documentation

Package information

Wikipedia

This article has some todo items:

• CONFIG_PM_STD_PARTITION for hibernation

The (U)EFI firmware present in many computers functions as a boot manager, allowing systems to boot by the use of a compatible EFI bootloader. By making the Linux kernel itself such a bootloader, called an EFI stub. This configuration boots without the need for secondary bootloader. This article provides instructions on configuring and installing kernels in the EFI System Partition (ESP) of a computer running in EFI mode.

Kernel configuration

In order to boot directly from UEFI, the kernel needs to know where to find the root (/) partition of the system to be booted.

The following kernel configuration options must be enabled:

KERNEL Enable EFI stub support

Processor type and features  --->
    [*] EFI runtime service support 
    [ ]     EFI handover protocol (DEPRECATED) (OPTIONAL)
    [*]     EFI stub support
    [ ]     EFI mixed-mode support (OPTIONAL)
    [*] Built-in kernel command line
    (root=UUID=d1e0c1e0-3a40-42c5-8931-cfa2c7deae32)

Important
Setting the root location using a UUID or PARTUUID is generally preferable and less error prone. This information can be obtained with blkid:

root #blkid | grep sda2

/dev/sda2: UUID="d1e0c1e0-3a40-42c5-8931-cfa2c7deae32" TYPE="ext4" PARTUUID="adf55784-15d9-4ca3-bb3f-56de0b35d88d"

The partition's PARTUUID is distinct from the filesystem's UUID. The UUID refers to the filesystem partition, while the PARTUUID refers to the disk partition.

Note
EFI mixed-mode support is only required to boot a 64-bit kernel from 32-bit firmware if the CPU supports 64-bit mode and EFI handover is enabled.

.config equivalent with a cmdline with dracut parameters:

CODE .config configuration for an EFI stub with an embedded kernel command line

CONFIG_EFI=y
CONFIG_EFI_STUB=y
CONFIG_CMDLINE_BOOL=y
CONFIG_CMDLINE="root=/dev/mapper/vg0-root rd.luks.key=/crypt_key.luks.gpg:UUID=044502df-6f rd.luks.uuid=5e0022f4-e1c9-4b58-b53e-25d3cd417451 rd.lvm.lv=vg0/root"

Tip
The command line does not need to be built into the kernel, and can be passed by the UEFI or bootloader. efibootmgr) can use the --unicode argument to define a new command line.

Note
For Distribution kernels (except gentoo-kernel-bin) the kernel settings go to savedconfig or /etc/kernel/config.d.

Installation

Kernel Installation

With the kernel configured with EFI Stub support (assuming that ESP is mounted at /boot):

/usr/src/linux-6.3.4-gentoo-r1 #make && make modules_install && make install

This will install the kernel to /boot/vmlinuz-6.3.4-gentoo-r1.

Tip
The EFI stub kernel file can be moved to /{ESP}/EFI/BOOT/BOOTx64.efi, where most UEFIs will check for efi files by default.

Signing for Secure Boot

If Secure Booting this kernel, it must be signed witn sbsign, part of app-crypt/sbsigntools:

root #sbsign --key {db key} --cert {db cert} /boot/vmlinuz-6.3.4-gentoo-r1-initramfs

More information is available at Secure Boot.

EFI Configuration

With the kernel file at /boot/vmlinuz-6.3.4-gentoo-r1-initramfs.signed, a boot entry can be added with:

/boot #efibootmgr --create --disk /dev/sda --label "Signed Gentoo EFI Stub" --loader vmlinuz-6.3.4-gentoo-r1-initramfs.signed

To add an entry with kernel command line arguments:

/boot #efibootmgr --create --disk /dev/sda --label "Signed Gentoo EFI Stub" --loader vmlinuz-6.3.4-gentoo-r1-initramfs.signed --unicode "root=/dev/sdb1"

Microcode loading

An efistub compatible method to load microcode without using an initramfs can be found in the following articles:

• Intel microcode.
• AMD microcode.

Optional: initramfs

See the Generating the Initramfs and Using a Stub Kernel sections of the Early Userspace Mounting article.

Troubleshooting

• Forums topic - BIOS losing the names of the EFI ESPs

• Older kernels compiled with gcc:10 crashed at boot (bug #721734#c4).

• Users of sys-kernel/gentoo-kernel-bin can specify the root partition path with the root= parameter using efibootmgr:

root #efibootmgr -c -L "Gentoo Linux" -l '\EFI\Gentoo\bootx64.efi' -u 'root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

To create a boot entry with efibootmgr and hibernation on swap partition:

root #efibootmgr -c -L "Gentoo Linux" -l '\EFI\Gentoo\bootx64.efi' -u 'root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX resume=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

See also

• UEFI — a firmware standard for boot ROM designed to provide a stable API for interacting with system hardware. On x86 it replaced the legacy BIOS.
• Efibootmgr — a tool for managing UEFI boot entries.
• Architecture specific kernel configuration (AMD64 Handbook)
• REFInd — a boot manager for EFI and UEFI platforms forked from and successor to rEFIt.

External resources

• Linux Kernel Documentation on EFI Stub
• EFI Stub - booting without a bootloader Blog posting which this article is partially based on.
• EFI bootloaders listing alternative ways to boot an (U)EFI system.
• Gentoo Forums: Suspend and Hibernate with UEFI
• http://www.kroah.com/log/blog/2013/09/02/booting-a-self-signed-linux-kernel/