UEFI - ParabolaWiki

# UEFI

Warning: While the choice to install in EFI mode is forward looking, early vendor UEFI implementations carried more bugs than their BIOS counterparts. It is advised to do a search relating your particular mainboard model before proceeding.

Unified Extensible Firmware Interface (or UEFI for short) is a new type of firmware. It introduces new ways of booting an OS that is distinct from the commonly used "MBR boot code" method followed for BIOS systems. See Arch boot process#Firmware types for their differences. This page explains What is UEFI and UEFI support in Linux kernel. To set up UEFI Boot Loaders, see Boot loaders.

## UEFI versions

- UEFI started as Intel's EFI in versions 1.x.
- Later, a group of companies called the UEFI Forum took over its development, which renamed it as Unified EFI starting with version 2.0.
- Unless specified as EFI 1.x, EFI and UEFI terms are used interchangeably to denote UEFI 2.x firmware.
- As of 15 April 2015, UEFI Specification 2.5 is the most recent version.
- Apple's EFI implementation is neither a EFI 1.x version nor UEFI 2.x version but mixes up both. This kind of firmware does not fall under any one (U)EFI specification and therefore is not a standard UEFI firmware. Unless stated explicitly, these instructions are general and some of them may not work or may be different in Apple Macs.

## Boot Process under UEFI

1. System switched on - Power On Self Test, or POST process.
2. UEFI firmware is loaded. Firmware initializes the hardware required for booting.
3. Firmware then reads its Boot Manager data to determine which UEFI application to be launched and from where (i.e. from which disk and partition).
4. Firmware then launches the UEFI application as defined in the boot entry in the firmware's boot manager.
5. The launched UEFI application may launch another application (in case of UEFI Shell or a boot manager like rEFInd) or the kernel and initramfs (in case of a boot loader like GRUB) depending on how the UEFI application was configured.

Note: On some UEFI systems the only possible way to launch UEFI application on boot (if it does not have custom entry in UEFI boot menu) is to put it in this fixed location: <EFI SYSTEM PARTITION>/EFI/BOOT/BOOTX64.EFI (for 64-bit x86 system)

### Multibooting in UEFI

Since each OS or vendor can maintain its own files within the EFI System Partition without affecting the other, multi-booting using UEFI is just a matter of launching a different UEFI application corresponding to the particular OS's bootloader. This removes the need for relying on chainloading mechanisms of one boot loader to load another to switch OSes.

### Secure Boot

For an overview about Secure Boot in GNU/Linux see Rodsbooks' Secure Boot article. This section focuses on how to set up Secure Boot in Parabola. For the time being, this section is limited to explain the procedure of booting the archiso with Secure Boot enabled. Booting the archiso with Secure Boot enabled is possible since the EFI applications PreLoader.efi and HashTool.efi have been added to it. A message will show up that says Failed to Start loader... I will now execute HashTool. To use HashTool for enrolling the hash of loader.efi and vmlinuz.efi, follow these steps.

- Select OK
- In the HashTool main menu, select Enroll Hash, choose \loader.efi and confirm with Yes. Again, select Enroll Hash and parabolaiso to enter the parabolaiso directory, then select vmlinuz-efi and confirm with Yes. Then choose Exit to return to the boot device selection menu.
- In the boot device selection menu choose Parabola parabolaiso x86_64 UEFI CD

The parabolaiso boots, and you are presented with a shell prompt, automatically logged in as root. To check if the archiso was booted with Secure Boot, use this command:

    $ od -An -t u1 /sys/firmware/efi/efivars/SecureBoot-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

The characters denoted by XXXX differ from machine to machine. To help with this, you can use tab completion or list the EFI variables.

If a Secure Boot is enabled, this command returns 1 as the final integer in a list of five, for example:

    6  0  0  0  1

For a verbose status, another way is to execute:

    # bootctl status

## Linux Kernel Config options for UEFI

