EFI stub (EN PROCESO DE TRADUCCIÓN)

This page is a translated version of the page EFI stub and the translation is 11% complete.

Outdated translations are marked like this.

Other languages:

Resources

Official documentation

Package information

Wikipedia

This article has some todo items:

CONFIG_PM_STD_PARTITION for hibernation

El firmware (U)EFI presente en varias computadoras funciona como un cargador de arranque, permitiendo a los sistemas iniciar usando un bootloader EFI compatible. Usando el mismo kernel de Linux como un cargador del sistema, llamado un EFI stub. Esta configuración funciona sin la necesidad de un cargador de sistemas secundario. El artículo te da instrucciones para configurar e instalar kernels en el EFI System Partition (ESP) en vez de un computador iniciando en modo EFI.

An EFI stub (aka EFI boot stub)^[1] is a kernel that is an EFI executable, i.e. that can directly be booted from the UEFI firmware. This means a bootloader is not necessary for them. (But it is also possible to use a bootloader.)

Configuración del kernel

Soporte de EFI STUB

La siguientes opciones de la configuración del kernel deben de ser activadas:

KERNEL Activar el soporte del EFI STUB para la versión de el kernel mayor a 6.1

Processor type and features  --->
    [*] EFI runtime service support
    [*]     EFI stub support
    [ ]     EFI mixed-mode support (OPTIONAL)

Nota
El soporte del modo EFI mixto es solo requerido para iniciar un kernel de 64 bits desde un firmware de 32 bits si el procesador soporta el modo de 64 bits y el modo de entrega de EFI está activado.

Instalación

Consejo
Opcional: Si una EFI System Partition (ESP) no existe, por favor sigue los pasos de to set it up antes de esto.

Automatizado

Advertencia
Las implementaciones UEFI varían mucho entre vendedores, así que el arranque usando el método EFI STUB tal vez no funcione en todas las versiones de UEFI. Asegurate de tener un metodo secundario de arranque antes de intentar el arranque de EFI STUB.

Automated EFI stub booting is provided by sys-kernel/installkernel-38 and later when the efistub USE flag is enabled. This relocates the regular boot layout from /boot to the EFI/Gentoo directory on the EFI System Partition

Systemd kernel-install

El inicio automático de EFI STUB es administrado por el paquete sys-kernel/installkernel cuando la USE flag efistub está activada

For systemd systems:

root #systemctl enable --now kernel-bootcfg-boot-successful.service

For OpenRC systems:

root #rc-update add kernel-bootcfg-boot-successful default

When the to-be-registered kernel image is not an Unified Kernel Image a kernel command line for the new entry is read from:

/etc/kernel/cmdline, or
/usr/lib/kernel/cmdline, or
/proc/cmdline

in this order. In addition, the initrd= kernel command line argument is automatically added if an initramfs was generated while installing the kernel. If on the other hand the to-be-registered kernel is an Unified Kernel Image, then no command line is added to the new entry. Instead the command line built into the Unified Kernel Image is used, the contents of this built-in command line are usually also read from the same files when the UKI is generated.

Consejo
The kernel command line, as well as an initramfs, may also be embedded into the kernel, see the sections below for more information.

Traditional installkernel

When the efistub USE flag is enabled on sys-kernel/installkernel, but the systemd USE flag is disabled. Installkernel calls uefi-mkconfig from sys-boot/uefi-mkconfig to dynamically update the UEFI configuration. If the shim EFI executable is present in the same directory as the kernel image the kernels will be chainloaded via Shim.

Manual

It is recommended to create a separate directory below /efi/EFI, assuming the ESP is mounted at /efi. With the kernel configured with EFI Stub support, create a separate directory below /efi/EFI:

root #mkdir -p /efi/EFI/example

Nota
On some systems /efi/EFI or /efi/efi (in lowercase) may already exist (assuming the ESP is mounted at /efi). The FAT file system of the EFI System Partition (ESP) is not case-sensitive, but case-preserving (VFAT). With the default VFAT mount options, the above command will work in both cases. See the case sensitivity section in the FAT article for further details.

The kernel is created from the current kernel directory and copied to the new directory. This will install the kernel to /efi/EFI/example/bzImage.efi:

/usr/src/linux #make && make modules_install && cp arch/x86/boot/bzImage /efi/EFI/example/bzImage.efi

Consejo
It is recommended when upgrading the kernel to keep an older version which is proven to work:

user $tree -L 3 /efi

 /efi
 └── EFI
     └── example
         ├── bzImage-6.1.67.efi
         └── bzImage-6.1.70.efi

Root partition configuration

In order to boot directly from UEFI, the kernel or its initramfs needs to know where to find the root partition of the system to be booted. When using a bootmanager like grub the kernel gets its information where to find its root partition from the bootmanager via command line parameter. When using a stub kernel two options can be used to give the kernel this information - choose one of these options:

Option 1: Configuring it into the kernel

KERNEL Root Partiton information for Kernels 6.1+

Processor type and features  --->
    [*] Built-in kernel command line
    (root=PARTUUID=adf55784-15d9-4ca3-bb3f-56de0b35d88d ro)

Importante
{{{1}}}

Option 2: Configuring it into UEFI

To add an entry with kernel command line arguments:

