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