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

Tip
Please follow the steps at EFI System Partition to setup the ESP first.

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

'"`UNIQ--pre-00000004-QINU`"'

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.
• Unified Kernel Image — a single executable which can be booted directly from UEFI firmware, or automatically sourced by boot-loaders with little or no configuration.

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/