x86 Platforms – Part 2: UEFI Bootloader Management and Integration with Yocto

In this part, we continue to explore bootloader management in UEFI systems, focusing on integrating GRUB and systemd-boot. We will also cover advanced boot mechanisms such as Linux EFI stub and Unified Kernel Images (UKI). Additionally, we will discuss using Yocto’s wic tool to create bootable images with an EFI System Partition (ESP) and a root filesystem partition.

Bootloader Integration in UEFI Systems

In UEFI-based systems, bootloaders like GRUB and systemd-boot play a crucial role in the system’s boot process by loading the operating system. Once installed, the bootloader binary’s location can be either explicitly configured in the UEFI firmware’s settings using NVRAM (Non-Volatile Random-Access Memory) entries, or it can simply be placed in a fallback path within the EFI System Partition (ESP).

When a bootloader is configured via NVRAM, the UEFI firmware is directed to a specific location to load the bootloader. This approach offers more control, allowing for multiple operating systems or kernel configurations to be managed. However, if the bootloader is placed in a fallback path, such as \EFI\BOOT\bootx64.efi for x86_64 systems, the firmware will automatically load it without needing NVRAM configuration. The fallback method is especially useful for system recovery or when NVRAM settings are unavailable or corrupted.

Both approaches – NVRAM configuration and fallback paths – ensure flexibility in managing bootloader locations on UEFI-based systems, making it easier to handle multi-boot setups or system recovery.

systemd-boot in UEFI Systems

systemd-boot is a simple UEFI boot manager that directly loads EFI-compliant binaries, including the Linux kernel when compiled with the EFI stub.

