git: 3bd3b6b9fe4f - stable/15 - loader.efi(8): Document LoaderEnv and NextLoaderEnv EFI variables

The branch stable/15 has been updated by 0mp:

URL: https://cgit.FreeBSD.org/src/commit/?id=3bd3b6b9fe4f221a90a1bea2817d6c4a5f0b51a3

commit 3bd3b6b9fe4f221a90a1bea2817d6c4a5f0b51a3
Author:     Paarth Shirsat <paarthshirsat123@gmail.com>
AuthorDate: 2026-04-25 15:10:27 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2026-06-15 08:55:26 +0000

    loader.efi(8): Document LoaderEnv and NextLoaderEnv EFI variables
    
    Describe how the LoaderEnv and NextLoaderEnv variables can be used.
    
    PR:                     293054
    Reviewed by:            imp
    Sponsored by:           Wiesbaden Hackathon 202604
    Differential Revision:  https://reviews.freebsd.org/D56633
    
    (cherry picked from commit 4137c673fa963fdf409eba2f48d615350c988ffe)
---
 stand/man/loader.efi.8 | 41 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 4 deletions(-)

diff --git a/stand/man/loader.efi.8 b/stand/man/loader.efi.8
index 9ff31b02dcb6..d9ee55ee192e 100644
--- a/stand/man/loader.efi.8
+++ b/stand/man/loader.efi.8
@@ -217,14 +217,47 @@ functionality where we use the video console if a keyboard is connected and a
 serial console otherwise.
 .Ss Additional Environment Variables
 .Nm
-loads some extra variables early in startup from
-.Pa /efi/freebsd/loader.env
-from the EFI partition.
-Only simple variables can be set here.
+can set variables early in startup from a file on the EFI partition.
+By default, that file is
+.Pa /efi/freebsd/loader.env .
+It can be changed by setting the FreeBSD EFI variable
+.Va LoaderEnv ,
+as in:
+.Bd -literal -offset indent
+echo -n /efi/freebsd/alt.env | efivar -w -t 7 \\
+    -n cfee69ad-a0de-47a9-93a8-f63106f8ae99-LoaderEnv
+.Ed
+.Pp
+After that is executed, the file
+.Pa /efi/freebsd/alt.env
+is used instead of
+.Pa /efi/freebsd/loader.env .
+See
+.Xr efivar 8
+for more information on setting EFI variables.
+.Pp
+The EFI variable
+.Va NextLoaderEnv
+can be set to the pathname of a second startup file.
+That variable is deleted immediately after its value is retrieved,
+so setting it will affect only the next boot attempt.
+For either variable, a missing file is silently ignored.
+.Pp
+Only simple variables can be set in the startup file.
 It can be useful to specify the root filesystem:
 .Bd -literal -offset indent
 rootdev=disk0s1a
 .Ed
+.Pp
+The startup file contains a series of assignments separated by spaces,
+tabs, or newlines.
+Quotes are not given any special treatment.
+If no
+.Li =value
+is given, the value
+.Li 1
+is used.
+Invalid syntax and the like are silently ignored.
 .Ss Staging Slop
 The kernel must parse the firmware memory map tables to know what memory
 it can use.