4 files changed, 300 insertions, 3 deletions
diff --git a/stand/efi/gptboot/Makefile b/stand/efi/gptboot/Makefile
index 7d6dee85f93f..2dcf8dda8f59 100644
--- a/stand/efi/gptboot/Makefile
+++ b/stand/efi/gptboot/Makefile
@@ -6,6 +6,7 @@ MK_LOADER_ZFS=no
 EFI_DEBUG=yes
 
 BOOT1?=		gptboot
+MAN=		gptboot.efi.8
 .PATH:		${SRCTOP}/stand/efi/boot1 ${SRCTOP}/stand/libsa
 CFLAGS+=	-I${SRCTOP}/stand/efi/boot1
 CFLAGS+=	-I${.CURDIR}
diff --git a/stand/efi/gptboot/gptboot.efi.8 b/stand/efi/gptboot/gptboot.efi.8
new file mode 100644
index 000000000000..134c5353e9f1
--- /dev/null
+++ b/stand/efi/gptboot/gptboot.efi.8
@@ -0,0 +1,282 @@
+.\" Copyright (c) 2013 Warren Block All rights reserved.
+.\" Copyright (c) 2021 Warner Losh
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd April 6, 2021
+.Dt GPTBOOT.EFI 8
+.Os
+.Sh NAME
+.Nm gptboot.efi
+.Nd GPT bootcode for UFS on UEFI computers
+.Sh DESCRIPTION
+.Nm
+is used on UEFI computers to boot from a UFS partition on a
+GPT-partitioned disk.
+.Nm
+is installed in the EFI System Partition (ESP).
+For BIOS-based computers,
+see
+.Xr gptboot 8
+for details.
+While conceptually similar, the details differ.
+.Nm
+works only with UFS root file systems.
+Users with ZFS partitions should use
+.Xr loader.efi 8
+with
+.Xr bectl 8
+to control what dataset is used for root.
+.Pp
+What UEFI computers boot is usually controlled via the mechanisms explained in
+.Xr efibootmgr 8
+using
+.Xr loader.efi 8
+or
+.Xr boot1.efi 8 .
+However, some setups cannot use those mechanisms.
+When the users cannot rely on host-supplied UEFI variables
+or they want the contents of the media alone to decide root,
+.Nm
+accomplishes these goals.
+.Pp
+When it starts,
+.Nm
+first reads the GPT and determines which drive and partition to
+boot from, as described under
+.Sx BOOTING ,
+below.
+If it does not find an eligible partition, it returns to the UEFI
+firmware.
+The firmware will then try the next bootable item in the UEFI Boot Manager's
+list, if any, usually a different disk.
+.Sh IMPLEMENTATION NOTES
+The GPT standard allows a variable number of partitions, but
+.Nm
+only boots from tables with 128 partitions or less.
+.Sh PARTITION ATTRIBUTES
+.Nm
+checks and manages several attributes of GPT UFS partitions.
+These flags are
+.Fx
+specific and non-standard.
+.Bl -tag -width ".Cm bootfailed"
+.It Cm bootme
+Attempt to boot from this partition.
+If more than one partition has the
+.Cm bootme
+attribute set,
+.Nm
+will attempt to boot each one until successful.
+.It Cm bootonce
+Attempt to boot from this partition only one time.
+Setting this attribute with
+.Xr gpart 8
+automatically also sets the
+.Cm bootme
+attribute.
+Multiple partitions may have the
+.Cm bootonce
+and
+.Cm bootme
+attributes set.
+.It Cm bootfailed
+The
+.Cm bootfailed
+attribute marks partitions that had the
+.Cm bootonce
+attribute set, but failed to boot.
+This attribute is managed by the system.
+See
+.Sx "BOOTING"
+and
+.Sx "POST-BOOT ACTIONS"
+below for details.
+.El
+.Sh USAGE
+For normal usage, the user does not have to set or manage any of the
+partition attributes.
+.Nm
+will boot from the first UFS partition found on the device.
+.Pp
+The
+.Cm bootonce
+attribute can be used for testing an upgraded operating system on
+an already-working computer.
+The existing system partition is left untouched, and the new version
+of the operating system to be tested is installed on another partition.
+The
+.Cm bootonce
+attribute is set on that new test partition.
+The next boot is attempted from the test partition.
+Success or failure will be shown in the system log files.
+After a successful boot of the test partition, a user script can check
+the logs and change the
+.Cm bootme
+attributes so the test partition becomes the new system partition.
+Because the
+.Cm bootonce
+attribute is cleared after an attempted boot, a failed boot will not
+leave the system attempting to boot from a partition that will never
+succeed.
+Instead, the system will boot from the older, known-working operating
+system that has not been modified.
+If the
+.Cm bootme
+attribute is set on any partitions, booting will be attempted from them
+first.
+If no partitions with
+.Cm bootme
+attributes are found, booting will be attempted from the first UFS
+partition found.
+.Sh BOOTING
+.Nm
+first reads the partition table.
+All
+.Cm freebsd-ufs
+partitions with only the
+.Cm bootonce
+attribute set, indicating a failed boot, are set to
+.Cm bootfailed .
+.Nm
+then scans through all of the
+.Cm freebsd-ufs
+partitions.
+Boot behavior depends on the combination of
+.Cm bootme
+and
+.Cm bootonce
+attributes set on those partitions.
+.Bl -tag -width ".Cm bootonce + .Cm bootme"
+.It Cm bootonce + Cm bootme
+Highest priority: booting is attempted from each of the
+.Cm freebsd-ufs
+partitions with both of these attributes.
+On each partition, the
+.Cm bootme
+attribute is removed and the boot attempted.
+.It Cm bootme
+Middle priority: booting is attempted from each of the
+.Cm freebsd-ufs
+partitions with the
+.Cm bootme
+attribute.
+.El
+.Pp
+If neither
+.Cm bootonce
+nor
+.Cm bootme
+attributes are found on any partitions, booting is attempted from the
+first
+.Cm freebsd-ufs
+partition on the disk.
+.Sh POST-BOOT ACTIONS
+The startup script
+.Pa /etc/rc.d/gptboot
+checks the attributes of
+.Cm freebsd-ufs
+partitions on all GPT disks.
+Partitions with the
+.Cm bootfailed
+attribute generate a
+.Dq boot from X failed
+system log message.
+Partitions with only the
+.Cm bootonce
+attribute, indicating a partition that successfully booted, generate a
+.Dq boot from X succeeded
+system log message.
+The
+.Cm bootfailed
+attributes are cleared from all the partitions.
+The
+.Cm bootonce
+attribute is cleared from the partition that successfully booted.
+There is normally only one of these.
+.Sh FILES
+.Bl -tag -width /boot/gptboot.efi -compact
+.It Pa /boot/gptboot.efi
+bootcode binary
+.It Pa /boot/efi/efi/boot/bootx64.efi
+Default boot loader for amd64 systems.
+.It Pa /boot/efi/efi/boot/bootaa64.efi
+Default boot loader for arm64 systems.
+.It Pa /boot/efi/efi/boot/bootarm.efi
+Default boot loader for arm systems.
+.It Pa /boot/efi/efi/boot/bootriscv64.efi
+Default boot loader for riscv systems.
+.El
+.Sh EXAMPLES
+.Nm
+is installed in the ESP with
+.Xr cp 1 .
+.Pp
+Install
+.Nm
+into the ESP for the system.
+This assumes the ESP is mounted in the standard
+.Pa /boot/efi
+directory.
+For amd64, use the following
+.Bd -literal -offset indent -compact
+cp /boot/gptboot.efi /boot/efi/efi/boot/bootx64.efi
+.Ed
+For other systems, use the file listed in the
+.Sx FILES
+section.
+.Pp
+Set the
+.Cm bootme
+attribute for partition 2:
+.Bd -literal -offset indent
+gpart set -a bootme -i 2 ada0
+.Ed
+.Pp
+Set the
+.Cm bootonce
+attribute for partition 2, automatically also setting the
+.Cm bootme
+attribute:
+.Bd -literal -offset indent
+gpart set -a bootonce -i 2 ada0
+.Ed
+.Sh SEE ALSO
+.Xr rc.conf 5 ,
+.Xr boot 8 ,
+.Xr efibootmgr 8 ,
+.Xr gpart 8 ,
+.Xr gptboot 8 ,
+.Xr loader.efi 8
+.Sh HISTORY
+.Nm
+appeared in
+.Fx 13.0
+.Sh AUTHORS
+This manual page written by
+.An Warner Losh Aq imp@FreeBSD.org .
+It is based heavily on the
+.Xr gptboot 8
+man page by
+.An Warren Block Aq wblock@FreeBSD.org .
diff --git a/stand/i386/gptboot/gptboot.8 b/stand/i386/gptboot/gptboot.8
index 06ccaa37cdce..fa6eecc3cfab 100644
--- a/stand/i386/gptboot/gptboot.8
+++ b/stand/i386/gptboot/gptboot.8
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd April 30, 2019
+.Dd April 6, 2021
 .Dt GPTBOOT 8
 .Os
 .Sh NAME