root #efibootmgr --create --disk /dev/sda --label "Gentoo EFI Stub" --loader "\EFI\example\bzImage.efi" -u "root=/dev/sda3"

Importante
Setting the root location using a PARTUUID, or (filesystem) UUID when using a initramfs, is generally preferable and less error prone.

More examples can be found in Creating a boot entry.

Optional: Kernel with initramfs

When using a kernel with an external initramfs (as CPIO archive) additional steps are necessary. There is always an initramfs file when building a dist-kernel or when using genkernel. When using a dist-kernel this initramfs is named "initrd" and is in /usr/src/linux-6.1.57-gentoo-dist/arch/x86/boot/initrd. This file must must be copied also into the ESP:

root #cp /path/to/my/initramfs/myinitrd.cpio.gz /efi/EFI/example/initrd.cpio.gz

Now the kernel needs the information where to find it, and the initramfs needs the information where to find its root partition. UEFI must give both information:

root #

efibootmgr -c -d /dev/sda -p 1 -L "Gentoo EFI Stub" -l '\EFI\example\bzImage.efi' -u 'root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx initrd=\EFI\example\initrd.cpio.gz'

A Forums post explains it in more detail - and solved some user errors:

Forums topic - Booting UEFI without Grub

When using Early Userspace Mounting the Generating the Initramfs and Using a Stub Kernel sections explains it in more detail.

Optional: Embedded initramfs

It's also possible to embed the initramfs directly into the kernel. Advantages include the initramfs being verified by Secure Boot when it verifies the kernel, a simplified boot process and EFI partition, and it being easier to load the kernel by hand (because callers no longer need to specify the initramfs). Disadvantages are reduced flexibility, the ease of making a mistake, and using an unconventional boot setup.

Advertencia
If your initramfs contains Microcode, then it is critical for security that it is receiving updates. When embedded, the initramfs can't be updated independently of the kernel, and a kernel rebuild will be necessary every time the initramfs is updated. In particular, please ensure that:

If
root #make clean
is not being run before rebuilding the kernel,
root #rm usr/initramfs_data.cpio
is run to clear the cached initramfs CPIO archive that remains from the last build.
When the initramfs has an update, the kernel is rebuilt and reinstalled.
If the initramfs is managed by sys-apps/portage, the initramfs is updated before the kernel.

The kernel supports both CPIO files (for example, as produced by Dracut) and source directories which are to be compressed into a CPIO archive. The following shows the latter with /usr/src/initramfs, however should be substituted with /path/to/my/initramfs/myinitrd.cpio.gz if the former case is desired (it usually is, unless you are using a Custom Initramfs).

KERNEL Embedding the initramfs into the kernel

General Setup  --->
    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support
    (/usr/src/initramfs) Initramfs source file(s)

EFI firmware configuration

To ensure everything is functioning correctly, the kernel may be booted without the initrd command line argument.

To create the Unified Kernel Image entry:

root #efibootmgr --create --disk /dev/sda --label "Gentoo EFI Stub" --loader "\EFI\example\bzImage.efi"

Backup kernel

It is recommended to always have a backup kernel. If a bootmanager like grub is already installed, it should not be uninstalled, because grub can boot a stub kernel just like a normal kernel. A second possibility is to work with an additional UEFI entry. Before installing a new kernel, the current one can be copied from /efi/EFI/example/ to /efi/EFI/backup. The second UEFI entry was also created with efibootmgr. In this example, other names were used:

root #efibootmgr

BootCurrent: 0002
Timeout: 1 seconds
BootOrder: 0002,0000,0001
Boot0000* Secure        HD(1,GPT,0adcbfee-21aa-42ea-9a9a-2e53bd05e6a2,0x800,0x7f800)/File(\EFI\secure\bzImage.efi)
Boot0001* gentoo        HD(1,GPT,0adcbfee-21aa-42ea-9a9a-2e53bd05e6a2,0x800,0x7f800)/File(\EFI\gentoo\grubx64.efi)
Boot0002* Backup        HD(1,GPT,0adcbfee-21aa-42ea-9a9a-2e53bd05e6a2,0x800,0x7f800)/File(\EFI\backup\bzImage.efi)

Microcode loading

When using a kernel without an initramfs it is recommended to load the microcode described in the following articles:

Optional: Signing for Secure Boot

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

root #sbsign --key {db key} --cert {db cert} /efi/EFI/example/bzImage.efi

More information is available at Secure Boot.

Advertencia
It is not possible to EFI Stub boot via sys-boot/shim due to the vanilla EFI Stub missing the required .sbat sbat section. As such the used signing keys must be registered directly with the UEFI firmware to EFI Stub boot with Secure Boot enabled. See the Unified Kernel Image wiki page for an alternate EFI Stub booting method that does support booting via shim.

Troubleshooting

Consejo
Some rare (U)EFI implementations do not accept individual EFI entries. In this case it often works to use the removable media boot path, see EFI System Partition #removable media for details. E.g. this command will copy the kernel for a 64 bit UEFI:

root #cp /usr/src/linux/arch/x86/boot/bzImage /efi/EFI/boot/bootx64.efi

Be advised that this is against the (U)EFI specification, as it will circumvent the (U)EFI boot selection on internal drives (which are configured using EFI boot entries).

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: