bootenv: reorganise and document

In 99d7453 I split out the "OS-specific" zfs_bootenv_os.h for
userspace, added a placeholder "posix" vendor and set BOOTENV_OS to use
it by default. This turned out to be the wrong thing to do. BOOTENV_OS
is not actually OS-specific but rather, part of a protocol coordinating
behaviour between libzfsbootenv and the bootloader. So, all bootenv keys
now get prefixed with posix:, and their respective loaders can no longer
find them[1].

Reverting would have been straightforward, however, I am more interested
in trying to reorganise libzfsbootenv and surrounds to provide all the
pieces a loader, its support tools and the kernel module need in order
to have agreement on how to communicate with each other. This commit is
attempting that rework.

The two goals here are:

- it should be possible to set and get the loader prefix in
  libzfsbootenv at run time, allowing the possibility for the library to
  work on loader prefixes other than the one it was compiled with.

- a loader is a constrained environment, and so should be able to get
  all the config it needs from a single header that libzfsbootenv and
  the kernel at least default to using.

FreeBSD (and illumos, which borrows heavily from it) is the only system
out there that currently has this tight integration between loader,
kernel and tools, so it is the obvious target to focus on here, but I'm
also trying to clearly draw the lines for future systems.

First, we remove sys/zfs_bootenv.h and the various sys/zfs_bootenv_os.h.
This is not really a public API, and as discussed, is not the proper way
to target a loader anyway.

The important macros for a consumer have been moved to fs/zfs.h as
public and supported names. These are the minimum necessary to use
libzfsbootenv (actually lzc_get_bootenv/lzc_set_bootenv) effectively
anyway, and since they live in headers, a standalone loader can make use
of them.

Here we have macros nvlist keys for "known" loaders, and for
common/known bootenv vars. Worth noting that only "bootonce" is
currently used in libzfsbootenv proper, but listing them out at least
makes sure they're documented and we can encourage future systems to do
it the same way.

libzfsbootenv gains an internal notion of the current loader, just the
string prefix. Two new functions are added, lzbe_set_loader() and
lzbe_get_loader(), allowing runtime changes. By compiler define, we set
the default on FreeBSD and illumos to the matching macro from fs/zfs.h,
and "unknown" otherwise. This should keep existing consumers working
without change.

The rest is simple cleanup.

Sponsored-by: https://despairlabs.com/sponsor/
Signed-off-by: Rob Norris <[email protected]>

1. https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=291211

Author: robn

include/Makefile.am

@@ -123,7 +123,6 @@ COMMON_H = \
 	sys/zcp_set.h \
 	sys/zfeature.h \
 	sys/zfs_acl.h \
-	sys/zfs_bootenv.h \
 	sys/zfs_chksum.h \
 	sys/zfs_context.h \
 	sys/zfs_debug.h \

include/libzfsbootenv.h

@@ -12,6 +12,7 @@
 
 /*
  * Copyright 2020 Toomas Soome <[email protected]>
+ * Copyright (c) 2025, Rob Norris <[email protected]>
  */
 
 #ifndef _LIBZFSBOOTENV_H
@@ -36,6 +37,8 @@ _LIBZFSBOOTENV_H int lzbe_set_boot_device(const char *, lzbe_flags_t,
     const char *);
 _LIBZFSBOOTENV_H int lzbe_get_boot_device(const char *, char **);
 _LIBZFSBOOTENV_H int lzbe_bootenv_print(const char *, const char *, FILE *);
+_LIBZFSBOOTENV_H const char *lzbe_loader_get(void);
+_LIBZFSBOOTENV_H int lzbe_loader_set(const char *, size_t);
 
 #ifdef __cplusplus
 }

include/os/freebsd/Makefile.am

@@ -82,7 +82,6 @@ noinst_HEADERS = \
 	%D%/zfs/sys/freebsd_event.h \
 	%D%/zfs/sys/trace_zfs.h \
 	%D%/zfs/sys/vdev_os.h \
-	%D%/zfs/sys/zfs_bootenv_os.h \
 	%D%/zfs/sys/zfs_context_os.h \
 	%D%/zfs/sys/zfs_ctldir.h \
 	%D%/zfs/sys/zfs_debug_os.h \

include/os/freebsd/zfs/sys/zfs_bootenv_os.h

@@ -38,7 +38,6 @@ kernel_sys_HEADERS = \
 	%D%/zfs/sys/trace_zil.h \
 	%D%/zfs/sys/trace_zio.h \
 	%D%/zfs/sys/trace_zrlock.h \
-	%D%/zfs/sys/zfs_bootenv_os.h \
 	%D%/zfs/sys/zfs_context_os.h \
 	%D%/zfs/sys/zfs_ctldir.h \
 	%D%/zfs/sys/zfs_debug_os.h \

