Unified Extensible Firmware Interface

The Unified Extensible Firmware Interface (UEFI or EFI for short) is a model for the interface between operating systems and firmware. It provides a standard environment for booting an operating system and running pre-boot applications.

Related articles

It is distinct from the "MBR boot code" method that was used by legacy BIOS systems. See Arch boot process for their differences and the boot process using UEFI. To set up UEFI boot loaders, see Arch boot process#Boot loader.

Note: Early vendor UEFI implementations may carry more bugs than their BIOS counterparts. Consider using legacy BIOS booting for such systems if you encounter unsolvable issues.

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.
  • 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.

The latest UEFI specification can be found at https://uefi.org/specifications.

UEFI firmware bitness

Under UEFI, every program whether it is an OS loader or a utility (e.g. a memory testing or recovery tool), should be a EFI application corresponding to the UEFI firmware bitness/architecture.

The vast majority of UEFI firmwares, including recent Apple Macs, use x86_64 UEFI firmware. The only known devices that use IA32 (32-bit) UEFI are older (pre 2008) Apple Macs, Intel Atom System-on-Chip systems (as on 2 November 2013) and some older Intel server boards that are known to operate on Intel EFI 1.10 firmware.

An x86_64 UEFI firmware does not include support for launching 32-bit EFI applications (unlike x86_64 Linux and Windows versions which include such support). Therefore the EFI application must be compiled for that specific firmware processor bitness/architecture.

Note: Systems with IA32 UEFI require using a boot loader that supports mixed mode booting. For example, GRUB when installed with the i386-efi target.

Checking the firmware bitness

The firmware bitness can be checked from a booted operating system.

From Linux

On distributions running Linux kernel 4.0 or newer, the UEFI firmware bitness can be found via the sysfs interface. Run:

$ cat /sys/firmware/efi/fw_platform_size

It will return 64 for a 64-bit (x86_64) UEFI or for a 32-bit (IA32) UEFI. If the file does not exist, then you have not booted in UEFI mode.

From macOS

Pre-2008 Macs mostly have IA32 EFI firmware while >=2008 Macs have mostly x86_64 EFI. All Macs capable of running Mac OS X Snow Leopard 64-bit Kernel have x86_64 EFI 1.x firmware.

To find out the arch of the EFI firmware in a Mac, type the following into the Mac OS X terminal:

$ ioreg -l -p IODeviceTree | grep firmware-abi

If the command returns then it is IA32 (32-bit) EFI firmware. If it returns then it is x86_64 EFI firmware. Most of the Macs do not have UEFI 2.x firmware as Apple's EFI implementation is not fully compliant with UEFI 2.x specification.

From Microsoft Windows

64-bit versions of Windows do not support booting on a 32-bit UEFI. So, if you have a 32-bit version of Windows booted in UEFI mode, you have a 32-bit UEFI.

To check the bitness run . In the System Summary section look at the values of "System Type" and "BIOS mode".

For a 64-bit Windows on a 64-bit UEFI it will be and BIOS mode: UEFI, for a 32-bit Windows on a 32-bit UEFI - System Type: x86-based PC and BIOS mode: UEFI. If the "BIOS mode" is not , then Windows is not booted in UEFI mode.

Linux kernel configuration options for UEFI

The required Linux Kernel configuration options for UEFI systems are:

CONFIG_RELOCATABLE=y
CONFIG_EFI=y
CONFIG_EFI_STUB=y
CONFIG_X86_SYSFB=y
CONFIG_FB_SIMPLE=y
CONFIG_FRAMEBUFFER_CONSOLE=y

UEFI Runtime Variables Support (efivarfs filesystem - ). This option is important as this is required to manipulate UEFI runtime variables using tools like efibootmgr. The configuration option below has been added in kernel 3.10 and later.

CONFIG_EFIVAR_FS=y

UEFI Runtime Variables Support (old efivars sysfs interface - ). 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) configuration option - mandatory for UEFI support

CONFIG_EFI_PARTITION=y

EFI mixed-mode support - to boot a x86_64 kernel on a IA32 UEFI.

CONFIG_EFI_MIXED=y

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 --list

UEFI variables support in Linux kernel

Linux kernel exposes UEFI variables data to userspace via efivarfs (EFI VARiable FileSystem) interface () - mounted using kernel module at - 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. Kernel should be booted in UEFI mode via EFISTUB (optionally using a boot manager) or by a UEFI boot loader, not via BIOS or CSM, or Apple's Boot Camp which is also a CSM.
  2. EFI Runtime Services support should be present in the kernel (CONFIG_EFI=y, check if present with ).
  3. EFI Runtime Services in the kernel SHOULD NOT be disabled via the kernel command line, i.e. kernel parameter SHOULD NOT be used.
  4. filesystem should be mounted at , otherwise follow #Mount efivarfs section below.
  5. efivar should list (option /) the UEFI variables without any error.

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

  1. If listing of the UEFI variables () leads to and the system is booted into a realtime kernel, add to the kernel parameters and reboot (efivarfs functionality is disabled by default on those kernels).
  2. See #Userspace tools are unable to modify UEFI variable data for more troubleshooting steps

