Update grub.texi to describe the external environment block in the
reserved area of Btrfs header used for grub-reboot and savedefault, and
add a section documenting the saved_entry, next_entry, and env_block
variables.
Signed-off-by: Michael Chang <mch...@suse.com>
---
docs/grub.texi | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 60 insertions(+)
diff --git a/docs/grub.texi b/docs/grub.texi
index 34b3484dc..6ffb3a370 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -3271,6 +3271,7 @@ GRUB. Others may be used freely in GRUB configuration
files.
@menu
* Special environment variables::
* Environment block::
+* Special environment block variables::
@end menu
@@ -3868,9 +3869,68 @@ For safety reasons, this storage is only available when
installed on a plain
disk (no LVM or RAID), using a non-checksumming filesystem (no ZFS), and
using BIOS or EFI functions (no ATA, USB or IEEE1275).
+On Btrfs filesystems, a reserved area in the filesystem header may be used to
+store the environment block. This static block avoids the problems of updating
+a normal file on a copy-on-write filesystem, where writing raw block is not
+stable and requires metadata update. The reserved area provides a fixed
+location that GRUB can update directly, allowing commands such as
+@command{grub-reboot} and @samp{GRUB_SAVEDEFAULT} to function correctly on
+Btrfs volumes.
+
@command{grub-mkconfig} uses this facility to implement
@samp{GRUB_SAVEDEFAULT} (@pxref{Simple configuration}).
+
+@node Special environment block variables
+@section Special environment block variables
+
+These special variables are usually written to the environment block
+(@pxref{Environment block}) to customize the behavior of @file{grub.cfg}
+generated by @command{grub-mkconfig}.
+
+@menu
+* saved_entry::
+* next_entry::
+* env_block::
+@end menu
+
+
+@node saved_entry
+@subsection saved_entry
+
+The @var{saved_entry} variable sets the default boot entry in @file{grub.cfg}
+created by @command{grub-mkconfig}. It can be set with
+@command{grub-set-default} to choose a default entry, or at runtime with the
+@code{savedefault} function in grub.cfg to save the current entry as the new
+default. This may require write access by GRUB.
+
+
+@node next_entry
+@subsection next_entry
+
+The @var{next_entry} variable sets the boot entry for the next boot only. After
+it is used, GRUB clears the value so it is not reused. This requires write
+access to the environment block (@pxref{Environment block}) at runtime. The
+@command{grub-reboot} command is usually used instead of changing this variable
+directly.
+
+
+@node env_block
+@subsection env_block
+
+If the filesystem is Btrfs and the disk is not an abstracted device such as
+LVM, RAID, or encryption, the reserved space in the Btrfs header can be used as
+the environment block (@pxref{Environment block}). This provides a fixed raw
+block that GRUB can reliably write to. The @var{env_block} records this
+location in GRUB blocklist syntax (@pxref{Block list syntax}) so that
+@command{grub-editenv} and @file{grub.cfg} know how to access and use the
+external raw block.
+
+This variable is initialized when @file{grubenv} is first created by
+@command{grub-editenv} and is treated as read-only to avoid being overwritten
+with an unpredictable value.
+
+
@node Modules
@chapter Modules
--
2.51.0
_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel
