Index: stand/man/loader.efi.8
===================================================================
--- stand/man/loader.efi.8
+++ stand/man/loader.efi.8
@@ -27,7 +27,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 18, 2022
+.Dd August 21, 2022
 .Dt LOADER.EFI 8
 .Os
 .Sh NAME
@@ -41,7 +41,156 @@
 .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.
+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.
+However, 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, serial will be selected as console.
+However, this setup is non-standard and may be buggy.
+.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.
+This sets number of flags to the kernel.
+These flags can be controlled by setting loader environment variables set
+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 +198,7 @@
 .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 +217,10 @@
 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 +234,10 @@
 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
@@ -100,3 +249,14 @@
 .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 at present.
+.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.