@@ -39,6 +39,10 @@ is installed in a
 .Cm freebsd-boot
 partition with
 .Xr gpart 8 .
+For UEFI,
+.Xr gptboot.efi 8
+is used instead.
+While conceptually similar, the details differ.
 .Pp
 When it starts,
 .Nm
diff --git a/stand/man/boot1.efi.8 b/stand/man/boot1.efi.8
index 74758a0c5660..efd3c2c93d5e 100644
--- a/stand/man/boot1.efi.8
+++ b/stand/man/boot1.efi.8
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd September 1, 2020
+.Dd April 6, 2021
 .Dt BOOT1.EFI 8
 .Os
 .Sh NAME
@@ -33,13 +33,19 @@
 .Sh DESCRIPTION
 .Nm
 has been deprecated and will be removed from a future release.
-.Xr loader.efi 8 handles all its former use cases with more flexibility.
+.Xr loader.efi 8
+handles all its former use cases with more flexibility.
 .Pp
 On UEFI systems,
 .Nm
 loads
 .Pa /boot/loader.efi
 from the default root file system and transfers execution there.
+Some systems may need to use
+.Xr gptboot.efi 8
+when
+.Xr loader.efi 8
+cannot be used directly on the ESP (EFI System Partition).
 .Ss Initialization
 Before looking for the boot device,
 .Nm
@@ -94,6 +100,10 @@ When configuring a serial console for FreeBSD, but not for UEFI, no output
 will show up on the serial console from boot1.efi.
 .It
 There's no support for marking partitions as the preferred one.
+See
+.Xr gptboot.efi 8 .
 .It
 There's no support for boot-once functionality.
+See
+.Xr gptboot.efi 8 .
 .El