EFI Stub

Resources
This article has some todo items:
  • CONFIG_PM_STD_PARTITION for hibernation

The (U)EFI firmware present in many computers can function as bootloader, allowing systems to boot without needing the addition of a secondary bootloader. This article provides instructions on configuring and installing unsigned kernels in the EFI System Partition (ESP) of a computer running in EFI mode. This requires secure boot to be disabled.

Kernel configuration[edit | edit source]

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

  • EFI runtime service support (CONFIG_EFI),
  • EFI stub support (CONFIG_EFI_STUB)
  • Built-in kernel command line (CONFIG_CMDLINE_BOOL)
  • and add the root partition path (example: /dev/sda2) or its PARTUUID to (CONFIG_CMDLINE).
KERNEL Enable EFI stub support
Processor type and features  --->
    [*] EFI runtime service support 
    [*]   EFI stub support
    [ ]     EFI mixed-mode support
    ...
    ...
    [*] Built-in kernel command line
    (root=/dev/sda2)

Using root=PARTUUID= might be preferable. To find out use blkid:

root #blkid | grep sda2
/dev/sda2: UUID="d1e0c1e0-3a40-42c5-8931-cfa2c7deae32" TYPE="ext4" PARTUUID="adf55784-15d9-4ca3-bb3f-56de0b35d88d"
KERNEL CONFIG_CMDLINE - alternative using PARTUUID (example: adf55784-15d9-4ca3-bb3f-56de0b35d88d)
Processor type and features  --->
    [*] Built-in kernel command line
    (root=PARTUUID=adf55784-15d9-4ca3-bb3f-56de0b35d88d)
Note
The partition's PARTUUID is distinct from the filesystem's UUID.
Note
Alternatively to setting the Built-in kernel command line, the root partition path can be set by the NVRAM (boot entry) (e.g. via efibootmgr) or by an additional EFI boot manager.
Note
For Distribution kernels (except gentoo-kernel-bin) the kernel settings go to savedconfig or /etc/kernel/config.d.

Installation[edit | edit source]

If an ESP does not exist, one needs to be created. See EFI System Partition. Still in the kernel directory, build the kernel and install the modules:

root #cd /usr/src/linux
root #make && make modules_install

Have the ESP (in this example /dev/sda1) mounted at /boot:

root #mount /dev/sda1 /boot

Copy or move the kernel image to the right place adding version number and the .efi suffix:

root #mkdir -p /boot/EFI/Gentoo
root #cp arch/x86/boot/bzImage /boot/EFI/Gentoo/bzImage-4.9.76-r1.efi

In the ESP it should then be listed like:

user $tree -L 3 /boot
 /boot
 └── EFI
     └── Gentoo
         └── bzImage-4.9.76-r1.efi

Alternatively the fallback directory /boot/EFI/Boot could be used additionally to or instead of /boot/EFI/Gentoo. Alternatively vmlinuz can be copied (or moved) instead of the bzImage.

Next, update the NVRAM creating a new boot entry using e.g. efibootmgr.

Microcode loading (Intel)[edit | edit source]

An efistub compatible method to load microcode without using an initramfs can be found in the Intel microcode article.

Optional: Initramfs[edit | edit source]

If for some reason an initramfs is needed, it can either be embedded into the kernel or be used as a separate file.

In case it's desired as a separate file, it should also be copied or moved into the ESP and the NVRAM be updated accordingly.

root #mv /boot/initramfs-4.9.76-r1-gentoo.img /boot/EFI/Gentoo/initramfs.img
root #mount /sys/firmware/efi/efivars -o rw,remount
root #efibootmgr --create --part 1 --disk /dev/sda --label "Gentoo" --loader '\efi\gentoo\bzImage-4.9.76-r1.efi' -u 'initrd=\efi\gentoo\initramfs.img'
root #mount /sys/firmware/efi/efivars -o ro,remount

Some UEFI implementations however seem to not support passing parameters from the NVRAM to the EFI stub kernel.

For embedding the initramfs directly into the kernel image, the Initramfs source file(s) (CONFIG_INITRAMFS_SOURCE) must be coded in the kernel (directly under the Initial RAM filesystem and RAM disk (initramfs/initrd) support (CONFIG_BLK_DEV_INITRD) option) as shown here for a custom initramfs created in /usr/src/initramfs:

KERNEL CONFIG_INITRAMFS_SOURCE="/usr/src/initramfs" — (Example from Custom Initramfs)
General setup  --->
    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support
    (/usr/src/initramfs) Initramfs source file(s)

Embedding takes place on compilation, so the kernel must then be recompiled and be moved (or copied) again into the ESP.

Optional: Secure boot[edit | edit source]

There is a forums post and another wiki article explaining in detail how to sign the kernel and enable secure boot.

Troubleshooting[edit | edit source]

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[edit | edit source]

External resources[edit | edit source]


This article is issued from Gentoo. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.