This page is dedicated to The FreeBSD Foundation-sponsored project to support booting FreeBSD under UEFI. The project is complete and basic UEFI boot support is available in FreeBSD 10.1 and later; this page exists as a snapshot of the development process and to track some remaining enhancements.


This project allows FreeBSD to boot under UEFI on the amd64 and arm64 platforms. This primarily involves adding code to build a version of loader that can run as an EFI application and removing any dependencies on BIOS presence and patterns from the kernel. Additional work will be done to add the ability to create UEFI-bootable CD/DVD images. Lastly, some groundwork will be done to permit further work to allow FreeBSD to boot with UEFI Secure Boot enabled.

Support for loading and booting i386 kernels was removed from the initial infrastructure project as the preponderance of systems that require UEFI support will be 64-bit. i386 support will be reimplemented at a later time.

Boot Process

The UEFI boot process uses an EFI System Partition (ESP) to store system bootstrap components. The ESP is a GPT or MBR partition with a specific identifier, and contains a FAT file system with a specified hierarchy.

Partition Scheme






The boot process proceeds as follows:

  1. UEFI firmware runs at power up and searches for an OS loader in the EFI system partition. The path to the loader may be set by an EFI environment variable, with a default of /EFI/BOOT/BOOTX64.EFI.

    • For FreeBSD, boot1.efi is installed as /EFI/BOOT/BOOTX64.EFI.

    • boot1.efifat is an image of such a FAT filesystem for use by bsdinstall
  2. boot1.efi locates the first partition with a type of freebsd-ufs, and from it loads loader.efi. (This may be a different disk than the one holding the EFI system partition.)
  3. loader.efi loads and boots the kernel, as described in loader(8).


The code was merged to FreeBSD-HEAD in r264095. Development was originally done in the projects/uefi branch of the Subversion repository.

Virtualised Development Environment

If you wish to test this code under a virtual environment, UEFI firmware images are available for qemu. Assuming you have a version of qemu greater than 0.9.1, you can download the OVMF images from here. Download the ovmf-x64 rpm file and unpack it with tar xf <ovmf x64 file>.rpm. You'll probably want to copy usr/share/edk2.git/ovmf-x64/OVMF-pure-efi.fd somewhere more convenient then remove the rest of the extracted files and directories. To test the code I run:

> qemu-system-x86_64 -m 1024 -serial stdio -bios OVMF-pure-efi.fd -hda fat:<path to boot directory>

Alternatively, to test UEFI CD support:

> qemu-system-x86_64 -m 1024 -serial stdio -bios OVMF-pure-efi.fd -cdrom <path to ISO image>

The boot directory contains my built loader.efi as well as any kernel I want to boot.

Real Hardware Gotchas

These are some issues I have run into when using real hardware (ie, not qemu).

Bootable UEFI memory stick or Hard Disk

To test UEFI booting on a memory stick or a hard disk, create a GPT partition table with a small EFI partition and the rest of the space dedicated to a FreeBSD UFS partition:

gpart create -s gpt da0
gpart add -t efi -s 800K da0
gpart add -t freebsd-ufs da0
dd if=/boot/boot1.efifat of=/dev/da0p1
newfs -U -L FreeBSD /dev/da0p2

Perform the install to the UFS partition, as usual:

mount /dev/da0p2 /mnt
make DESTDIR=/mnt installkernel installworld distribution
echo "/dev/da0p2 / ufs rw 1 1" >> /mnt/etc/fstab
umount /mnt

TODO: Use a label for the root fs instead

Create etc/fstab.

umount /mnt                                                                     

CD/DVD Boot under UEFI

The approach for creating a bootable CD/DVD image for UEFI is to create a FAT filesystem image containing your loader code as it would be laid out in an EFI System Partition. This image is then attached to the CD/DVD image as a non-emulation El Torito boot image. To make an image that is bootable under both legacy BIOS and UEFI, the BIOS image is placed first and the UEFI image is placed as an alternate. More information can be found here.

A sample boot ISO can be created using the following steps.

Create a FAT filesystem image and place our loader in it in the default path that UEFI will look for:

> dd if=/dev/zero of=efiboot.img bs=4k count=100
> mdconfig -a -t vnode -f efiboot.img
> newfs_msdos -F 12 -m 0xf8 /dev/md0
> mount -t msdosfs /dev/md0 /mnt
> mkdir -p /mnt/efi/boot
> cp loader.efi /mnt/efi/boot/bootx64.efi
> umount /mnt
> mdconfig -d -u 0

We now have our UEFI boot image. The next step is to make the ISO image. We assume that you have a directory called image containing the file structure you want in your ISO.

> makefs -t cd9660 -o bootimage='i386;efiboot.img' -o no-emul-boot -o rockridge -o label="UEFItest" -o publisher="test" uefi-test.iso image

You should now have an ISO image in uefitest.iso that will boot using UEFI.

The version that is built for FreeBSD 11 snapshots by the release scripts has multiple boot images attached in order to support BIOS and UEFI. You can do something similar by the following:

> makefs -t cd9660 -o 'bootimage=i386;efiboot.img' -o no-emul-boot -o 'bootimage=i386;/boot/cdboot' -o no-emul-boot -o rockridge -o label="UEFItest" -o publisher="test" uefi-test.iso image

Bootable Image from NanoBSD

> cd $TOP/tools/tools/nanobsd/embedded
> sh ../nanobsd.sh -c qemu-amd64-uefi.cfg

The bootable image will be in $TOP/../qemu-amd64-uefi/obj/_.disk.image.qemu-amd64-uefi.qcow2 that you can feed to qmeu, as described in the Virtualized Development Environment section above. You can also put it on a USB stick.

Secure Boot

See the SecureBoot page.


The vt(4) (aka Newcons) console is enabled automatically when booting via UEFI. Serial console appears to work fine under QEMU.


64-bit UEFI loader

Make libstand build natively as 64-bit on amd64.


Adjust non-EFI boot code to use /usr/lib32/libstand.a.


Add bits to build 64-bit loader.efi.


Make sure that loader.efi can actually load a kernel and hand off to it.


Pass ACPI table information to kernel via hints.


Clean up loader.efi to propery exit UEFI.


Clean up loader.efi to allocate memory properly.


Test that the other boot code still actually works.


Boot amd64 kernel

Work out how to pass the memory map from EFI to the kernel.


Work out why syscons isn't working.


Write an EFI framebuffer driver.


Integrate EFI framebuffer with vt(9).


Work out why kernel hand-off doesn't work work on systems with >1GB of RAM.


UEFI-compatible install media

Work out how exactly CD/DVD boot under UEFI works.


Create a UEFI boot image and attach it to an ISO image.


Allow loader to see CD filesystem once booted from CD.


Glue UEFI boot logic into the distribution build.


UEFI support in installer


Filesystem / partition support

Root on ZFS


Next-stage partition selection


Integration into FreeBSD HEAD

Make libstand build natively as 64-bit on amd64.


Adjust non-EFI boot code to use 32-bit libstand.a.


Build 64-bit loader.efi


Kernel parses memory map created by loader

Complete (r263822)

Outstanding tasks were discussed at the BSDCan DevSummit.

Test Results

The amd64 UEFI loader has successfully booted on the following devices:

It is presumed fixed on the following devices:

If you encounter an issue with UEFI boot on a FreeBSD-CURRENT or stable/10 snapshot after r292551 please submit a PR with details. For UEFI issues on FreeBSD 10.2-release or earlier please send an email with details to the freebsd-stable mailing list.

Known Issues

Search for PRs tagged with the UEFI keyword.

UEFI (last edited 2018-04-16 19:57:00 by RebeccaCran)