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
@@ -42,6 +42,142 @@
 is used to load
 .Nm
 when it is placed within the system.
+Alternatively,
+.Nm
+is used directly when configured with
+.Xr efibootmgr 8
+or when placed directly in 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 with the
+.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 these places.
+However, the
+.Fx
+kernel has a limitation.
+All consoles that are configured will get kernel output.
+However, only the primary console will get boot message from the
+.Xr rc 8
+system, and prompts for things like
+.Xr geli 8
+passwords.
+If
+.Nm
+finds a video device first, then it will be the primary console.
+If it finds a serial device first, that will be the primary console.
+.Pp
+If there is no
+.Dv ConOut
+variable, serial will be selected.
+.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 a 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 a number of flags to the kernel.
+These flags can be controlled by setting loader environment variables.
+.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"
+.Bl Sy Flags Ta Sy Kernel Flags Ta Sy Kernel Consoles Ta Sy Primary Console
+.Bl none Ta 0 Ta Video Ta Video
+.Bl Fl h Ta RB_SERIAL Ta Serial Ta Serial
+.Bl Fl D Ta RB_MULTIPLE Ta Serial, Video Ta Video
+.Bl 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
@@ -100,3 +236,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.
+.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.