stand/man/loader.efi.8

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