The required Linux Kernel configuration options for UEFI systems are :

    CONFIG_RELOCATABLE=y
    CONFIG_EFI=y
    CONFIG_EFI_STUB=y
    CONFIG_FB_EFI=y
    CONFIG_FRAMEBUFFER_CONSOLE=y

UEFI Runtime Variables Support (efivarfs filesystem - /sys/firmware/efi/efivars). This option is important as this is required to manipulate UEFI Runtime Variables using tools like /usr/bin/efibootmgr. The below config option has been added in kernel 3.10 and above.

    CONFIG_EFIVAR_FS=y

UEFI Runtime Variables Support (old efivars sysfs interface - /sys/firmware/efi/vars). This option should be disabled to prevent any potential issues with both efivarfs and sysfs-efivars enabled.

    CONFIG_EFI_VARS=n

GUID Partition Table GPT config option - mandatory for UEFI support

    CONFIG_EFI_PARTITION=y

Note: All of the above options are required to boot GNU/Linux via UEFI, and are enabled in Parabola kernels in official repos.

Retrieved from https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/x86/x86_64/uefi.txt .

## UEFI Variables

UEFI defines variables through which an operating system can interact with the firmware. UEFI Boot Variables are used by the boot-loader and used by the OS only for early system start-up. UEFI Runtime Variables allow an OS to manage certain settings of the firmware like the UEFI Boot Manager or managing the keys for UEFI Secure Boot Protocol etc. You can get the list using

    $ efivar -l

### UEFI Variables Support in Linux Kernel

Linux kernel exposes EFI variables data to userspace via efivarfs (EFI VARiable FileSystem) interface (CONFIG_EFIVAR_FS) - mounted using efivarfs kernel module at /sys/firmware/efi/efivars - it has no maximum per-variable size limitation and supports UEFI Secure Boot variables. Introduced in kernel 3.8.

### Requirements for UEFI variable support