Mount efivarfs

If is not automatically mounted at by systemd during boot, then you need to manually mount it to expose UEFI variables to userspace tools like efibootmgr:

# mount -t efivarfs efivarfs /sys/firmware/efi/efivars
Note: The above command should be run both outside (i.e. before) and inside the chroot, if any.

See efivarfs.html for kernel documentation.

Userspace tools

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

  • efitools — Tools for manipulating UEFI secure boot platforms
https://git.kernel.org/pub/scm/linux/kernel/git/jejb/efitools.git || efitools

    efibootmgr

    You will have to install the package.

    To add a new boot option using efibootmgr, you need to know three things:

    1. The disk containing the EFI system partition (ESP). E.g.: /dev/sda, .
    2. The partition number of the ESP on that disk. The in or .
    3. The path to the EFI application (relative to the root of the ESP)

    For example, if you want to add a boot option for where /efi is the mount point of the ESP, run

    In this example, this indicates that the ESP is on disk /dev/sda and has partition number 1. The path to the EFI application relative to the root of the ESP is . So you would create the boot entry as follows:

    # efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd Boot Manager" --unicode
    # efibootmgr --create --disk /dev/nvme0n1p1 --loader /EFI/refind/refind_x64.efi --label "rEFInd Boot Manager" --unicode

    See or efibootmgr README for more info.

    Note: UEFI uses backward slash \ as path separator but efibootmgr automatically converts UNIX-style / path separators.

    Disable UEFI variable access

    Access to the UEFI can potentially cause harm beyond the running OS level. Even hardware-level bricking is possible in some cases of poor UEFI implementation.

    So, as the UEFI variables access is not required for daily system usage, you may want to disable it, to avoid potential security breaches or accidental harm.

    Possible solutions are:

    • Mount in read-only mode using fstab. For example:
    • Use the kernel parameter to completely disable OS access to UEFI.

    UEFI Shell

    The UEFI Shell is a shell/terminal for the firmware which allows launching EFI 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 obtain a BSD licensed UEFI Shell from the TianoCore EDK2 project:

    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 information at ShellPkg and the EDK2 mailing list thread—Inclusion of UEFI shell in Linux distro iso.

    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, copy the x86_64 UEFI Shell to the root of your EFI system partition, named as .

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

    Important UEFI Shell commands

    UEFI Shell commands usually support option which makes output pause after each page. Run help -b to list available internal commands. Available commands are either built into the shell or discrete EFI applications.

    For more info see Intel Scripting Guide 2008 and Intel "Course" 2011.

    bcfg

     
    modifies the UEFI NVRAM entries which allows the user to change the boot entries or driver options. This command is described in detail in page 96 (Section 5.3) of the UEFI Shell Specification 2.2 document.

    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 Boot Manager"

    where is the mapping corresponding to the EFI system partition and is the file to be launched.

    To add an entry to boot directly into your system without a bootloader, configure a boot option using your kernel as an EFISTUB:

    Shell> bcfg boot add N fsV:\vmlinuz-linux "Arch Linux"
Shell> bcfg boot -opt N "root=/dev/sdX# initrd=\initramfs-linux.img"

    where is the priority, is the volume number of your EFI system partition, and /dev/sdX# is your root partition.

    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

    map

     
    displays a list of device mappings i.e. the names of available file systems () and storage devices ().

    Before running file system commands such as or ls, you need to change the shell to the appropriate file system by typing its name:

    Shell> FS0:
FS0:\> cd EFI/

    edit

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

    For example, to edit rEFInd's in the EFI system partition ( in the firmware),

    Shell> edit FS0:\EFI\refind\refind.conf

    Press for help.

    UEFI drivers

    UEFI drivers are pieces of software that support some functionality. For example, access to NTFS formatted partitions is usually not possible from a UEFI shell. The package has drivers that support reading many more file systems from within an EFI shell. A usage example is to copy such driver to a partition that can be accessed from an UEFI shell. Then, from the UEFI shell, issuing commands such as:

    Shell> load ntfs_x64.efi