• Installation: systemd-boot can be registered in UEFI firmware or placed in the fallback path at \EFI\BOOT\bootx64.efi on the ESP.
• Configuration: systemd-boot uses simple text-based configuration files:
  • /boot/loader/loader.conf: Defines bootloader behavior (e.g., default entry, timeout).
  • /boot/loader/entries/*.conf: Defines boot entries with kernel images and boot options. Each file corresponds to a boot entry.
    • Systemd-boot requires both a loader.conf for global settings and one or more boot entry files for each kernel option.

Example loader.conf:

default default boot-5.10.conf
timeout 5

Example boot entry (boot-5.10.conf):

title   MyLinux 5.10
linux   /vmlinuz-5.10
initrd  /initramfs-5.10.img
options root=/dev/sda2 rw quiet splash

Example boot entry (boot-4.19.conf):

title   MyLinux 4.19
linux   /vmlinuz-4.19
initrd  /initramfs-4.19.img
options root=/dev/sda2 rw quiet splash

• default boot-5.10.conf: Specifies the default boot entry by referencing its .conf file in /boot/loader/entries/.
• timeout 5: Sets the timeout before the default boot entry is chosen automatically.
• console-mode keep: Controls the console resolution mode during boot.

Key Variables in Boot Entry Files (boot-5.10.conf, etc.) are:

• title: The display name for this boot entry.
• linux: The path to the kernel image, relative to the ESP. It must have been compiled with EFI stub support (CONFIG_EFI_STUB=y), turning the kernel into an EFI-compliant binary.
• initrd: The path to the initial RAM disk relative to the ESP.
• options: Kernel boot parameters, such as the root filesystem and boot options like quiet or splash.

Systemd-boot requires both a loader.conf for global settings and one or more boot entry files for each kernel option.

GRUB in UEFI Systems

GRUB is a feature-rich bootloader supporting multi-OS booting, multiple filesystems, and complex configurations. GRUB functions as both a boot manager and bootloader.

• Installation: GRUB can be installed in UEFI’s NVRAM or placed in the ESP’s fallback path (\EFI\BOOT\bootx64.efi).
• Configuration Files:
  • /boot/grub/grub.cfg: The main configuration file for defining boot options. The structure of this file is essential for GRUB’s functionality, as it provides the boot menu and ensures the correct kernel is loaded
  • /boot/grub/grubenv: Stores grub’s persistent settings (e.g., environment variables, boot logic, …).

Example grub.cfg:

set default=0
set timeout=5

menuentry "MyLinux 5.10" {
    set root=(hd0,1)
    linux /vmlinuz-5.10 root=/dev/sda2 ro quiet
	initrd /initramfs-5.10.img
}

menuentry "MyLinux 4.19" {
    set root=(hd0,1)
    linux /vmlinuz-4.19 root=/dev/sda2 ro quiet
    initrd /initramfs-4.19.img
}

Key Variables in grub.cfg includes:

• set timeout=5: Defines how long GRUB waits before booting the default option.
• set default=0: Specifies the default boot option (first entry in the list).
• menuentry: Each menuentry block defines a bootable kernel option.
• linux: The path to the kernel image and additional kernel parameters (like the root partition).
• initrd: Specifies the path to the initial RAM disk (initramfs).

This configuration presents two boot options for the user, one for Linux kernel 5.10 and another for kernel 4.19.

Managing GRUB’s grubenv Outside the ESP

While grub.cfg must reside in the ESP, the grubenv file can be stored outside the ESP. This setup is useful in scenarios where the ESP is updated separately from the rest of the system. To configure GRUB to load grubenv from a different partition, use the --file argument in the load_env and save_env commands in grub.cfg:

load_env --file=(hd0,2)/grubenv
[...]
save_env --file=(hd0,2)/grubenv

This method allows GRUB to load and save the environment file from a separate partition.

Direct Kernel Booting with EFI Stub

The Linux kernel can be compiled with EFI stub support (CONFIG_EFI_STUB=y), enabling it to act as an EFI-compliant binary that can be booted directly by UEFI firmware or by a simple boot manager like systemd-boot. It can be achieved thhough the following steps:

1. Compile the Kernel with EFI Stub Support:
   CONFIG_EFI_STUB=y
2. Place the Kernel in the ESP: Copy the kernel to the ESP (typically /efi/boot/bootx64.efi).
3. Set Up Kernel Command Line with efibootmgr: When creating a UEFI boot entry, you can specify kernel parameters directly. However, paths must be properly formatted according to EFI standards, using backslashes and being relative to the ESP.

Specifying Kernel Command Line Options with efibootmgr

When setting up a boot entry with efibootmgr, it’s essential to follow the correct formatting for paths to match EFI standards by using backslashes and ensuring the paths are relative to the ESP. For example, the path to the initramfs should be specified relative to the ESP and use backslashes. Here’s how you can configure the efibootmgr command:

efibootmgr --create --disk /dev/sda --part 1 --label "MyLinux" --loader '\EFI\arch\vmlinuz-linux' \
    --unicode "root=/dev/sda2 rw initrd=\EFI\arch\initramfs-linux.img"

This example assumes the kernel and initramfs are located under /EFI/arch in the ESP. Proper path formatting ensures compatibility with UEFI standards.

Limitations of Direct Kernel Booting

While direct kernel booting simplifies the boot process, it has some limitations:

• No Boot Menu: Users cannot select between multiple kernels or configurations.
• Parameter Management: Kernel command-line arguments must be handled via UEFI configuration, which can be cumbersome.

Furthermore, some UEFI firmwares do not pass command-line parameters from the NVRAM boot entries to the EFI binaries (even though you can sometime contact the CoM vendor for customization). In such cases, kernel parameters specified in boot entries are ignored, making it difficult to control boot behavior.

One solution might be to compile the kernel with command line set in CONFIG_CMDLINE. However, you’ll need to recompile your kernel every time need be to change a parameter in command line. A solution to this problem is to combine the kernel and its parameters into a Unified Kernel Image (UKI). The resulting .efi file can then be used to create a new boot entry that includes all necessary parameters, bypassing the firmware limitation.

Unified Kernel Image (UKI) Booting

A Unified Kernel Image (UKI) consolidates the Linux kernel, initramfs, and other components into a single EFI binary, simplifying the boot process and enhancing security (especially for systems using Secure Boot). A UKI image has the following core components:

1. UEFI Boot Stub: Forms the initial executable program of the UKI. This binary is architecture-specific and can be provided by the systemd-boot package (e.g., linuxx64.efi.stub, linuxia32.efi.stub for x86_64 and x86_32, respectively).The UEFI boot stub binary is recommended to avoid frequent kernel rebuilds since it can fetch kernel parameters from the EFI configuration.
2. Linux Kernel: Must be compiled with CONFIG_EFI_STUB=y and is stored in the .linux section of the UKI.
3. Optional Components:
   • OS Information (.osrel section): Derived from /etc/os-release.
   • Kernel Command Line (.cmdline section): Stores kernel boot parameters.
   • Initrd (.initrd section): Initial RAM disk loaded during boot.
   • Microcode Initrd (.ucode section): Microcode updates for the CPU.

There are two methods to create a UKI image: using objcopy or ukify tool.

Creating a UKI with objcopy

You can create a UKI using objcopy, merging the kernel, initramfs, and other components into a single EFI binary.

Example process:

MICRO_CODE_1="microcode.cpio"
MICRO_CODE_2="acpi_override.cpio"
INITRD="core-image-initramfs.cpio.gz"
KERNEL="bzImage"

# Create a combined initrd
cat ${MICRO_CODE_1} ${MICRO_CODE_2} ${INITRD} > /path/to/initrd

# Use objcopy to create the UKI
objcopy \
   --add-section .osrel=/usr/lib/os-release --change-section-vma .osrel=0x20000 \
   --add-section .cmdline=/path/to/cmdline-file --change-section-vma .cmdline=0x30000 \
   --add-section .linux=/path/to/${KERNEL} --change-section-vma .linux=0x2000000 \
   --add-section .initrd=/path/to/initrd --change-section-vma .initrd=0x3000000 \
   /path/to/linuxx64.efi.stub /boot/efi/EFI/Linux/linux.efi

This process creates a unified kernel image with all necessary boot components, which can be placed in the ESP for direct booting by UEFI.

CONFIG_EFI_STUB vs. linux<arch>efi.stub (Systemd Stub)

CONFIG_EFI_STUB and linux<arch>.efi.stub (the systemd boot stub) serve similar purposes but are not mutually exclusive. Both can be used independently or in combination, depending on the needs of the system. Here’s a breakdown of their relationship:

• CONFIG_EFI_STUB: This option allows the Linux kernel to be compiled with its own EFI stub, turning the kernel itself into an EFI executable. With this option enabled, you can boot the kernel directly from UEFI without needing any additional bootloader or boot stub. It’s ideal for minimal setups or embedded systems where the boot process is streamlined.
• linux<arch>.efi.stub (Systemd Stub): This architecture-specific stub, provided by the systemd-boot package, allows more flexibility than CONFIG_EFI_STUB. It separates the kernel from the boot configuration, enabling developers to modify kernel parameters without recompiling the kernel. The systemd stub reads kernel parameters from the EFI configuration or from sections in the UKI, such as .cmdline and .initrd, allowing dynamic updates.

Can They Be Used Together?

• UKI (Unified Kernel Image): Both CONFIG_EFI_STUB and linux<arch>.efi.stub can be used together when creating a Unified Kernel Image. In this case, the kernel is compiled with CONFIG_EFI_STUB, while the systemd stub provides additional flexibility in managing the boot process by fetching boot parameters dynamically from the EFI configuration. The systemd stub is highly recommended for UKI because it enables updates to kernel parameters and other components without requiring a full kernel rebuild.

Are They Mandatory for UKI?

• CONFIG_EFI_STUB is mandatory when creating a UKI because the kernel must be EFI-compliant to be included in the image.
• linuxx64.efi.stub (systemd boot stub) is not mandatory but highly recommended for UKI creation due to its flexibility in handling kernel parameters and boot configuration.

In summary, while CONFIG_EFI_STUB enables the kernel to be directly booted as an EFI binary, using linuxx64.efi.stub offers additional flexibility and is preferred for dynamic systems or when using UKI.