xref: /freebsd/stand/man/loader.efi.8 (revision edf8578117e8844e02c0121147f45e4609b30680)
1.\"
2.\" SPDX-License-Identifier: BSD-2-Clause
3.\"
4.\" Copyright (c) 2019-2022 Netflix, Inc
5.\" Copyright (c) 2022 Mateusz Piotrowski <0mp@FreeBSD.org>
6.\" Copyright 2022 The FreeBSD Foundation, Inc.
7.\"
8.\" Part of this documentation was written by
9.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
10.\" from the FreeBSD Foundation.
11.\"
12.\" Redistribution and use in source and binary forms, with or without
13.\" modification, are permitted provided that the following conditions
14.\" are met:
15.\" 1. Redistributions of source code must retain the above copyright
16.\"    notice, this list of conditions and the following disclaimer.
17.\" 2. Redistributions in binary form must reproduce the above copyright
18.\"    notice, this list of conditions and the following disclaimer in the
19.\"    documentation and/or other materials provided with the distribution.
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31.\" SUCH DAMAGE.
32.\"
33.Dd September 4, 2022
34.Dt LOADER.EFI 8
35.Os
36.Sh NAME
37.Nm loader.efi
38.Nd UEFI kernel loader
39.Sh DESCRIPTION
40On UEFI systems,
41.Nm
42loads the kernel.
43.Pp
44.Xr boot1.efi 8
45is used to load
46.Nm
47when it is placed within a UFS or ZFS file system.
48Alternatively,
49.Nm
50is used directly when configured with
51.Xr efibootmgr 8 ,
52or when placed directly as the default boot program as described in
53.Xr uefi 8 .
54When a system is built using
55.Xr bsdinstall 8 ,
56.Nm
57will be used directly.
58.Ss Console Considerations
59The EFI BIOS provides a generic console.
60In
61.Nm
62this is selected by specifying
63.Dq efi
64using the
65.Dv console
66variable.
67.Nm
68examines the
69.Dv 8be4df61-93ca-11d2-aa0d-00e098032b8c-ConOut
70UEFI environment variable to guess what the
71.Dq efi
72console points to.
73.Nm
74will output its prompts and menus to all the places specified by ConOut.
75However, the
76.Fx
77kernel has a limitation when more than one console is present.
78The kernel outputs to all configured consoles.
79Only the primary console will get the log messages from the
80.Xr rc 8
81system, and prompts for things like
82.Xr geli 8
83passwords.
84If
85.Nm
86finds a video device first, then
87.Nm
88tells the kernel to use the video console as primary.
89Likewise, if a serial device is first in the
90.Dv ConOut
91list, the serial port will be the primary console.
92.Pp
93If there is no
94.Dv ConOut
95variable, both serial and video are attempted.
96.Nm
97uses the
98.Dq efi
99console for the video (which may or may not work) and
100.Dq comconsole
101for the serial on
102.Dv COM1
103at the default baud rate.
104The kernel will use a dual console, with the video console
105primary if a UEFI graphics device is detected, or the serial console
106as primary if not.
107.Pp
108On x86 platforms, if you wish to redirect the loader's output to a serial port
109when the EFI BIOS doesn't support it, or to a serial port that isn't the one the
110EFI BIOS redirects its output to, set
111.Dv console
112to
113.Dq comconsole .
114The default port is
115.Dv COM1
116with an I/O address of 0x3f8.
117.Dv comconsole_port
118is used to set this to a different port address.
119.Dv comconsole_speed
120is used to set the of the serial port (the default is 9600).
121If you have
122.Dv console
123set to
124.Dq efi,comconsole
125you will get output on both the EFI console and the serial port.
126If this causes a doubling of characters, set
127.Dv console
128to
129.Dq efi ,
130since your EFI BIOS is redirecting to the serial port already.
131.Pp
132If your EFI BIOS redirects the serial port, you may need to tell the kernel
133which address to use.
134EFI uses ACPI's UID to identify the serial port, but
135.Nm
136does not have an ACPI parser, so it cannot convert that to an I/O port.
137The
138.Fx
139kernel initializes its consoles before it can decode ACPI resources.
140The
141.Fx
142kernel will look at the
143.Dv hw.uart.console
144variable to set its serial console.
145Its format should be described in
146.Xr uart 4
147but is not.
148Set it to
149.Dq io:0x3f8,br:115200
150with the proper port address.
151PCI or memory mapped ports are beyond the scope of this man page.
152.Pp
153The serial ports are assigned as follows on IBM PC compatible systems:
154.Bl -column -offset indent ".Sy Windows Name" ".Sy I/O Port Address" ".Sy Typical FreeBSD device"
155.It Sy Windows Name Ta Sy I/O Port Address Ta Sy Typical FreeBSD device
156.It COM1 Ta 0x3f8 Ta Pa /dev/uart0
157.It COM2 Ta 0x2f8 Ta Pa /dev/uart1
158.It COM3 Ta 0x3e8 Ta Pa /dev/uart2
159.It COM4 Ta 0x2e8 Ta Pa /dev/uart3
160.El
161Though
162.Dv COM3
163and
164.Dv COM4
165can vary.
166.Pp
167.Ss Primary Console
168The primary console is set using the boot flags.
169These command line arguments set corresponding flags for the kernel.
170These flags can be controlled by setting loader environment variables
171to
172.Dq yes
173or
174.Dq no .
175Boot flags may be set on the command line to the boot command.
176Inside the kernel, the RB_ flags are used to control behavior, sometimes
177in architecturally specific ways and are included to aid in discovery
178of any behavior not covered in this document.
179.Bl -column -offset indent ".Sy boot flag" ".Sy loader variable" ".Sy Kernel RB_ flag"
180.It Sy boot flag Ta Sy loader variable Ta Sy Kernel RB_ flag
181.It Fl a Ta Dv boot_askme Ta Va RB_ASKNAME
182.It Fl c Ta Dv boot_cdrom Ta Va RB_CDROM
183.It Fl d Ta Dv boot_ddb Ta Va RB_KDB
184.It Fl r Ta Dv boot_dfltroot Ta Va RB_DFLTROOT
185.It Fl D Ta Dv boot_multiple Ta Va RB_MULTIPLE
186.It Fl m Ta Dv boot_mute Ta Va RB_MUTE
187.It Fl g Ta Dv boot_gdb Ta Va RB_GDB
188.It Fl h Ta Dv boot_serial Ta Va RB_SERIAL
189.It Fl p Ta Dv boot_pause Ta Va RB_PAUSE
190.It Fl P Ta Dv boot_probe Ta Va RB_PROBE
191.It Fl s Ta Dv boot_single Ta Va RB_SINGLE
192.It Fl v Ta Dv boot_verbose Ta Va RB_VERBOSE
193.El
194And the following flags determine the primary console:
195.Bl -column -offset indent ".Sy Flags" ".Sy Kernel Flags" ".Sy Kernel Consoles" ".Sy Primary Console"
196.It Sy Flags Ta Sy Kernel Flags Ta Sy Kernel Consoles Ta Sy Primary Console
197.It none Ta 0 Ta Video Ta Video
198.It Fl h Ta RB_SERIAL Ta Serial Ta Serial
199.It Fl D Ta RB_MULTIPLE Ta Serial, Video Ta Video
200.It Fl Dh Ta RB_SERIAL | RB_MULTIPLE Ta Serial, Video Ta Serial
201.El
202.Pp
203.Nm
204does not implement the probe
205.Fl P
206functionality where we use the video console if a keyboard is connected and a
207serial console otherwise.
208.Ss Staging Slop
209The kernel must parse the firmware memory map tables to know what memory
210it can use.
211Since it must allocate memory to do this,
212.Nm
213ensures there's extra memory available, called
214.Dq slop ,
215after everything it loads
216.Po
217the kernel, modules and metadata
218.Pc
219for the kernel to bootstrap the memory allocator.
220.Pp
221By default, amd64 reserves 8MB.
222The
223.Ic staging_slop
224command allows for tuning the slop size.
225It takes a single argument, the size of the slop in bytes.
226.Ss amd64 Nocopy
227.Nm
228will load the kernel into memory that is 2MB aligned below 4GB.
229It cannot load to a fixed address because the UEFI firmware may reserve
230arbitrary memory for its use at runtime.
231Prior to
232.Fx 13.1 ,
233kernels retained the old BIOS-boot protocol of loading at exactly 2MB.
234Such kernels must be copied from their loaded location to 2MB prior
235starting them up.
236The
237.Ic copy_staging
238command is used to enable this copying for older kernels.
239It takes a single argument
240which can be one of
241.Bl -tag -width disable
242.It Ar disable
243Force-disable copying staging area to
244.Ad 2M .
245.It Ar enable
246Force-enable copying staging area to
247.Ad 2M .
248.It Ar auto
249Selects the behaviour based on the kernel's capability of boostraping
250from non-2M physical base.
251The kernel reports this capability by exporting the symbol
252.Va kernphys .
253.El
254.Pp
255Arm64 loaders have operated in the
256.Sq nocopy
257mode from their inception, so there is no
258.Ic copy_staging
259command on that platform.
260Riscv, 32-bit arm and arm64 have always loaded at any
261.Ad 2MB
262aligned location, so do not provide
263.Ic copy_staging .
264.Pp
265.Bd -ragged -offset indent
266.Sy Note.
267BIOS loaders on i386 and amd64 put the staging area starting
268at the physical address
269.Ad 2M ,
270then enable paging with identical mapping for the low
271.Ad 1G .
272The initial port of
273.Nm
274followed the same scheme for handing control to the kernel,
275since it avoided modifications for the loader/kernel hand-off protocol,
276and for the kernel page table bootstrap.
277.Pp
278This approach is incompatible with the UEFI specification,
279and as a practical matter, caused troubles on many boards,
280because UEFI firmware is free to use any memory for its own needs.
281Applications like
282.Nm
283must only use memory explicitly allocated using boot interfaces.
284The original way also potentially destroyed UEFI runtime interfaces data.
285.Pp
286Eventually,
287.Nm
288and the kernel were improved to avoid this problem.
289.Ed
290.Ss amd64 Faults
291Because it executes in x86 protected mode, the amd64 version of
292.Nm
293is susceptible to CPU faults due to programmer mistakes and
294memory corruption.
295To make debugging such faults easier, amd64
296.Nm
297can provide detailed reporting of the CPU state at the time
298of the fault.
299.Pp
300The
301.Ic grab_faults
302command installs a handler for faults directly in the IDT,
303avoiding the use of the UEFI debugging interface
304.Fn EFI_DEBUG_SUPPORT_PROTOCOL.RegisterExceptionCallback .
305That interface is left available for advanced debuggers in
306the UEFI environment.
307The
308.Ic ungrab_faults
309command tries to deinstall the fault handler, returning TSS and IDT
310CPU tables to their pre-installation state.
311The
312.Ic fault
313command produces a fault in the
314.Nm
315environment for testing purposes, by executing the
316.Ic ud2
317processor instruction.
318.Sh FILES
319.Bl -tag -width "/boot/loader.efi"
320.It Pa /boot/loader.efi
321The location of the UEFI kernel loader within the system.
322.El
323.Ss EFI System Partition
324.Nm
325is installed on the ESP (EFI System Partition) in one of the following locations:
326.Bl -tag -width "efi/freebsd/loader.efi"
327.It Pa efi/boot/bootXXX.efi
328The default location for any EFI loader
329.Po see
330.Xr uefi 8
331for values to replace
332.Ql XXX
333with
334.Pc .
335.It Pa efi/freebsd/loader.efi
336The location reserved specifically for the
337.Fx
338EFI loader.
339.El
340.Pp
341The default location for the ESP mount point is documented in
342.Xr hier 7 .
343.Sh EXAMPLES
344.Ss Updating loader.efi on the ESP
345The following examples shows how to install a new
346.Nm
347on the ESP.
348.Pp
349First, find the partition of type
350.Dq efi :
351.Bd -literal -offset indent
352# gpart list | grep -Ew '(Name|efi)'
3531. Name: nvd0p1
354   type: efi
3552. Name: nvd0p2
3563. Name: nvd0p3
3574. Name: nvd0p4
3581. Name: nvd0
359.Ed
360.Pp
361The name of the ESP on this system is
362.Pa nvd0p1 .
363.Pp
364Second, let's mount the ESP, copy
365.Nm
366to the special location reserved for
367.Fx
368EFI loaders, and unmount once finished:
369.Bd -literal -offset indent
370# mount_msdosfs /dev/nvd0p1 /boot/efi
371# cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi
372# umount /boot/efi
373.Ed
374.Sh SEE ALSO
375.Xr loader 8 ,
376.Xr uefi 8
377.Sh BUGS
378Systems that do not have a
379.Dv ConOut
380variable set are not conformant with the standard, and likely have unexpected
381results.
382.Pp
383Non-x86 serial console handling is even more confusing and less well documented.
384.Pp
385Sometimes when the serial port speed isn't set, 9600 is used.
386Other times the result is typically 115200 since the speed remains unchanged
387from the default.
388