Shell> map -r

    After the map command has been executed, the user should be able to access NTFS formatted partitions from within a UEFI shell.

    UEFI bootable media

    Create UEFI bootable USB from ISO

    Follow USB flash installation medium#Using the ISO as is (BIOS and UEFI).

    Remove UEFI boot support from optical media

    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.

    Extract the ISO skipping the UEFI-specific directories:

    $ mkdir extracted_iso
$ bsdtar -x --exclude=EFI/ --exclude=loader/ -f archlinux-version-x86_64.iso -C extracted_iso

    Then rebuild the ISO, excluding the UEFI optical media booting support, using xorriso(1) from . Be sure to set the correct volume label, e.g. ; it can be acquired using on the original ISO.

    $ xorriso -as mkisofs \
    -iso-level 3 \
    -full-iso9660-filenames \
    -joliet \
    -joliet-long \
    -rational-rock \
    -volid "ARCH_''YYYYMM''" \
    -appid "Arch Linux Live/Rescue CD" \
    -publisher "Arch Linux <https://archlinux.org>" \
    -preparer "prepared by $USER" \
    -eltorito-boot syslinux/isolinux.bin \
    -eltorito-catalog syslinux/boot.cat \
    -no-emul-boot -boot-load-size 4 -boot-info-table \
    -isohybrid-mbr "extracted_iso/syslinux/isohdpfx.bin" \
    -output archlinux-''version''-x86_64-noUEFI.iso extracted_iso/

    Burn 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 and a separate non-volatile variable store for QEMU.

    You can install from the extra repository.

    It is advised to make a local copy of the non-volatile variable store for your virtual machine:

    $ cp /usr/share/edk2-ovmf/x64/OVMF_VARS.fd my_uefi_vars.fd

    To use the OVMF firmware and this variable store, add following to your QEMU command:

    -drive if=pflash,format=raw,readonly,file=/usr/share/edk2-ovmf/x64/OVMF_CODE.fd \
