git: 7b3fb3caef94 - main - loader.efi(8): clarify UEFI boot path and boot1.efi usage

The branch main has been updated by imp:

URL: https://cgit.FreeBSD.org/src/commit/?id=7b3fb3caef9495cdfcc1c8ec39907defb65ce860

commit 7b3fb3caef9495cdfcc1c8ec39907defb65ce860
Author:     kitkat1424 <aadityavksingh@gmail.com>
AuthorDate: 2025-12-31 19:41:08 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
CommitDate: 2026-01-09 21:16:24 +0000

    loader.efi(8): clarify UEFI boot path and boot1.efi usage
    
    Reorganise and clarify the legacy role of boot1.efi in DESCRIPTION to
    improve clarity.
    
    Add a minor missing word in the BUGS section ["...caution is required*..."].
    
    See also - PR: 290794
    
    Signed-off-by: Aaditya Singh <aadityavksingh@gmail.com>
    Reviewed by: imp
    Pull Request: https://github.com/freebsd/freebsd-src/pull/1939
---
 stand/man/loader.efi.8 | 47 +++++++++++++++++++++++------------------------
 1 file changed, 23 insertions(+), 24 deletions(-)

diff --git a/stand/man/loader.efi.8 b/stand/man/loader.efi.8
index d9a5c827ba71..80d16d45670a 100644
--- a/stand/man/loader.efi.8
+++ b/stand/man/loader.efi.8
@@ -41,20 +41,28 @@ On UEFI systems,
 .Nm
 loads the kernel.
 .Pp
-.Xr boot1.efi 8
-is used to load
-.Nm
-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 as described in
-.Xr uefi 8 .
-When a system is built using
+is invoked directly from the EFI System Partition (ESP)
+on systems installed using
 .Xr bsdinstall 8 ,
-.Nm
-will be used directly.
+when installed as the default EFI boot program as described in
+.Xr uefi 8
+or when configured as an EFI boot entry with
+.Xr efibootmgr 8 .
+.Pp
+On systems upgraded from FreeBSD 10 or earlier, the EFI System Partition (ESP)
+can be too small to accommodate
+.Nm .
+In such cases,
+.Xr boot1.efi 8
+may be retained as the firmware boot program. It
+will chain-load the current
+.Pa /boot/loader.efi ,
+which is updated during the
+.Cm installworld
+process.
+.Xr boot1.efi 8
+is deprecated for new installations.
 .Ss Console Considerations
 The EFI BIOS provides a generic console.
 In
@@ -485,15 +493,6 @@ Typically in these embedded situations, there is only one .efi file (loader.efi
 or a copy of loader.efi).
 The path to this file is typically the default removable path above.
 .Pp
-Managing booting multiple OSes on UEFI varies greatly, so extra caution when
-updating the UEFI default loader.
-.Pp
-The old, now obsolete, boot1.efi was installed as bootx64.efi in
-.Fx 10
-and earlier.
-Since it was quite limited in functionality, we created very small
-ESPs by default.
-A modern loader.efi will not fit.
-However, if the old boot1.efi still works, there's no need to update
-it since it will chain boot /boot/loader.efi from a copy that
-make installworld updates.
+Managing booting multiple OSes on UEFI varies greatly, so extra caution is required
+when updating the UEFI default loader.
+.Pp