include/os/linux/Makefile.am

@@ -32,6 +32,7 @@
  * Copyright (c) 2021, Colm Buckley <[email protected]>
  * Copyright (c) 2022 Hewlett Packard Enterprise Development LP.
  * Copyright (c) 2024, Klara, Inc.
+ * Copyright (c) 2025, Rob Norris <[email protected]>
  */
 
 #ifndef	_SYS_FS_ZFS_H
@@ -2003,6 +2004,41 @@ enum zio_encrypt {
 	    ZFS_XA_NS_PREFIX_MATCH(LINUX_TRUSTED, name) || \
 	    ZFS_XA_NS_PREFIX_MATCH(LINUX_USER, name))
 
+
+/*
+ * Boot environment support. The vdev environment block is accessed with the
+ * ZFS_IOC_GET_BOOTENV and ZFS_IOC_SET_BOOTENV calls. libzfsbootenv uses these
+ * internally, and is the preferred way to work with boot environments, but
+ * these defines are provided here to assist bootloaders and tools that want to
+ * do their own thing.
+ */
+
+#define	ZFS_BE_VERSION		"version"
+enum zfs_bootenv_version {
+	ZFS_BE_VERSION_GRUBENV	= 0,	/* GRUB "grubenv" file */
+	ZFS_BE_VERSION_NVLIST	= 1,	/* arbitrary packed nvlist */
+};
+
+/* nvlist key for GRUB "grubenv" string */
+#define	ZFS_BE_GRUB_ENVMAP	"grub:envmap"
+
+/*
+ * Keys in NVLIST bootenvs should be prefixed with a loader-specific string,
+ * allowing the envblock to support multiple loaders.
+ *
+ * This is the list of known loader prefixes.
+ */
+#define	ZFS_BE_LOADER_FREEBSD	"freebsd"
+#define	ZFS_BE_LOADER_ILLUMOS	"illumos"
+
+/*
+ * Common bootenv keys, to be combined with the loader prefix. New loaders are
+ * encouraged to use these where appropriate to assist cross-platform interop.
+ */
+#define	ZFS_BE_BOOTONCE		"bootonce"
+#define	ZFS_BE_BOOTONCE_USED	"bootonce-used"
+#define	ZFS_BE_NVSTORE		"nvstore"
+
 #ifdef	__cplusplus
 }
 #endif

include/os/linux/zfs/sys/zfs_bootenv_os.h

@@ -503,26 +503,6 @@ typedef struct vdev_phys {
 	zio_eck_t	vp_zbt;
 } vdev_phys_t;
 
-typedef enum vbe_vers {
-	/*
-	 * The bootenv file is stored as ascii text in the envblock.
-	 * It is used by the GRUB bootloader used on Linux to store the
-	 * contents of the grubenv file. The file is stored as raw ASCII,
-	 * and is protected by an embedded checksum. By default, GRUB will
-	 * check if the boot filesystem supports storing the environment data
-	 * in a special location, and if so, will invoke filesystem specific
-	 * logic to retrieve it. This can be overridden by a variable, should
-	 * the user so desire.
-	 */
-	VB_RAW = 0,
-
-	/*
-	 * The bootenv file is converted to an nvlist and then packed into the
-	 * envblock.
-	 */
-	VB_NVLIST = 1
-} vbe_vers_t;
-
 typedef struct vdev_boot_envblock {
 	uint64_t	vbe_version;
 	char		vbe_bootenv[VDEV_PAD_SIZE - sizeof (uint64_t) -

include/sys/fs/zfs.h

@@ -5,10 +5,10 @@ lib_LTLIBRARIES += libzfsbootenv.la
 CPPCHECKTARGETS += libzfsbootenv.la
 
 libzfsbootenv_la_CPPFLAGS  = $(AM_CPPFLAGS)
-libzfsbootenv_la_CPPFLAGS += -I$(srcdir)/include/os/@ac_system_l@/zfs
 
 dist_libzfsbootenv_la_SOURCES = \
 	%D%/lzbe_device.c \
+	%D%/lzbe_loader.c \
 	%D%/lzbe_pair.c \
 	%D%/lzbe_util.c
 
@@ -22,7 +22,7 @@ if !ASAN_ENABLED
 libzfsbootenv_la_LDFLAGS += -Wl,-z,defs
 endif
 
-libzfsbootenv_la_LDFLAGS += -version-info 1:0:0
+libzfsbootenv_la_LDFLAGS += -version-info 2:0:1
 
 pkgconfig_DATA += %D%/libzfsbootenv.pc