LOADER.EFI(8)

💅 LOADER.EFI(8) 💅

okay so bestie, welcome to loader.efi(8) — the System Manager's Manual page for the UEFI kernel loader. buckle up, this one's a whole journey 🎀

---

✨ NAME ✨

loader.efi — UEFI kernel loader 🦋

---

🌸 DESCRIPTION 🌸

so on UEFI systems, loader.efi loads the kernel. that's the whole vibe. main character energy fr fr 👑

loader.efi gets invoked directly from the EFI System Partition (ESP) on systems that were installed using bsdinstall(8) — like, when it's installed as the default EFI boot program as described in uefi(8), or when you set it up as an EFI boot entry with efibootmgr(8). slay 💅

now, on systems that were upgraded from FreeBSD 10 or earlier, the ESP can literally be too small to fit loader.efi in it 😭. in those cases, boot1.efi(8) may be kept around as the firmware boot program. it'll chain-load the current /boot/loader.efi, which gets updated during the installworld process. ngl, boot1.efi(8) is deprecated for new installations — it's giving legacy, not giving fresh.

🖥️ Console Considerations 🖥️

the UEFI firmware gives you a generic console. in loader.efi you select it by setting the console variable to “efi”. then loader.efi goes snooping through the 8be4df61-93ca-11d2-aa0d-00e098032b8c-ConOut UEFI environment variable to figure out what the “efi” console is actually pointing at 👀.

loader.efi will output its prompts and menus to all the places specified by ConOut. but here's the catch, bestie — the FreeBSD kernel has a limitation when more than one console is present. the kernel outputs to all configured consoles, but only the primary console gets the log messages from the rc(8) system, and prompts for things like geli(8) passwords. 🫶

so: if loader.efi finds a video device first, then it tells the kernel to use the video console as primary. likewise, if a serial device is first in the ConOut list, the serial port becomes the primary console. it's giving "first come, first served" honestly.

if there's no ConOut variable, then both serial and video get attempted. loader.efi uses the “efi” console for the video (which may or may not work, no promises 💀) and “comconsole” for the serial on COM1 at the default baud rate. the kernel will use a dual console, with the video console primary if a UEFI graphics device is detected, or the serial console as primary if not.

on x86 platforms, if you wish to redirect the loader's output to a serial port when the UEFI firmware doesn't support it, or to a serial port that isn't the one the UEFI firmware redirects its output to — set console to “comconsole”. the default port is COM1 with an I/O address of 0x3f8. comconsole_port is used to set this to a different port address. comconsole_speed is used to set the speed of the serial port (the default is 9600). if you have console set to “efi,comconsole” you'll get output on both the EFI console and the serial port. and if that causes a doubling of characters, set console to “efi”, since your UEFI firmware is already redirecting to the serial port. love that for you 💖

if your UEFI firmware redirects the serial port, you may need to tell the kernel which address to use. EFI uses ACPI's UID to identify the serial port, but loader.efi doesn't have an ACPI parser, so it literally cannot convert that to an I/O port 😭. the FreeBSD kernel initializes its consoles before it can decode ACPI resources. the FreeBSD kernel will look at the hw.uart.console variable to set its serial console. its format should be described in uart(4) but is not (rude). set it to “io:0x3f8,br:115200” with the proper port address. PCI or memory mapped ports are beyond the scope of this man page, so don't come for me.

the serial ports are assigned as follows on IBM PC compatible systems:

• COM1 — I/O port address 0x3f8 — typical FreeBSD device /dev/uart0
• COM2 — I/O port address 0x2f8 — typical FreeBSD device /dev/uart1
• COM3 — I/O port address 0x3e8 — typical FreeBSD device /dev/uart2
• COM4 — I/O port address 0x2e8 — typical FreeBSD device /dev/uart3

though COM3 and COM4 can vary. iconic behavior honestly.

👑 Primary Console 👑

the primary console is set using the boot flags. these command line arguments set corresponding flags for the kernel, and you can control them by setting loader environment variables to “yes” or “no”. boot flags may be set on the command line to the boot command. inside the kernel, the RB_ flags are used to control behavior, sometimes in architecturally specific ways, and they're included here to aid in discovery of any behavior not covered in this document. iykyk 🌈

here's the whole lineup, one per flag:

• -a — loader variable boot_askme, kernel RB_ASKNAME
• -c — loader variable boot_cdrom, kernel RB_CDROM
• -d — loader variable boot_ddb, kernel RB_KDB
• -r — loader variable boot_dfltroot, kernel RB_DFLTROOT
• -D — loader variable boot_multiple, kernel RB_MULTIPLE
• -m — loader variable boot_mute, kernel RB_MUTE
• -g — loader variable boot_gdb, kernel RB_GDB
• -h — loader variable boot_serial, kernel RB_SERIAL
• -p — loader variable boot_pause, kernel RB_PAUSE
• -P — loader variable boot_probe, kernel RB_PROBE
• -s — loader variable boot_single, kernel RB_SINGLE
• -v — loader variable boot_verbose, kernel RB_VERBOSE

