git: 692cbd9565 - main - 14.0 relnotes: add other cases to bootcode update section

The branch main has been updated by karels:

URL: https://cgit.FreeBSD.org/doc/commit/?id=692cbd956506078b3a24de98819409ef7ab4c52d

commit 692cbd956506078b3a24de98819409ef7ab4c52d
Author:     Mike Karels <karels@FreeBSD.org>
AuthorDate: 2023-11-29 17:15:11 +0000
Commit:     Mike Karels <karels@FreeBSD.org>
CommitDate: 2023-11-29 17:15:11 +0000

    14.0 relnotes: add other cases to bootcode update section
    
    Address updating bootcode on BIOS-based systems.  Add an intro
    with general considerations, and mentioning the cases.  BIOS info
    based on draft by ale@.  Update recommendations.
    
    Reviewed by:    carlavilla, imp
    Differential Revision:  https://reviews.freebsd.org/D42789
---
 website/content/en/releases/14.0R/relnotes.adoc | 26 +++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/website/content/en/releases/14.0R/relnotes.adoc b/website/content/en/releases/14.0R/relnotes.adoc
index e12c004fe1..2c2e98f487 100644
--- a/website/content/en/releases/14.0R/relnotes.adoc
+++ b/website/content/en/releases/14.0R/relnotes.adoc
@@ -63,11 +63,14 @@ Note that freebsd-update cannot be used to roll back to the previous release aft
 
 Source-based upgrades (those based on recompiling the FreeBSD base system from source code) from previous versions are supported, according to the instructions in [.filename]#/usr/src/UPDATING#.
 
-Note for systems that boot via EFI, using either binary or source upgrades:
+There have been a number of improvements in the boot loaders, and upgrading the boot loader on the boot partition is recommended in most cases, in particular if the system boots via EFI.
+If the root is on a ZFS file system, updating the boot loader is mandatory if the pool is to be upgraded, and the boot loader update must be done first.
+Note that ZFS pool upgrades are not recommended for root file systems in most cases, but updating the boot loader can avoid making the system unbootable if the pool is upgraded in the future.
+The bootstrap update procedure depends on the boot method (EFI or BIOS), and also on the disk partitioning scheme.
+The next several sections address each in turn.
+
+Notes for systems that boot via EFI, using either binary or source upgrades:
 There are one or more copies of the boot loader on the MS-DOS EFI System Partition (ESP), used by the firmware to boot the kernel.
-If the root file system is ZFS, the boot loader must be able to support reading from the ZFS boot file system.
-After a system upgrade, but before doing a `zpool upgrade`, the boot loader on the ESP must be updated, or the system may become unbootable.
-While not mandatory, this update procedure should also be followed when using a UFS root file system.
 The location of the boot loader in use can be determined using the command `efibootmgr -v`.
 The value displayed for `BootCurrent` should be the number of the current boot configuration used to boot the system.
 The corresponding entry of the output should begin with a `+` sign, such as
@@ -85,6 +88,21 @@ If the mount point is [.filename]#/boot/efi#, this file will translate to `/boot
 Another common value for `File` would be `\EFI\boot\bootXXX.efi`, where `XXX` is `x64` for amd64, `aa64` for aarch64, or `riscv64` for riscv64; this is the default bootstrap if none is configured.
 Both the configured and default boot loaders should be updated by copying from [.filename]#/boot/loader.efi# to the correct path in [.filename]#/boot/efi#.
 
+For systems that boot via BIOS and use the GPT partition scheme, bootstrap upgrades are optional unless a ZFS root pool will be upgraded (which is discouraged).
+Upgrades are only possible if the `freebsd-boot` partition is at least 180K.
+(512K is now standard.)
+The device name and the partition index can be identified using the command `gpart show`, such as:
+
+ =>       34  246162605  ada0  GPT  (224G)
+          34       1024     1  freebsd-boot  (512K)
+
+When using ZFS, the bootcode can be updated by running the command `gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0`.
+If updating with a UFS root, the bootcode can be updated by running the command `gpart bootcode -b /boot/pmbr -p /boot/gptboot -i 1 ada0`, although this should not be necessary.
+Note that the `freebsd-boot` partition size is running up against a hard limit, and this scheme may not be supportable in the future.
+Users of such systems should consider an upgrade to EFI, possibly by carving space from an existing swap partition.
+
+If the systems boots via BIOS and uses the MBR partition scheme, or has a GPT `freebsd-boot` partition smaller than 256K, then it is not possible to update the bootcode, and therefore to upgrade the root ZFS storage pool.
+
 [IMPORTANT]
 ====
 Upgrading FreeBSD should only be attempted after backing up _all_ data and configuration files.