git: 0cd612664eba - main - UPDATING: update notes on EFI booting

The branch main has been updated by imp:

URL: https://cgit.FreeBSD.org/src/commit/?id=0cd612664ebaeaf960ffc8ebe4d3ff44be2a8eef

commit 0cd612664ebaeaf960ffc8ebe4d3ff44be2a8eef
Author:     Warner Losh <imp@FreeBSD.org>
AuthorDate: 2023-01-20 23:13:54 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
CommitDate: 2023-01-20 23:13:54 +0000

    UPDATING: update notes on EFI booting
    
    The notes on EFI booting and updating for ZFS had become dated and only
    partially updated. Expand the notes with a few more details and a
    pointer to laoder.efi(8) and uefi(8).
    
    Sponsored by:           Netflix
    Discussed with:         pauamma, karels
    Differential Revision:  https://reviews.freebsd.org/D36629
---
 UPDATING | 46 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 37 insertions(+), 9 deletions(-)

diff --git a/UPDATING b/UPDATING
index a0fdb839f668..689ddfedf6d3 100644
--- a/UPDATING
+++ b/UPDATING
@@ -2528,22 +2528,50 @@ COMMON ITEMS:
 
 	ZFS notes
 	---------
-	When upgrading the boot ZFS pool to a new version, always follow
-	these two steps:
+	When upgrading the boot ZFS pool to a new version (via zpool upgrade),
+	always follow these three steps:
 
-	1.) recompile and reinstall the ZFS boot loader and boot block
+	1) recompile and reinstall the ZFS boot loader and boot block
 	(this is part of "make buildworld" and "make installworld")
 
-	2.) update the ZFS boot block on your boot drive
+	2) update the ZFS boot block on your boot drive (only required when
+	doing a zpool upgrade):
 
-	The following example updates the ZFS boot block on the
-	freebsd-boot partition of a GPT partitioned drive ada0:
-	"gpart bootcode -p /boot/gptzfsboot -i $N ada0"
-	The value $N will typically be 1 (if booting from BIOS) or 2 (if
-	booting from EFI).
+	When booting on x86 via BIOS, use the following to update the ZFS boot
+	block on the freebsd-boot partition of a GPT partitioned drive ada0:
+		gpart bootcode -p /boot/gptzfsboot -i $N ada0
+	The value $N will typically be 1.  For EFI booting, see EFI notes.
+
+	3) zpool upgrade the root pool. New bootblocks will work with old
+	pools, but not vice versa, so they need to be updated before any
+	zpool upgrade.
 
 	Non-boot pools do not need these updates.
 
+	EFI notes
+	---------
+
+	There are two locations the boot loader can be installed into. The
+	current location (and the default) is \efi\freebsd\loader.efi and using
+	efibootmgr(8) to configure it. The old location, that must be used on
+	deficient systems that don't honor efibootmgr(8) protocols, is the
+	fallback location of \EFI\BOOT\BOOTxxx.EFI. Generally, you will copy
+	/boot/loader.efi to this location, but on systems installed a long time
+	ago the ESP may be too small and /boot/boot1.efi may be needed unless
+	the ESP has been expanded in the meantime.
+
+	Recent systems will have the ESP mounted on /boot/efi, but older ones
+	may not have it mounted at all, or mounted in a different
+	location. Older arm SD images with MBR used /boot/msdos as the
+	mountpoint. The ESP is a MSDOS filesystem.
+
+	The EFI boot loader rarely needs to be updated. For ZFS booting,
+	however, you must update loader.efi before you do 'zpool upgrade' the
+	root zpool, otherwise the old loader.efi may reject the upgraded zpool
+	since it does not automatically understand some new features.
+
+	See loader.efi(8) and uefi(8) for more details.
+
 	To build a kernel
 	-----------------
 	If you are updating from a prior version of FreeBSD (even one just