and the following flags determine the primary console:

• no flags — kernel flags 0 — kernel consoles Video — primary console Video
• -h — kernel flags RB_SERIAL — kernel consoles Serial — primary console Serial
• -D — kernel flags RB_MULTIPLE — kernel consoles Serial, Video — primary console Video
• -Dh — kernel flags RB_SERIAL | RB_MULTIPLE — kernel consoles Serial, Video — primary console Serial

one important thing though: loader.efi does not implement the probe -P functionality where we use the video console if a keyboard is connected and a serial console otherwise. so don't expect it, bestie. 🙈

🌿 Additional Environment Variables 🌿

loader.efi loads some extra variables early in startup from /efi/freebsd/loader.env from the EFI partition. only simple variables can be set here. it can be useful to specify the root filesystem, like this:

rootdev=disk0s1a

🍓 Staging Slop 🍓

the kernel has to parse the firmware memory map tables to know what memory it can actually use. since it must allocate memory to do this, loader.efi makes sure there's extra memory available — called “slop” — after everything it loads (the kernel, modules and metadata) so the kernel can bootstrap the memory allocator. cute lil cushion 💅

by default, amd64 reserves 8MB. the staging_slop command allows for tuning the slop size. it takes a single argument: the size of the slop in bytes.

🦋 amd64 Nocopy 🦋

loader.efi will load the kernel into memory that is 2MB aligned below 4GB. it cannot load to a fixed address because the UEFI firmware may reserve arbitrary memory for its use at runtime. prior to FreeBSD 13.1, kernels retained the old BIOS-boot protocol of loading at exactly 2MB. those kernels must be copied from their loaded location to 2MB prior to starting them up. the copy_staging command is used to enable this copying for older kernels. it takes a single argument, which can be one of:

• disable — force-disable copying staging area to 2M.
• enable — force-enable copying staging area to 2M.
• auto — selects the behaviour based on the kernel's capability of boostraping from non-2M physical base. the kernel reports this capability by exporting the symbol kernphys.

Arm64 loaders have operated in the 'nocopy' mode from their inception, so there's no copy_staging command on that platform. Riscv, 32-bit arm and arm64 have always loaded at any 2MB aligned location, so they do not provide copy_staging either.

Note. BIOS loaders on i386 and amd64 put the staging area starting at the physical address 2M, then enable paging with identical mapping for the low 1G. the initial port of loader.efi followed the same scheme for handing control to the kernel, since it avoided modifications for the loader/kernel hand-off protocol, and for the kernel page table bootstrap. this approach is incompatible with the UEFI specification, and as a practical matter, caused troubles on many boards, because UEFI firmware is free to use any memory for its own needs. applications like loader.efi must only use memory explicitly allocated using boot interfaces. the original way also potentially destroyed UEFI runtime interfaces data. eventually, loader.efi and the kernel were improved to avoid this problem. glow up arc ✨

💀 amd64 Faults 💀

because it executes in x86 protected mode, the amd64 version of loader.efi is susceptible to CPU faults due to programmer mistakes and memory corruption. to make debugging such faults easier, amd64 loader.efi can provide detailed reporting of the CPU state at the time of the fault. not me being fragile but self-aware 😭

the grab_faults command installs a handler for faults directly in the IDT, avoiding the use of the UEFI debugging interface EFI_DEBUG_SUPPORT_PROTOCOL.RegisterExceptionCallback(). that interface is left available for advanced debuggers in the UEFI environment. the ungrab_faults command tries to deinstall the fault handler, returning TSS and IDT CPU tables to their pre-installation state. and the fault command produces a fault in the loader.efi environment for testing purposes, by executing the ud2 processor instruction. yes, it just. faults. on purpose. for science 🧪

---

🎀 FILES 🎀

• /boot/loader.efi — the location of the UEFI kernel loader within the system.

🌸 EFI System Partition 🌸

loader.efi is installed on the ESP (EFI System Partition) in one of the following locations:

• efi/boot/bootXXX.efi — the default location for any EFI loader (see uefi(8) for values to replace 'XXX' with).
• efi/freebsd/loader.efi — the location reserved specifically for the FreeBSD EFI loader.

the default location for the ESP mount point is documented in hier(7). go check it out, bestie 🫶

💖 EXAMPLES 💖

🎀 Updating loader.efi on the ESP 🎀

Okay bestie, this is the part you actually came for. Here's how you install a shiny new loader.efi on the ESP. Ngl, the exact placement is genuinely complicated, because installations, setups and situations are all little snowflakes. 🌨️

So, ground rules for this section, write these on your hand:

• Paths that are all lower case are Unix paths.
• Paths that are all upper case are relative to the ESP mount point — though they might show up as lower case on your system, because the FAT filesystem of the ESP is case insensitive. 🙈

