git: 75a91c70f8d1 - main - stand: Document EFI consoles
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Thu, 01 Sep 2022 16:42:18 UTC
The branch main has been updated by imp:
URL: https://cgit.FreeBSD.org/src/commit/?id=75a91c70f8d12825ded5a6d14841bf3065ba6595
commit 75a91c70f8d12825ded5a6d14841bf3065ba6595
Author: Warner Losh <imp@FreeBSD.org>
AuthorDate: 2022-09-01 16:34:30 +0000
Commit: Warner Losh <imp@FreeBSD.org>
CommitDate: 2022-09-01 16:34:30 +0000
stand: Document EFI consoles
Document how EFI consoles work, at least on x86. There's a number of
weird quirks and limitations that are generally known, but not
documented until now. Include information on how EFI decides what the
defualt console is, how to set it and how to cope with common
situations. Note limitations and mismatch between ACPI (which uses UID
to identify a device) and our console code (which uses a raw address)
and explain why we can't translate between them in the loader.
Sponsored by: Netflix
Reviewed by: manu, kevans, rpokala, pauamma
Differential Revision: https://reviews.freebsd.org/D36286
---
stand/man/loader.efi.8 | 188 ++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 180 insertions(+), 8 deletions(-)
diff --git a/stand/man/loader.efi.8 b/stand/man/loader.efi.8
index ca7480d5eba6..139988b111d4 100644
--- a/stand/man/loader.efi.8
+++ b/stand/man/loader.efi.8
@@ -1,7 +1,7 @@
.\"
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
.\"
-.\" Copyright (c) 2019 Netflix, Inc
+.\" Copyright (c) 2019-2022 Netflix, Inc
.\" Copyright (c) 2022 Mateusz Piotrowski <0mp@FreeBSD.org>
.\"
.\" Redistribution and use in source and binary forms, with or without
@@ -27,7 +27,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd March 18, 2022
+.Dd August 31, 2022
.Dt LOADER.EFI 8
.Os
.Sh NAME
@@ -41,7 +41,167 @@ 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.
.Sh FILES
.Bl -tag -width "/boot/loader.efi"
.It Pa /boot/loader.efi
@@ -49,7 +209,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,10 +228,10 @@ EFI loader.
The default location for the ESP mount point is documented in
.Xr hier 7 .
.Sh EXAMPLES
-.Ss Updating loader.efi on ESP
+.Ss Updating loader.efi on the ESP
The following examples shows how to install a new
.Nm
-on ESP.
+on the ESP.
.Pp
First, find the partition of type
.Dq efi :
@@ -85,10 +245,10 @@ First, find the partition of type
1. Name: nvd0
.Ed
.Pp
-The name of ESP on this system is
+The name of the ESP on this system is
.Pa nvd0p1 .
.Pp
-Second, let's mount ESP, copy
+Second, let's mount the ESP, copy
.Nm
to the special location reserved for
.Fx
@@ -97,6 +257,18 @@ EFI loaders, and unmount once finished:
# 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
+Systems that do not have a
+.Dv ConOut
+variable set are not conformant with the standard, and likely have unexpected
+results.
+.Pp
+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.