diff options
Diffstat (limited to 'stand/man')
| -rw-r--r-- | stand/man/Makefile | 2 | ||||
| -rw-r--r-- | stand/man/Makefile.depend | 1 | ||||
| -rw-r--r-- | stand/man/boot1.efi.8 | 2 | ||||
| -rw-r--r-- | stand/man/loader.8 | 2 | ||||
| -rw-r--r-- | stand/man/loader.efi.8 | 444 | ||||
| -rw-r--r-- | stand/man/loader_4th.8 | 2 | ||||
| -rw-r--r-- | stand/man/loader_lua.8 | 3 | ||||
| -rw-r--r-- | stand/man/loader_simp.8 | 23 |
8 files changed, 437 insertions, 42 deletions
diff --git a/stand/man/Makefile b/stand/man/Makefile index 27370624ff62..1075c2e831c7 100644 --- a/stand/man/Makefile +++ b/stand/man/Makefile @@ -1,5 +1,3 @@ -# $FreeBSD$ - .include <bsd.init.mk> M.${MK_EFI}+= boot1.efi.8 diff --git a/stand/man/Makefile.depend b/stand/man/Makefile.depend index f80275d86ab1..11aba52f82cf 100644 --- a/stand/man/Makefile.depend +++ b/stand/man/Makefile.depend @@ -1,4 +1,3 @@ -# $FreeBSD$ # Autogenerated - do NOT edit! DIRDEPS = \ diff --git a/stand/man/boot1.efi.8 b/stand/man/boot1.efi.8 index efd3c2c93d5e..b6135f8e0e12 100644 --- a/stand/man/boot1.efi.8 +++ b/stand/man/boot1.efi.8 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd April 6, 2021 .Dt BOOT1.EFI 8 .Os diff --git a/stand/man/loader.8 b/stand/man/loader.8 index 7e652a536b21..4fc3bbb7cff0 100644 --- a/stand/man/loader.8 +++ b/stand/man/loader.8 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd September 29, 2021 .Dt LOADER 8 .Os diff --git a/stand/man/loader.efi.8 b/stand/man/loader.efi.8 index ca7480d5eba6..c488ac257804 100644 --- a/stand/man/loader.efi.8 +++ b/stand/man/loader.efi.8 @@ -1,8 +1,13 @@ .\" -.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD +.\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2019 Netflix, Inc +.\" Copyright (c) 2019-2022 Netflix, Inc .\" Copyright (c) 2022 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" Copyright 2022 The FreeBSD Foundation +.\" +.\" Part of this documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -25,9 +30,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd March 18, 2022 +.Dd September 3, 2024 .Dt LOADER.EFI 8 .Os .Sh NAME @@ -41,7 +44,287 @@ loads the kernel. .Xr boot1.efi 8 is used to load .Nm -when it is placed within the system. +when it is placed within a UFS or ZFS file system. +Alternatively, +.Nm +is used directly when configured with +.Xr efibootmgr 8 , +or when placed directly as the default boot program as described in +.Xr uefi 8 . +When a system is built using +.Xr bsdinstall 8 , +.Nm +will be used directly. +.Ss Console Considerations +The EFI BIOS provides a generic console. +In +.Nm +this is selected by specifying +.Dq efi +using the +.Dv console +variable. +.Nm +examines the +.Dv 8be4df61-93ca-11d2-aa0d-00e098032b8c-ConOut +UEFI environment variable to guess what the +.Dq efi +console points to. +.Nm +will output its prompts and menus to all the places specified by ConOut. +However, the +.Fx +kernel has a limitation when more than one console is present. +The kernel outputs to all configured consoles. +Only the primary console will get the log messages from the +.Xr rc 8 +system, and prompts for things like +.Xr geli 8 +passwords. +If +.Nm +finds a video device first, then +.Nm +tells the kernel to use the video console as primary. +Likewise, if a serial device is first in the +.Dv ConOut +list, the serial port will be the primary console. +.Pp +If there is no +.Dv ConOut +variable, both serial and video are attempted. +.Nm +uses the +.Dq efi +console for the video (which may or may not work) and +.Dq comconsole +for the serial on +.Dv 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. +.Pp +On x86 platforms, if you wish to redirect the loader's output to a serial port +when the EFI BIOS doesn't support it, or to a serial port that isn't the one the +EFI BIOS redirects its output to, set +.Dv console +to +.Dq comconsole . +The default port is +.Dv COM1 +with an I/O address of 0x3f8. +.Dv comconsole_port +is used to set this to a different port address. +.Dv comconsole_speed +is used to set the of the serial port (the default is 9600). +If you have +.Dv console +set to +.Dq efi,comconsole +you will get output on both the EFI console and the serial port. +If this causes a doubling of characters, set +.Dv console +to +.Dq efi , +since your EFI BIOS is redirecting to the serial port already. +.Pp +If your EFI BIOS 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 +.Nm +does not have an ACPI parser, so it cannot convert that to an I/O port. +The +.Fx +kernel initializes its consoles before it can decode ACPI resources. +The +.Fx +kernel will look at the +.Dv hw.uart.console +variable to set its serial console. +Its format should be described in +.Xr uart 4 +but is not. +Set it to +.Dq io:0x3f8,br:115200 +with the proper port address. +PCI or memory mapped ports are beyond the scope of this man page. +.Pp +The serial ports are assigned as follows on IBM PC compatible systems: +.Bl -column -offset indent ".Sy Windows Name" ".Sy I/O Port Address" ".Sy Typical FreeBSD device" +.It Sy Windows Name Ta Sy I/O Port Address Ta Sy Typical FreeBSD device +.It COM1 Ta 0x3f8 Ta Pa /dev/uart0 +.It COM2 Ta 0x2f8 Ta Pa /dev/uart1 +.It COM3 Ta 0x3e8 Ta Pa /dev/uart2 +.It COM4 Ta 0x2e8 Ta Pa /dev/uart3 +.El +Though +.Dv COM3 +and +.Dv COM4 +can vary. +.Pp +.Ss Primary Console +The primary console is set using the boot flags. +These command line arguments set corresponding flags for the kernel. +These flags can be controlled by setting loader environment variables +to +.Dq yes +or +.Dq 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 are included to aid in discovery +of any behavior not covered in this document. +.Bl -column -offset indent ".Sy boot flag" ".Sy loader variable" ".Sy Kernel RB_ flag" +.It Sy boot flag Ta Sy loader variable Ta Sy Kernel RB_ flag +.It Fl a Ta Dv boot_askme Ta Va RB_ASKNAME +.It Fl c Ta Dv boot_cdrom Ta Va RB_CDROM +.It Fl d Ta Dv boot_ddb Ta Va RB_KDB +.It Fl r Ta Dv boot_dfltroot Ta Va RB_DFLTROOT +.It Fl D Ta Dv boot_multiple Ta Va RB_MULTIPLE +.It Fl m Ta Dv boot_mute Ta Va RB_MUTE +.It Fl g Ta Dv boot_gdb Ta Va RB_GDB +.It Fl h Ta Dv boot_serial Ta Va RB_SERIAL +.It Fl p Ta Dv boot_pause Ta Va RB_PAUSE +.It Fl P Ta Dv boot_probe Ta Va RB_PROBE +.It Fl s Ta Dv boot_single Ta Va RB_SINGLE +.It Fl v Ta Dv boot_verbose Ta Va RB_VERBOSE +.El +And the following flags determine the primary console: +.Bl -column -offset indent ".Sy Flags" ".Sy Kernel Flags" ".Sy Kernel Consoles" ".Sy Primary Console" +.It Sy Flags Ta Sy Kernel Flags Ta Sy Kernel Consoles Ta Sy Primary Console +.It none Ta 0 Ta Video Ta Video +.It Fl h Ta RB_SERIAL Ta Serial Ta Serial +.It Fl D Ta RB_MULTIPLE Ta Serial, Video Ta Video +.It Fl Dh Ta RB_SERIAL | RB_MULTIPLE Ta Serial, Video Ta Serial +.El +.Pp +.Nm +does not implement the probe +.Fl P +functionality where we use the video console if a keyboard is connected and a +serial console otherwise. +.Ss Additional Environment Variables +.Nm +loads some extra variables early in startup from +.Pa /efi/freebsd/loader.env +from the EFI partition. +Only simple variables can be set here. +It can be useful to specify the root filesystem: +.Bd -literal -offset indent +rootdev=disk0s1a +.Ed +.Ss Staging Slop +The kernel must parse the firmware memory map tables to know what memory +it can use. +Since it must allocate memory to do this, +.Nm +ensures there's extra memory available, called +.Dq slop , +after everything it loads +.Po +the kernel, modules and metadata +.Pc +for the kernel to bootstrap the memory allocator. +.Pp +By default, amd64 reserves 8MB. +The +.Ic staging_slop +command allows for tuning the slop size. +It takes a single argument, the size of the slop in bytes. +.Ss amd64 Nocopy +.Nm +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 +.Fx 13.1 , +kernels retained the old BIOS-boot protocol of loading at exactly 2MB. +Such kernels must be copied from their loaded location to 2MB prior +starting them up. +The +.Ic copy_staging +command is used to enable this copying for older kernels. +It takes a single argument +which can be one of +.Bl -tag -width disable +.It Ar disable +Force-disable copying staging area to +.Ad 2M . +.It Ar enable +Force-enable copying staging area to +.Ad 2M . +.It Ar 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 +.Va kernphys . +.El +.Pp +Arm64 loaders have operated in the +.Sq nocopy +mode from their inception, so there is no +.Ic copy_staging +command on that platform. +Riscv, 32-bit arm and arm64 have always loaded at any +.Ad 2MB +aligned location, so do not provide +.Ic copy_staging . +.Pp +.Bd -ragged -offset indent +.Sy Note. +BIOS loaders on i386 and amd64 put the staging area starting +at the physical address +.Ad 2M , +then enable paging with identical mapping for the low +.Ad 1G . +The initial port of +.Nm +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. +.Pp +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 +.Nm +must only use memory explicitly allocated using boot interfaces. +The original way also potentially destroyed UEFI runtime interfaces data. +.Pp +Eventually, +.Nm +and the kernel were improved to avoid this problem. +.Ed +.Ss amd64 Faults +Because it executes in x86 protected mode, the amd64 version of +.Nm +is susceptible to CPU faults due to programmer mistakes and +memory corruption. +To make debugging such faults easier, amd64 +.Nm +can provide detailed reporting of the CPU state at the time +of the fault. +.Pp +The +.Ic grab_faults +command installs a handler for faults directly in the IDT, +avoiding the use of the UEFI debugging interface +.Fn EFI_DEBUG_SUPPORT_PROTOCOL.RegisterExceptionCallback . +That interface is left available for advanced debuggers in +the UEFI environment. +The +.Ic ungrab_faults +command tries to deinstall the fault handler, returning TSS and IDT +CPU tables to their pre-installation state. +The +.Ic fault +command produces a fault in the +.Nm +environment for testing purposes, by executing the +.Ic ud2 +processor instruction. .Sh FILES .Bl -tag -width "/boot/loader.efi" .It Pa /boot/loader.efi @@ -49,7 +332,7 @@ The location of the UEFI kernel loader within the system. .El .Ss EFI System Partition .Nm -is installed on ESP (EFI System Partition) in one of the following locations: +is installed on the ESP (EFI System Partition) in one of the following locations: .Bl -tag -width "efi/freebsd/loader.efi" .It Pa efi/boot/bootXXX.efi The default location for any EFI loader @@ -68,35 +351,142 @@ EFI loader. The default location for the ESP mount point is documented in .Xr hier 7 . .Sh EXAMPLES -.Ss Updating loader.efi on ESP -The following examples shows how to install a new +.Ss Updating loader.efi on the ESP +The following example shows how to install a new .Nm -on ESP. +on the ESP. +The exact placement is complicated due to the diversity of +installations, setups and situations. +In this section, paths that are all lower case are Unix paths. +Paths that are all upper case are relative to the ESP mount point, +though they may appear as lower case on your system because the +FAT filesystem of the ESP is case insensitive. .Pp -First, find the partition of type +Locate the ESP, which has its own partition type of .Dq efi : .Bd -literal -offset indent -# gpart list | grep -Ew '(Name|efi)' -1. Name: nvd0p1 - type: efi -2. Name: nvd0p2 -3. Name: nvd0p3 -4. Name: nvd0p4 -1. Name: nvd0 +# gpart show nda0 +=> 40 7501476448 nda0 GPT (3.5T) + 40 614400 1 efi (300M) + 614440 7500862048 2 freebsd-zfs (3.5T) .Ed .Pp -The name of ESP on this system is -.Pa nvd0p1 . +The name of the ESP on this system is +.Pa nda0p1 . +By default, this will be mounted on +.Pa /boot/efi . +To check: +.Bd -literal -offset indent +# mount | grep nda0p1 +/dev/nda0p1 on /boot/efi (msdosfs, local) +.Ed +If it's not mounted, you will need to mount it: +.Bd -literal -offset indent +# mount -t msdosfs /dev/nda0p1 /boot/efi +.Ed .Pp -Second, let's mount ESP, copy -.Nm -to the special location reserved for -.Fx -EFI loaders, and unmount once finished: +.Xr efibootmgr 8 +reports what we booted from. +.Bd -literal -offset indent +# 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(\eEFI\eFREEBSD\eLOADER.EFI) + nda0p1:/EFI/FREEBSD/LOADER.EFI /boot/efi//EFI/FREEBSD/LOADER.EFI +\&... +.Ed +Often there are several options, depending on the BIOS. +The entry that we booted with is marked with a +.Sq + +at the start of the line, as shown above. +So in this case, this firmware is using +.Pa /EFI/FREEBSD/LOADER.EFI +from the ESP. +Often times it will be the UEFI +.Dq default +loader, which varies by architecture. +.Bl -column -offset indent "Architecture" "Default Path" +.It Sy Architecture Ta Sy Default Path +.It amd64 Ta Pa /EFI/BOOT/BOOTX64.EFI +.It arm Ta Pa /EFI/BOOT/BOOTARM.EFI +.It arm64 Ta Pa /EFI/BOOT/BOOTAA64.EFI +.It i386 Ta Pa /EFI/BOOT/BOOTIA32.EFI +.It riscv Ta Pa /EFI/BOOT/BOOTRISCV64.EFI +.El +However, care must be taken: some multiple-boot environments rely on a special +.Pa bootXXX.efi +to function. +Before updating a +.Pa bootXXX.efi +file, make sure it is the FreeBSD boot loader before updating it: +.Bd -literal -offset indent +# strings /boot/efi/EFI/BOOT/BOOTX64.EFI | grep FreeBSD | grep EFI +FreeBSD/amd64 EFI loader, Revision 3.0 +.Ed +.Pp +.Xr bsdinstall 8 +copies +.Pa loader.efi +to the default name if there wasn't one there before. +Check to see if they are copies before updating (with X64 substituted using the +above table): +.Bd -literal -offset indent +# cmp /boot/efi/EFI/FREEBSD/LOADER.EFI /boot/efi/EFI/BOOT/BOOTX64.EFI +.Ed +Copy the loader: +.Bd -literal -offset indent +# cp /boot/loader.efi /boot/efi/EFI/FREEBSD/LOADER.EFI +.Ed +replacing the all caps part of the example with the proper path. +.Pp +If ESP path was +.Pa /FREEBSD/LOADER.EFI +and LOADER.EFI and BOOTX64.EFI were identical in the cmp step, +copy the loader to the default location: +.Bd -literal -offset indent +# cp /boot/loader.efi /boot/efi/EFI/BOOT/BOOTX64.EFI +.Ed +.Pp +Finally, if you mounted the ESP, you may wish to unmount it. .Bd -literal -offset indent -# mount_msdosfs /dev/nvd0p1 /boot/efi -# cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi # umount /boot/efi +.Ed .Sh SEE ALSO .Xr loader 8 , .Xr uefi 8 +.Sh BUGS +Non-x86 serial console handling is even more confusing and less well documented. +.Pp +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. +.Pp +U-Boot implements a subset of the UEFI standard. +Some versions do not support fetching loader variables, so +.Pa efibootmgr +may not work. +In addition, +.Pa efibootmgr +is not supported on armv7 or riscv. +In these instances, the user has to understand what was booted to update +it properly (and in most cases, it will be the FreeBSD path and the UEFI default +so just copy loader.efi there if there are loaders there). +Typically in these embedded situations, there is only one .efi file (loader.efi +or a copy of loader.efi). +The path to this file is typically the default removable path above. +.Pp +Managing booting multiple OSes on UEFI varies greatly, so extra caution when +updating the UEFI default loader. +.Pp +The old, now obsolete, boot1.efi was installed as bootx64.efi in +.Fx 10 +and earlier. +Since it was quite limited in functionality, we created very small +ESPs by default. +A modern loader.efi will not fit. +However, if the old boot1.efi still works, there's no need to update +it since it will chain boot /boot/loader.efi from a copy that +make installworld updates. diff --git a/stand/man/loader_4th.8 b/stand/man/loader_4th.8 index 868e70d180d2..9e87326f893b 100644 --- a/stand/man/loader_4th.8 +++ b/stand/man/loader_4th.8 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd September 29, 2021 .Dt LOADER_4TH 8 .Os diff --git a/stand/man/loader_lua.8 b/stand/man/loader_lua.8 index 1432000c4b53..0aa467237266 100644 --- a/stand/man/loader_lua.8 +++ b/stand/man/loader_lua.8 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd September 29, 2021 .Dt LOADER_LUA 8 .Os @@ -199,6 +197,7 @@ Loader init .Nm configuration files, as described in .Xr loader.conf 5 . +.El .Sh EXAMPLES Boot in single user mode: .Pp diff --git a/stand/man/loader_simp.8 b/stand/man/loader_simp.8 index d628b0d6d008..cdacd823b1a5 100644 --- a/stand/man/loader_simp.8 +++ b/stand/man/loader_simp.8 @@ -22,9 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd September 29, 2021 +.Dd September 30, 2021 .Dt LOADER_SIMP 8 .Os .Sh NAME @@ -341,6 +339,21 @@ In a running system, the state of console muting can be manipulated by the utility. .It Va boot_pause During the device probe, pause after each line is printed. +.It Va boot_safe +Force userland to boot in +.Dq safe mode , +which may disable or limit the functionality of some services that may not be +desired in safe mode. +This is typically set by selecting +.Dq safe mode +in the loader menu, which also sets some other hints for the kernel. +Applications wishing to respect safe mode should +.Sy only +test for the presence of +.Va boot_safe +in +.Xr kenv 1 , +not for any particular value. .It Va boot_serial Force the use of a serial console even when an internal console is present. @@ -360,7 +373,7 @@ Defines the speed of the serial console (i386 and amd64 only). If the previous boot stage indicated that a serial console is in use then this variable is initialized to the current speed of the console serial port. -Otherwise it is set to 9600 unless this was overridden using the +Otherwise it is set to 115200 unless this was overridden using the .Va BOOT_COMCONSOLE_SPEED variable when .Nm @@ -661,6 +674,7 @@ command line by booting unconditionally in .Pa loader.rc . In order for this to be effective, one should also configure the firmware (BIOS or UEFI) to prevent booting from unauthorized devices. +.El .Sh FILES .Bl -tag -width /boot/loader_simp -compact .It Pa /boot/loader_simp @@ -670,6 +684,7 @@ itself. The script run by .Nm on startup. +.El .Sh EXAMPLES Boot in single user mode: .Pp |