-drive if=pflash,format=raw,file=my_uefi_vars.fd

    For example:

    $ qemu-system-x86_64 -enable-kvm -m 1G -drive if=pflash,format=raw,readonly,file=/usr/share/edk2-ovmf/x64/OVMF_CODE.fd -drive if=pflash,format=raw,file=my_uefi_vars.fd …

    DUET for BIOS only systems

    DUET was a TianoCore project that enabled chainloading a full UEFI environment from a BIOS system, in a way similar to BIOS OS booting. This method is being discussed extensively in https://www.insanelymac.com/forum/topic/186440-linux-and-windows-uefi-boot-using-tianocore-duet-firmware/. Pre-build DUET images can be downloaded from one of the repos at https://gitlab.com/tianocore_uefi_duet_builds/tianocore_uefi_duet_installer. Specific instructions for setting up DUET is available at https://gitlab.com/tianocore_uefi_duet_builds/tianocore_uefi_duet_installer/blob/master/Migle_BootDuet_INSTALL.txt . However, as of November 2018, the DUET code has been removed from TianoCore git repository.

    You can also try https://sourceforge.net/projects/cloverefiboot/ which provides modified DUET images that may contain some system specific fixes and is more frequently updated compared to the gitlab repos.

    Troubleshooting

    Boot back to Arch Linux when stuck with Windows

    To boot back into Arch Linux when you are stuck with Windows, reach Advanced startup in Windows by the Windows PowerShell command , or via Settings > Update & Security > Recovery > Advanced startup and select Restart now. When you have reached the Advanced startup menu, choose Use a device, which actually contains your UEFI boot options (not limited to USB or CD, but can also boot operating system in hard drive), and choose "Arch Linux".

    Enter firmware setup without function keys

    On some laptops, like Lenovo XiaoXin 15are 2020, using keys like or does not do anything. This can possibly be fixed by returning laptops to OEM to repair mainboard information, but sometimes this is not possible or not desired. There are however other means to enter firmware setup:

    Userspace tools are unable to modify UEFI variable data

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

    Cannot create a new boot entry with efibootmgr

    Some kernel and efibootmgr version combinations might refuse to create new boot entries. This could be due to lack of free space in the NVRAM. You can try the solution at #Userspace tools are unable to modify UEFI variable data.

    You can also try to downgrade your efibootmgr install to version 0.11.0. This version works with Linux version 4.0.6. See the bug discussion FS#34641, in particular the closing comment, for more information.

    Windows 7 will not boot in UEFI mode

    If you have installed Windows to a different hard disk with GPT partitioning and still have a MBR partitioned hard disk in your computer, then it is possible that the firmware (UEFI) is starting its CSM support (for booting MBR partitions) and therefore Windows will not boot. To solve this, merge your MBR hard disk to GPT partitioning or disable the SATA port where the MBR hard disk is plugged in or unplug the SATA connector from this hard disk.

    Mainboards with this kind of problem:

    • Gigabyte Z77X-UD3H rev. 1.1 (UEFI version F19e)
      • The firmware option for booting "UEFI Only" does not prevent the firmware from starting CSM.

    Windows changes boot order

    If you dual boot with Windows and your motherboard just boots Windows immediately instead of your chosen EFI application, there are several possible causes and workarounds.

    • Ensure Fast Startup is disabled in your Windows power options
    • Ensure Secure Boot is disabled in your firmware (if you are not using a signed boot loader)
    • Ensure your UEFI boot order does not have Windows Boot Manager set first e.g. using efibootmgr and what you see in the configuration tool of the UEFI. Some motherboards override by default any settings set with efibootmgr by Windows if it detects it. This is confirmed in a Packard Bell laptop.
    • If your motherboard is booting the default boot path (), this file may have been overwritten with the Windows boot loader. Try setting the correct boot path e.g. using efibootmgr.
    • If the previous steps do not work, you can tell the Windows boot loader to run a different EFI application. From a Windows administrator command prompt
    • Alternatively, deactivate the Windows Boot Manager by running as root. Replace with the actual Windows Boot Manager boot number; you can see it by running efibootmgr with no options.
    • Alternatively, you can set a startup script in Windows that ensures that the boot order is set correctly every time you boot Windows.
      1. Open a command prompt with administrator privileges. Run and find your desired boot entry.
      2. Copy the identifier, including the brackets, e.g.
      3. Create a batch file with the command
      4. Open gpedit.msc and under Local Computer Policy > Computer Configuration > Windows Settings > Scripts (Startup/Shutdown), choose Startup
      5. Under the Scripts tab, choose the Add button, and select your batch file
    Note: Windows 10 Home does not officially include gpedit.msc, although there are unsupported workarounds to install it manually.
    • Alternatively, Task Scheduler can be used to run a startup script in Windows:
      1. Follow steps 1-3 above to create the batch file.
      2. Run taskschd.msc, then choose Create Task... from the Action menu.
      3. On the General tab:
        Enter any suitable Name and Description.
        Ensure the user account selected is an "Administrator", not a "Standard User".
        Select "Run whether user is logged in or not".
        Select "Run with highest privileges".
      4. On the Triggers tab, choose "At startup" from the menu, then click OK.
      5. On the Actions tab, click New..., then Browse..., and locate the batch file from step 1.
      6. On the Conditions tab, untick the Power options so the script runs when on battery power (for laptops).
      7. Click OK, and enter the password of the user account selected in step 4 when prompted.

    USB media gets struck with black screen

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

    UEFI boot loader does not show up in firmware menu

    Some firmware do not support custom boot entries. They will instead only boot from hardcoded boot entries.

    A typical workaround is to not rely on boot entries in the NVRAM and install the boot loader to one of the common fallback paths on the EFI system partition.

    The following sections describe the fallback paths.

    Default boot path for removable drives

    The UEFI specification defines default file paths for EFI binaries for booting from removable media. The relevant ones are:

    • for x86_64 UEFI
    • for IA32 UEFI.

    While the specification defines these for removable drives only, most firmware support booting these from any drive.

    See the appropriate boot loader article on how to install or migrate the boot loader to the default/fallback boot path.

    Microsoft Windows boot loader location

    On certain UEFI motherboards like some boards with an Intel Z77 chipset, adding entries with efibootmgr or from the UEFI 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 file from the Arch Linux installation medium () to the Microsoft directory your ESP partition on your hard drive (FS1:). Do this by booting into EFI shell and typing:

    Shell> mkdir FS1:\EFI\Microsoft
Shell> mkdir FS1:\EFI\Microsoft\Boot
Shell> 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.

    Boot entries created with efibootmgr fail to show up in UEFI

    efibootmgr can fail to detect EDD 3.0 and as a result create unusable boot entries in NVRAM. See efibootmgr issue 86 for the details.

    To work around this, when creating boot entries manually, add the option to the efibootmgr command. E.g.

    # efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd Boot Manager" --unicode -e 3

    To fix boot loader installers, like and refind-install, create a wrapper script and make it executable:

    UEFI boot entry disappears after removing its referenced drive

    Some firmware will remove boot entries referencing drives that are not present during boot. This could be an issue when frequently detaching/attaching drives or when booting from a removable drive.

    The solution is to install the boot loader to the default/fallback boot path.

    gollark: What?
    gollark: Several thousand GPUs, for purposes.
    gollark: Secret conspiracy running the US government, get on it.
    gollark: It would be HIGHLY humorous if there was an exact tie in the next US election.
    gollark: Besides this, we let people take on the difficult and important job of parenting with literally no training.

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