UEFI [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Unified Extensible Firmware Interface (UEFI) =====

===== Introduction =====

%%FreeBSD%% can boot using UEFI on the amd64 and arm64 platforms since %%FreeBSD%% 10.1 ([[http://svnweb.freebsd.org/base?view=revision&revision=264095|r264095]]). More information is available in [[https://man.freebsd.org/cgi/man.cgi?query=uefi|uefi(8)]]. Like loader(8), the UEFI loader //loader.efi// supports booting from GPT UFS and ZFS filesystems and supports GELI in the loader.

===== 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 [[https://www.kraxel.org/repos/jenkins/edk2/|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:

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

Alternatively, to test UEFI CD support:

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

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

===== Real Hardware Gotchas =====

These are some issues that benno@ ran into when using real hardware (ie, not qemu) in early development:

  * Filesystem not seen. %%FreeBSD%%'s FAT32 code appears to sometimes create filesystems that the UEFI code can't properly read. If the filesystem is small enough, use FAT16 or FAT12 instead. Please [[https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Base System|submit a PR]] with details if you are able to reproduce this.

===== 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:

<code>
gpart create -s gpt da0
gpart add -t efi -s 40M da0
gpart add -t freebsd-ufs da0
newfs_msdos -F 32 -c 1 /dev/da0p1
mount -t msdosfs /dev/da0p1 /mnt
mkdir -p /mnt/EFI/BOOT
cp /boot/loader.efi /mnt/EFI/BOOT/BOOTX64.efi
umount /mnt
newfs -U -L FreeBSD /dev/da0p2
</code>

Perform the install to the UFS partition, as usual:

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

**TODO:** Use a label for the root fs instead

Create etc/fstab.

<code>
umount /mnt                                                                     
</code>

===== 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 [[http://fedoraproject.org/wiki/User:Pjones/BootableCDsForBIOSAndUEFI|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:

<code>
> mkdir -p efiroot/EFI/BOOT
> cp loader.efi efiroot/EFI/BOOT/BOOTX64.efi
> makefs -t msdos -s 40m -o fat_type=32,sectors_per_cluster=1,media_descriptor=248 efiboot.img efiroot
</code>

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.

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

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:

<code>
> 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
</code>

===== Bootable Image from NanoBSD =====

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

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

===== Secure Boot =====

See the [[SecureBoot]] page.

===== Tasks =====

| Create the ESP as a 40MB FAT32 filesystem to maximize compatibility | Done |
| Improve diagnostics when something goes wrong (e.g. can't allocate memory in early loader stage | Started by bcran@ |
| Verify API usage to maximize compatibility (e.g. corner cases around %%GetMemoryMap%% calls) | Started by bcran@ |
| Build 32-bit EFI loader and install as /BOOT/EFI/BOOTIA32.efi | Not Started |
| Support booting 64-bit %%FreeBSD%% on a 64-bit CPU from a 32-bit EFI environment | Not Started |
| Support side-by-side installation with other OSes: e.g. installing loader as /EFI/%%FreeBSD%%/BOOTX64.efi | Done |
| **Filesystem / partition support**  |
| Next-stage partition selection | Not Started |

===== Related Links =====
  * http://wiki.osdev.org/UEFI
  * ''%%http://straightedgelinux.com/blog/howto/efi.html%%'' (link is broken)
  * http://software.intel.com/en-us/articles/efi-shells-and-scripting
  * http://en.wikipedia.org/wiki/EFI_System_partition
  * http://www.uefi.org/registry
  * http://blog.ignoranthack.me/?p=147
  * Beyond BIOS - 2nd Edition book (''%%http://click.intel.com/beyond-bios-2nd-edition.html%%'' | link is broken)
  * [[https://www.happyassassin.net/2014/01/25/uefi-boot-how-does-that-actually-work-then/|UEFI boot: how does that actually work, then?]]
  * https://glenbarber.us/2014/08/02/FreeBSD-Pure-ZFS-and-GELI-migration-to-UEFI.html
  * http://ximalas.info/2015/03/19/uefi-gpt-windows-10-freebsd-10-and-refind/
  * https://www.freebsdfoundation.org/project/uefi-boot-integration/

===== Test Results =====
The amd64 UEFI loader has successfully booted on the following devices:
  * QEMU with ''%%OVMF-X64-r11337-alpha.zip%%'' firmware
  * QEMU 2.0.0 with ''%%OVMF-X64-r15214.zip%%'' firmware
  * Intel DQ77MK with UEFI v2.31 development kit firmware Revision 1.02
  * Lenovo Thinkpad X220 with UEFI firmware 1.31
  * Lenovo Thinkpad X1 Carbon
  * Lenovo Thinkpad T530 - UEFI BIOS Version 2.04, EFI Version 2.31, EFI Firmware: Lenovo (rev 0.8256). Notes: Force Intel (Integrated) GPU, disable CSM
  * ASUS UX51VZ
  * Fujitsu Lifebook E743
  * Gigabyte H61M-DS2H
  * Gigabyte 6PXSV4
  * 2014 %%MacBook%% Air (6,2)
  * %%MacBook%% Pro 15" early 2011 i7 (''%%https://gist.github.com/dch/22c28211c539a6d612a4%%'' | link is broken.) - requires booting from using CD during install
  * "Early 2008" Mac Pro (%%MacPro%% 3,1) with a %%GeForce%% 8800 GT video card - fixed since r287422, more details in [[https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=202730|PR 202730]]
  * [[http://www.gigabyte.com/products/product-page.aspx?pid=4601|Gigabyte H87N-WiFi]]
  * HP Probook 430 G1 (loader works both w/ and w/o CSM mode, but the later has issues with console [[https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=202309|PR 202309]])
  * Dell R710 (see [[https://reviews.freebsd.org/D1417]])
  * VirtualBox EFI (fixed by [[https://bugs.freebsd.org/193672|PR 193672]])
  * Toshiba satellite C55-A-1NK (fixed by [[https://svnweb.freebsd.org/changeset/base/292515|r292515]])
  * VMware ESXi 5.5 (head after [[https://svnweb.freebsd.org/changeset/base/277735|r277735]], stable/10 after [[https://svnweb.freebsd.org/changeset/base/292551|r292551]])

It is presumed fixed on the following devices:
  * ASUS %%P8B75%%-M/CSM [[https://bugs.freebsd.org/193646|PR 193646]]
  * Hyper-V with Generation 2 configurations. [Booted, but need %%HyperV%% keyboard driver]

If you encounter an issue with UEFI boot on a %%FreeBSD%%-CURRENT or stable/10 snapshot after r292551 please [[https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Base System|submit a PR]] with details. For UEFI issues on %%FreeBSD%% 10.2-release or earlier please send an email with details to the [[https://lists.freebsd.org/mailman/listinfo/freebsd-stable|freebsd-stable]] mailing list.

===== Known Issues =====

  * moused causes kernel panics Please [[https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Base System|submit a PR]] with details if you are able to reproduce this.

Search for PRs tagged with the [[https://bugs.freebsd.org/bugzilla/buglist.cgi?keywords=uefi&list_id=23406&resolution=---|UEFI keyword]].

----

{{tag>Project}}