1. EFI Runtime Services support should be present in the kernel (CONFIG_EFI=y, check if present with zgrep CONFIG_EFI /proc/config.gz).
2. Kernel processor bitness and EFI processor bitness should match
3. Kernel should be booted in EFI mode (via EFISTUB or any EFI boot loader, not via BIOS/CSM or Apple's "bootcamp" which is also BIOS/CSM)
4. EFI Runtime Services in the kernel SHOULD NOT be disabled via kernel cmdline, i.e. noefi kernel parameter SHOULD NOT be used
5. efivarfs filesystem should be mounted at /sys/firmware/efi/efivars, otherwise follow #Mount efivarfs section below.
6. efivar should list (option -l) the EFI Variables without any error.

If EFI Variables support does not work even after the above conditions are satisfied, try the below workarounds:

1. If any userspace tool is unable to modify efi variables data, check for existence of /sys/firmware/efi/efivars/dump-* files. If they exist, delete them, reboot and retry again.
2. If the above step does not fix the issue, try booting with efi_no_storage_paranoia kernel parameter to disable kernel efi variable storage space check that may prevent writing/modification of efi variables.

Note: efi_no_storage_paranoia should only be used when needed and should not be left as a normal boot option. The effect of this kernel command line parameter turns off a safeguard that was put in place to help avoid the bricking of machines when the NVRAM gets too full.

#### Mount efivarfs

If efivarfs is not automatically mounted at /sys/firmware/efi/efivars by systemd during boot, then you need to manually mount it to expose UEFI Variable support to the userspace tools like efibootmgr etc.:

    # mount -t efivarfs efivarfs /sys/firmware/efi/efivars

Note: The above command should be run both OUTSIDE (BEFORE) and INSIDE chroot, if any.

It is also a good idea to auto-mount efivarfs during boot via /etc/fstab as follows:

    /etc/fstab

    efivarfs    /sys/firmware/efi/efivars    efivarfs    defaults    0    0

### Userspace Tools

There are few tools that can access/modify the UEFI variables, namely

1. efivar - Library and Tool to manipulate UEFI Variables (used by efibootmgr) - https://github.com/vathpela/efivar - efivar
2. efibootmgr - Tool to manipulate UEFI Firmware Boot Manager Settings - https://github.com/vathpela/efibootmgr - efibootmgr or efibootmgr-git

#### efibootmgr

Note:

- If efibootmgr completely fails to work in your system, you can reboot into UEFI Shell v2 and use bcfg command to create a boot entry for the bootloader.
- If you are unable to use efibootmgr, some UEFI firmwares allow users to directly manage uefi boot entries from within its boot-time interface. For example, some ASUS firmwares have an "Add New Boot Option" choice which enables you to select a local EFI System Partition and manually enter the EFI stub location. (for example \EFI\refind\refind_x64.efi).
- The below commands use refind-efi boot-loader as example.

Assuming the boot-loader file to be launched is /boot/efi/EFI/refind/refind_x64.efi, /boot/efi/EFI/refind/refind_x64.efi can be split up as /boot/efi and /EFI/refind/refind_x64.efi, wherein /boot/efi is the mountpoint of the EFI System Partition, which is assumed to be /dev/sdXY (here X and Y are just placeholders for the actual values - eg:- in /dev/sda1 , X==a Y==1).

To determine the actual device path for the EFI System Partition (assuming mountpoint /boot/efi for example) (should be in the form /dev/sdXY), try :

    # findmnt /boot/efi
    TARGET SOURCE  FSTYPE OPTIONS
    /boot/efi  /dev/sdXY  vfat         rw,flush,tz=UTC

Verify that uefi variables support in kernel is working properly by running:

    # efivar -l

If efivar lists the uefi variables without any error, then you can proceed. If not, check whether all the conditions in #Requirements for UEFI variable support are met.

Then create the boot entry using efibootmgr as follows:

    # efibootmgr -c -d /dev/sdX -p Y -l /EFI/refind/refind_x64.efi -L "rEFInd"

Note: UEFI uses backward slash \ as path separator (similar to Windows paths), but the official efibootmgr pkg support passing unix-style paths with forward-slash / as path-separator for the -l option. Efibootmgr internally converts / to \ before encoding the loader path. The relevant git commit that incorporated this feature in efibootmgr is http://linux.dell.com/cgi-bin/cgit.cgi/efibootmgr.git/commit/?id=f38f4aaad1dfa677918e417c9faa6e3286411378 .

In the above command /boot/efi/EFI/refind/refind_x64.efi translates to /boot/efi and /EFI/refind/refind_x64.efi which in turn translate to drive /dev/sdX -> partition Y -> file /EFI/refind/refind_x64.efi.

The 'label' is the name of the menu entry shown in the UEFI boot menu. This name is user's choice and does not affect the booting of the system. More info can be obtained from efibootmgr GIT README .

FAT32 filesystem is case-insensitive since it does not use UTF-8 encoding by default. In that case the firmware uses capital 'EFI' instead of small 'efi', therefore using \EFI\refind\refindx64.efi or \efi\refind\refind_x64.efi does not matter (this will change if the filesystem encoding is UTF-8).

## EFI System Partition

The EFI System Partition (also called ESP or EFISYS) is a FAT32 formatted physical partition (in the main partition table of the disk, not LVM or software raid etc.) from where the UEFI firmware launches the UEFI bootloader and application.

It is an OS independent partition that acts as the storage place for the EFI bootloaders and applications to be launched by the EFI firmware. It is mandatory for UEFI boot. It should have the EFI System partition type (see #GPT partitioned disks). It is recommended to keep ESP size at 512 MiB although smaller/larger sizes are fine (see note below). For more information see Wikipedia:EFI System partition.

Note:

- It is recommended to use always GPT for UEFI boot as some UEFI firmwares do not allow UEFI-MBR boot.
- In GNU Parted, boot flag (not to be confused with legacy_boot flag) has different effect in MBR and GPT disk. In MBR disk, it marks the partition as active. In GPT disk, it changes the type code of the partition to EFI System Partition type. Parted has no flag to mark a partition as ESP in MBR disk (this can be done using fdisk though).
- According to a Microsoft note[1], the minimum size for the EFI System Partition (ESP) would be 100 MB, though this is not stated in the UEFI Specification. Note that for Advanced Format 4K Native drives (4-KB-per-sector) drives, the size is at least 260 MB, because it's the minimum partition size of FAT32 drives (calculated as sector size (4KB) x 65527 = 256 MB), due to a limitation of the FAT32 file format.
- In case of EFISTUB, the kernels and initramfs files should be stored in the EFI System Partition. For sake of simplicity, you can also use the ESP as the /boot partition itself instead of a separate /boot partition, for EFISTUB booting.

### GPT partitioned disks

- fdisk/gdisk: Create a partition with partition type EFI System (EFI System in fdisk or ef00 in gdisk). Then format that partition as FAT32 using mkfs.fat -F32 /dev/<THAT_PARTITION>

(or)

- GNU Parted: Create a FAT32 partition and in Parted set/activate the boot flag (not legacy_boot flag) on that partition

Note: If you get the message WARNING: Not enough clusters for a 32 bit FAT!, reduce cluster size with mkfs.fat -s2 -F32 ... or -s1, otherwise the partition may be unreadable by UEFI.

### MBR partitioned disks

- fdisk: Create a partition with partition type EFI System using fdisk. Then format that partition as FAT32 using mkfs.fat -F32 /dev/<THAT_PARTITION>

### ESP on RAID

It is possible to make the ESP part of a RAID1 array, but doing so brings the risk of data corruption, and further considerations need to be taken when creating the ESP. See https://bbs.archlinux.org/viewtopic.php?pid=1398710#p1398710 and https://bbs.archlinux.org/viewtopic.php?pid=1390741#p1390741 for details.

## UEFI Shell

The UEFI Shell is a shell/terminal for the firmware which allows launching uefi applications which include uefi bootloaders. Apart from that, the shell can also be used to obtain various other information about the system or the firmware like memory map (memmap), modifying boot manager variables (bcfg), running partitioning programs (diskpart), loading uefi drivers, editing text files (edit), hexedit etc.

### Obtaining UEFI Shell

You can download a BSD licensed UEFI Shell from Intel's Tianocore UDK/EDK2 Sourceforge.net project:

- There are copies of Shell v1 and Shell v2 in the EFI directory on the Arch install media image.
- Precompiled x86_64 UEFI Shell v2 binary (may not be up-to-date)
- Precompiled x86_64 UEFI Shell v1 binary (not updated anymore upstream)
- Precompiled IA32 UEFI Shell v2 binary (may not be up-to-date)
- Precompiled IA32 UEFI Shell v1 binary (not updated anymore upstream)

Shell v2 works best in UEFI 2.3+ systems and is recommended over Shell v1 in those systems. Shell v1 should work in all UEFI systems irrespective of the spec. version the firmware follows. More info at ShellPkg and this mail

### Launching UEFI Shell

Few Asus and other AMI Aptio x86_64 UEFI firmware based motherboards (from Sandy Bridge onwards) provide an option called "Launch EFI Shell from filesystem device" . For those motherboards, download the x86_64 UEFI Shell and copy it to your EFI System Partition as <EFI_SYSTEM_PARTITION>/shellx64.efi (mostly /boot/efi/shellx64.efi) .

Systems with Phoenix SecureCore Tiano UEFI firmware are known to have embedded UEFI Shell which can be launched using either F6, F11 or F12 key.

Note: If you are unable to launch UEFI Shell from the firmware directly using any of the above mentioned methods, create a FAT32 USB pen drive with Shell.efi copied as (USB)/efi/boot/bootx64.efi. This USB should come up in the firmware boot menu. Launching this option will launch the UEFI Shell for you.

### Important UEFI Shell Commands

UEFI Shell commands usually support -b option which makes output pause after each page. map lists recognized filesystems (fs0, ...) and data storage devices (blk0, ...). Run help -b to list available commands.

More info at http://software.intel.com/en-us/articles/efi-shells-and-scripting/

#### bcfg

BCFG command is used to modify the UEFI NVRAM entries, which allow the user to change the boot entries or driver options. This command is described in detail in page 83 (Section 5.3) of "UEFI Shell Specification 2.0" PDF document.

Note:

- Users are recommended to try bcfg only if efibootmgr fails to create working boot entries in their system.
- UEFI Shell v1 official binary does not support bcfg command. You can download a modified UEFI Shell v2 binary which may work in UEFI pre-2.3 firmwares.

To dump a list of current boot entries:

    Shell> bcfg boot dump -v

To add a boot menu entry for rEFInd (for example) as 4th (numbering starts from zero) option in the boot menu:

    Shell> bcfg boot add 3 fs0:\EFI\refind\refind_x64.efi "rEFInd"

where fs0: is the mapping corresponding to the EFI System Partition and fs0:\EFI\refind\refind_x64.efi is the file to be launched.

To remove the 4th boot option:

    Shell> bcfg boot rm 3

To move the boot option #3 to #0 (i.e. 1st or the default entry in the UEFI Boot menu):

    Shell> bcfg boot mv 3 0

For bcfg help text:

    Shell> help bcfg -v -b

or:

    Shell> bcfg -? -v -b

#### edit

EDIT command provides a basic text editor with an interface similar to nano text editor, but slightly less functional. It handles UTF-8 encoding and takes care or LF vs CRLF line endings.

To edit, for example rEFInd's refind.conf in the EFI System Partition (fs0: in the firmware)

    Shell> fs0:
    FS0:\> cd \EFI\arch\refind
    FS0:\EFI\arch\refind\> edit refind.conf

Type Ctrl-E for help.

## UEFI Linux Hardware Compatibility

See Unified Extensible Firmware Interface/Hardware for more information.

## UEFI Bootable Media

### Create UEFI bootable USB from ISO

Follow USB flash installation media#BIOS and UEFI Bootable USB

### Remove UEFI boot support from Optical Media

Note: This section mentions removing UEFI boot support from a CD/DVD only (Optical Media), not from a USB flash drive.

Most of the 32-bit EFI Macs and some 64-bit EFI Macs refuse to boot from a UEFI(X64)+BIOS bootable CD/DVD. If one wishes to proceed with the installation using optical media, it might be necessary to remove UEFI support first.

- Mount the official installation media and obtain the archisolabel as shown in the previous section.

    # mount -o loop input.iso /mnt/iso

- Then rebuild the ISO, excluding the UEFI Optical Media booting support, using xorriso from libisoburn. Be sure to set the correct parabolaisolabel, e.g. "PARABOLA_201411" or similar:

    $ xorriso -as mkisofs -iso-level 3 \
        -full-iso9660-filenames\
        -volid "parabolaisolabel" \
        -appid "Parabola GNU/Linux-libre CD" \
        -publisher "Parabola GNU/Linux-libre <https://www.parabola.nu>" \
        -preparer "prepared by $USER" \
        -eltorito-boot isolinux/isolinux.bin \
        -eltorito-catalog isolinux/boot.cat \
        -no-emul-boot -boot-load-size 4 -boot-info-table \
        -isohybrid-mbr "/mnt/iso/isolinux/isohdpfx.bin" \
        -output output.iso /mnt/iso/

- Burn output.iso to optical media and proceed with installation normally.

## Testing UEFI in systems without native support

### OVMF for Virtual Machines

OVMF is a tianocore project to enable UEFI support for Virtual Machines. OVMF contains a sample UEFI firmware for QEMU.

## Troubleshooting

### USB media gets struck with black screen

- This issue can occur either due to KMS issue. Try Disabling KMS while booting the USB.

- If the issue is not due to KMS, then it may be due to bug in EFISTUB booting (see [2] and [3] for more information.). Both Official ISO (Parabolaiso) and Parabolaboot iso use EFISTUB (via Gummiboot Boot Manager for menu) for booting the kernel in UEFI mode. In such a case you have to use GRUB as the USB's UEFI bootloader by following the below section.

#### Using GRUB

Tip: The given configuration entries can also be entered inside a GRUB command-shell.

- Create an USB Flash Installation

- Backup EFI/boot/loader.efi to EFI/boot/gummiboot.efi

- Create a GRUB standalone image and copy the generate grub*.efi to the USB as EFI/boot/loader.efi, EFI/boot/bootx64.efi and/or EFI/boot/bootia32.efi (useful when running on a 32-bit UEFI)

- Create EFI/boot/grub.cfg with the following contents (replace PARABOLA_YYYYMM with the required archiso label e.g. PARABOLA_201507):

    grub.cfg for Official ISO

    insmod part_gpt
    insmod part_msdos
    insmod fat

    insmod efi_gop
    insmod efi_uga
    insmod video_bochs
    insmod video_cirrus

    insmod font

    if loadfont "${prefix}/fonts/unicode.pf2" ; then
        insmod gfxterm
        set gfxmode="1024x768x32;auto"
        terminal_input console
        terminal_output gfxterm
    fi

    menuentry "Parabola GNU/Linux-libre parabolaiso x86_64" {
        set gfxpayload=keep
        search --no-floppy --set=root --label PARABOLA_YYYYMM
        linux /arch/boot/x86_64/vmlinuz-linux-libre archisobasedir=parabola parabolaisolabel=ARCH_YYYYMM add_efi_memmap
        initrd /arch/boot/x86_64/parabolaiso.img
    }

    menuentry "UEFI Shell x86_64 v2" {
        search --no-floppy --set=root --label PARABOLA_YYYYMM
        chainloader /EFI/shellx64_v2.efi
    }

    menuentry "UEFI Shell x86_64 v1" {
        search --no-floppy --set=root --label PARABOLA_YYYYMM
        chainloader /EFI/shellx64_v1.efi
    }

    grub.cfg for Parabolaboot ISO

    insmod part_gpt
    insmod part_msdos
    insmod fat

    insmod efi_gop
    insmod efi_uga
    insmod video_bochs
    insmod video_cirrus

    insmod font

    if loadfont "${prefix}/fonts/unicode.pf2" ; then
        insmod gfxterm
        set gfxmode="1024x768x32;auto"
        terminal_input console
        terminal_output gfxterm
    fi

    menuentry "Parabola GNU/Linux-libre x86_64 Parabolaboot" {
        set gfxpayload=keep
        search --no-floppy --set=root --file /boot/vmlinuz_x86_64
        linux /boot/vmlinuz_x86_64 cgroup_disable=memory loglevel=7 add_efi_memmap
        initrd /boot/initramfs_x86_64.img
    }

    menuentry "UEFI Shell x86_64 v2" {
        search --no-floppy --set=root --file /boot/vmlinuz_x86_64
        chainloader /EFI/tools/shellx64_v2.efi
    }

    menuentry "UEFI Shell x86_64 v1" {
        search --no-floppy --set=root --file /boot/vmlinuz_x86_64
        chainloader /EFI/tools/shellx64_v1.efi
    }

### UEFI boot loader does not show up in firmware menu

On some UEFI motherboards like boards with an Intel Z77 chipset, adding entries with efibootmgr or bcfg from the EFI Shell will not work because they do not show up on the boot menu list after being added to NVRAM.

This issue is caused because the motherboards can only load Microsoft Windows. To solve this you have to place the .efi file in the location that Windows uses.

Copy the bootx64.efi file from the Parabola installation medium (FSO:) to the Microsoft directory your ESP partition on your hard drive (FS1:). Do this by booting into EFI shell and typing:

    FS1:
    cd EFI
    mkdir Microsoft
    cd Microsoft
    mkdir Boot
    cp FS0:\EFI\BOOT\bootx64.efi FS1:\EFI\Microsoft\Boot\bootmgfw.efi

After reboot, any entries added to NVRAM should show up in the boot menu.

## Acknowledgement

This wiki article is based on ArchWiki. We may have removed non-FSDG bits from it.
Category:

- Software