1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3.\" 4.\" Copyright (c) 2019-2022 Netflix, Inc 5.\" Copyright (c) 2022 Mateusz Piotrowski <0mp@FreeBSD.org> 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd August 31, 2022 31.Dt LOADER.EFI 8 32.Os 33.Sh NAME 34.Nm loader.efi 35.Nd UEFI kernel loader 36.Sh DESCRIPTION 37On UEFI systems, 38.Nm 39loads the kernel. 40.Pp 41.Xr boot1.efi 8 42is used to load 43.Nm 44when it is placed within a UFS or ZFS file system. 45Alternatively, 46.Nm 47is used directly when configured with 48.Xr efibootmgr 8 , 49or when placed directly as the default boot program as described in 50.Xr uefi 8 . 51When a system is built using 52.Xr bsdinstall 8 , 53.Nm 54will be used directly. 55.Ss Console Considerations 56The EFI BIOS provides a generic console. 57In 58.Nm 59this is selected by specifying 60.Dq efi 61using the 62.Dv console 63variable. 64.Nm 65examines the 66.Dv 8be4df61-93ca-11d2-aa0d-00e098032b8c-ConOut 67UEFI environment variable to guess what the 68.Dq efi 69console points to. 70.Nm 71will output its prompts and menus to all the places specified by ConOut. 72However, the 73.Fx 74kernel has a limitation when more than one console is present. 75The kernel outputs to all configured consoles. 76Only the primary console will get the log messages from the 77.Xr rc 8 78system, and prompts for things like 79.Xr geli 8 80passwords. 81If 82.Nm 83finds a video device first, then 84.Nm 85tells the kernel to use the video console as primary. 86Likewise, if a serial device is first in the 87.Dv ConOut 88list, the serial port will be the primary console. 89.Pp 90If there is no 91.Dv ConOut 92variable, both serial and video are attempted. 93.Nm 94uses the 95.Dq efi 96console for the video (which may or may not work) and 97.Dq comconsole 98for the serial on 99.Dv COM1 100at the default baud rate. 101The kernel will use a dual console, with the video console 102primary if a UEFI graphics device is detected, or the serial console 103as primary if not. 104.Pp 105On x86 platforms, if you wish to redirect the loader's output to a serial port 106when the EFI BIOS doesn't support it, or to a serial port that isn't the one the 107EFI BIOS redirects its output to, set 108.Dv console 109to 110.Dq comconsole . 111The default port is 112.Dv COM1 113with an I/O address of 0x3f8. 114.Dv comconsole_port 115is used to set this to a different port address. 116.Dv comconsole_speed 117is used to set the of the serial port (the default is 9600). 118If you have 119.Dv console 120set to 121.Dq efi,comconsole 122you will get output on both the EFI console and the serial port. 123If this causes a doubling of characters, set 124.Dv console 125to 126.Dq efi , 127since your EFI BIOS is redirecting to the serial port already. 128.Pp 129If your EFI BIOS redirects the serial port, you may need to tell the kernel 130which address to use. 131EFI uses ACPI's UID to identify the serial port, but 132.Nm 133does not have an ACPI parser, so it cannot convert that to an I/O port. 134The 135.Fx 136kernel initializes its consoles before it can decode ACPI resources. 137The 138.Fx 139kernel will look at the 140.Dv hw.uart.console 141variable to set its serial console. 142Its format should be described in 143.Xr uart 4 144but is not. 145Set it to 146.Dq io:0x3f8,br:115200 147with the proper port address. 148PCI or memory mapped ports are beyond the scope of this man page. 149.Pp 150The serial ports are assigned as follows on IBM PC compatible systems: 151.Bl -column -offset indent ".Sy Windows Name" ".Sy I/O Port Address" ".Sy Typical FreeBSD device" 152.It Sy Windows Name Ta Sy I/O Port Address Ta Sy Typical FreeBSD device 153.It COM1 Ta 0x3f8 Ta Pa /dev/uart0 154.It COM2 Ta 0x2f8 Ta Pa /dev/uart1 155.It COM3 Ta 0x3e8 Ta Pa /dev/uart2 156.It COM4 Ta 0x2e8 Ta Pa /dev/uart3 157.El 158Though 159.Dv COM3 160and 161.Dv COM4 162can vary. 163.Pp 164.Ss Primary Console 165The primary console is set using the boot flags. 166These command line arguments set corresponding flags for the kernel. 167These flags can be controlled by setting loader environment variables 168to 169.Dq yes 170or 171.Dq no . 172Boot flags may be set on the command line to the boot command. 173Inside the kernel, the RB_ flags are used to control behavior, sometimes 174in architecturally specific ways and are included to aid in discovery 175of any behavior not covered in this document. 176.Bl -column -offset indent ".Sy boot flag" ".Sy loader variable" ".Sy Kernel RB_ flag" 177.It Sy boot flag Ta Sy loader variable Ta Sy Kernel RB_ flag 178.It Fl a Ta Dv boot_askme Ta Va RB_ASKNAME 179.It Fl c Ta Dv boot_cdrom Ta Va RB_CDROM 180.It Fl d Ta Dv boot_ddb Ta Va RB_KDB 181.It Fl r Ta Dv boot_dfltroot Ta Va RB_DFLTROOT 182.It Fl D Ta Dv boot_multiple Ta Va RB_MULTIPLE 183.It Fl m Ta Dv boot_mute Ta Va RB_MUTE 184.It Fl g Ta Dv boot_gdb Ta Va RB_GDB 185.It Fl h Ta Dv boot_serial Ta Va RB_SERIAL 186.It Fl p Ta Dv boot_pause Ta Va RB_PAUSE 187.It Fl P Ta Dv boot_probe Ta Va RB_PROBE 188.It Fl s Ta Dv boot_single Ta Va RB_SINGLE 189.It Fl v Ta Dv boot_verbose Ta Va RB_VERBOSE 190.El 191And the following flags determine the primary console: 192.Bl -column -offset indent ".Sy Flags" ".Sy Kernel Flags" ".Sy Kernel Consoles" ".Sy Primary Console" 193.It Sy Flags Ta Sy Kernel Flags Ta Sy Kernel Consoles Ta Sy Primary Console 194.It none Ta 0 Ta Video Ta Video 195.It Fl h Ta RB_SERIAL Ta Serial Ta Serial 196.It Fl D Ta RB_MULTIPLE Ta Serial, Video Ta Video 197.It Fl Dh Ta RB_SERIAL | RB_MULTIPLE Ta Serial, Video Ta Serial 198.El 199.Pp 200.Nm 201does not implement the probe 202.Fl P 203functionality where we use the video console if a keyboard is connected and a 204serial console otherwise. 205.Sh FILES 206.Bl -tag -width "/boot/loader.efi" 207.It Pa /boot/loader.efi 208The location of the UEFI kernel loader within the system. 209.El 210.Ss EFI System Partition 211.Nm 212is installed on the ESP (EFI System Partition) in one of the following locations: 213.Bl -tag -width "efi/freebsd/loader.efi" 214.It Pa efi/boot/bootXXX.efi 215The default location for any EFI loader 216.Po see 217.Xr uefi 8 218for values to replace 219.Ql XXX 220with 221.Pc . 222.It Pa efi/freebsd/loader.efi 223The location reserved specifically for the 224.Fx 225EFI loader. 226.El 227.Pp 228The default location for the ESP mount point is documented in 229.Xr hier 7 . 230.Sh EXAMPLES 231.Ss Updating loader.efi on the ESP 232The following examples shows how to install a new 233.Nm 234on the ESP. 235.Pp 236First, find the partition of type 237.Dq efi : 238.Bd -literal -offset indent 239# gpart list | grep -Ew '(Name|efi)' 2401. Name: nvd0p1 241 type: efi 2422. Name: nvd0p2 2433. Name: nvd0p3 2444. Name: nvd0p4 2451. Name: nvd0 246.Ed 247.Pp 248The name of the ESP on this system is 249.Pa nvd0p1 . 250.Pp 251Second, let's mount the ESP, copy 252.Nm 253to the special location reserved for 254.Fx 255EFI loaders, and unmount once finished: 256.Bd -literal -offset indent 257# mount_msdosfs /dev/nvd0p1 /boot/efi 258# cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi 259# umount /boot/efi 260.Ed 261.Sh SEE ALSO 262.Xr loader 8 , 263.Xr uefi 8 264.Sh BUGS 265Systems that do not have a 266.Dv ConOut 267variable set are not conformant with the standard, and likely have unexpected 268results. 269.Pp 270Non-x86 serial console handling is even more confusing and less well documented. 271.Pp 272Sometimes when the serial port speed isn't set, 9600 is used. 273Other times the result is typically 115200 since the speed remains unchanged 274from the default. 275