---

🔍 Step one: find your ESP

The ESP has its own partition type, efi, so you can sniff it out like this:

# gpart show nda0
=>        40  7501476448  nda0  GPT  (3.5T)
          40      614400     1  efi  (300M)
      614440  7500862048     2  freebsd-zfs  (3.5T)

The name of the ESP on this system is nda0p1. By default it'll be mounted on /boot/efi, and you can check that like so:

# mount | grep nda0p1
/dev/nda0p1 on /boot/efi (msdosfs, local)

If it's not mounted, no stress — you just gotta mount it:

# mount -t msdosfs /dev/nda0p1 /boot/efi

---

🕵️ Step two: figure out what you actually booted from

efibootmgr(8) will tell you everything, like the little snitch it is:

# efibootmgr -v
Boot to FW : false
BootCurrent: 0001
Timeout    : 2 seconds
BootOrder  : 0000, 0001, 0003, 0004, 0005, 0006, 0001, 0008, 000A, 000B, 000C, 000E, 0007
...
+Boot0001* FreeBSD ZPOOL HD(1,GPT,b5d0f86b-265d-1e1b-18aa-0ed55e1e73bd,0x28,0x96000)/File(\EFI\FREEBSD\LOADER.EFI)
                            nda0p1:/EFI/FREEBSD/LOADER.EFI /boot/efi//EFI/FREEBSD/LOADER.EFI
...

Depending on the BIOS you'll often see several options — that's normal, don't spiral. 💅 The one you booted with gets a + at the start of the line, like the icon it is. So in this case, the firmware is using /EFI/FREEBSD/LOADER.EFI from the ESP.

A lot of the time it'll actually be the UEFI "default" loader, which varies by architecture:

• Architecture amd64 — Default Path /EFI/BOOT/BOOTX64.EFI
• Architecture arm — Default Path /EFI/BOOT/BOOTARM.EFI
• Architecture arm64 — Default Path /EFI/BOOT/BOOTAA64.EFI
• Architecture i386 — Default Path /EFI/BOOT/BOOTIA32.EFI
• Architecture riscv — Default Path /EFI/BOOT/BOOTRISCV64.EFI

⚠️ But be careful, fr fr: some multiple-boot environments rely on a special bootXXX.efi to function properly. Before you update any bootXXX.efi file, make sure it's actually the FreeBSD boot loader first:

# strings /boot/efi/EFI/BOOT/BOOTX64.EFI | grep FreeBSD | grep EFI
FreeBSD/amd64 EFI loader, Revision 3.0

bsdinstall(8) copies loader.efi to the default name if there wasn't one there already. So before updating, check whether they're actually copies (substituting X64 using the table above, bestie):

# cmp /boot/efi/EFI/FREEBSD/LOADER.EFI /boot/efi/EFI/BOOT/BOOTX64.EFI

---

📋 Step three: copy the loader

# cp /boot/loader.efi /boot/efi/EFI/FREEBSD/LOADER.EFI

...where you swap the all caps part of the example out for the proper path. 👑

Now — if your ESP path was /FREEBSD/LOADER.EFI and LOADER.EFI and BOOTX64.EFI came back identical in the cmp step, then go ahead and copy the loader to the default location too:

# cp /boot/loader.efi /boot/efi/EFI/BOOT/BOOTX64.EFI

And finally — if you mounted the ESP, you might wanna unmount it. Tidy queen behaviour. ✨

# umount /boot/efi

---

💜 SEE ALSO 💜

• loader(8) 🫶
• uefi(8) 🫶

💀 BUGS 💀

Okay so the bug section is giving "we tried our best" energy, and honestly we respect it. 🙈

• Non-x86 serial console handling is even more confusing and less well documented. Yeah. That's the whole note. 😭
• Sometimes when the serial port speed isn't set, 9600 is used. Other times the result is typically 115200, since the speed remains unchanged from the default. Not a vibe, but it is what it is.
• U-Boot implements a subset of the UEFI standard. Some versions don't support fetching loader variables, so efibootmgr may not work. On top of that, efibootmgr isn't supported on armv7 or riscv at all. In these instances, the user has to understand what was booted in order to update it properly — and in most cases it'll be the FreeBSD path and the UEFI default, so honestly just copy loader.efi there if there are loaders there. Typically, in these embedded situations, there's only one .efi file (loader.efi or a copy of loader.efi), and the path to this file is typically the default removable path listed above. 🧚
• Managing booting multiple OSes on UEFI varies greatly, so extra caution is required when updating the UEFI default loader. Like, extra extra. 🚨

---

And that's the whole page, bestie — you made it to the end. 🎉 This one's from the Debian crew, dated April 11, 2026 (that's the LOADER.EFI(8) manual, in case the tab got lost in the group chat). Go forth, update that loader, and text me when the ESP is unmounted. 💅💖