From: Emil Velikov <emil.velikov@collabora.com>
Date: Thu, 12 Oct 2023 15:24:12 +0000 (+0100)
Subject: bootctl, sd-boot: cross document the menu-hidden/force ABI
X-Git-Tag: v255-rc1~216^2~1
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=5b45fad4fcfa2dd81f25b13fe8d7717f62fa5843;p=thirdparty%2Fsystemd.git

bootctl, sd-boot: cross document the menu-hidden/force ABI

Document the current state and how we got here.

v2:
 - rewrap command to 109 columns

Signed-off-by: Emil Velikov <emil.velikov@collabora.com>
---

diff --git a/src/boot/bootctl-set-efivar.c b/src/boot/bootctl-set-efivar.c
index 9feb0e3d2ea..71507c1e1da 100644
--- a/src/boot/bootctl-set-efivar.c
+++ b/src/boot/bootctl-set-efivar.c
@@ -20,6 +20,10 @@ static int parse_timeout(const char *arg1, char16_t **ret_timeout, size_t *ret_t
         assert(ret_timeout);
         assert(ret_timeout_size);
 
+        /* Note: Since there is no way to query if the booloader supports the string tokens, we explicitly
+         * set their numerical value(s) instead. This means that some of the sd-boot internal ABI has leaked
+         * although the ship has sailed and the side-effects are self-contained.
+         */
         if (streq(arg1, "menu-force"))
                 timeout = USEC_INFINITY;
         else if (streq(arg1, "menu-hidden"))
diff --git a/src/boot/efi/boot.c b/src/boot/efi/boot.c
index 41814535b43..43891df9348 100644
--- a/src/boot/efi/boot.c
+++ b/src/boot/efi/boot.c
@@ -101,9 +101,16 @@ typedef struct {
         int64_t console_mode_efivar;
 } Config;
 
-/* These values have been chosen so that the transitions the user sees could
- * employ unsigned over-/underflow like this:
- * efivar unset ↔ force menu ↔ no timeout/skip menu ↔ 1 s ↔ 2 s ↔ … */
+/* These values have been chosen so that the transitions the user sees could employ unsigned over-/underflow
+ * like this:
+ * efivar unset ↔ force menu ↔ no timeout/skip menu ↔ 1 s ↔ 2 s ↔ …
+ *
+ * Note: all the values below are ABI, so they are not allowed to change. The bootctl tool sets the numerical
+ * value of TIMEOUT_MENU_FORCE and TIMEOUT_MENU_HIDDEN, instead of the string for compatibility reasons.
+ *
+ * The other values may be set by systemd-boot itself and changing those will lead to functional regression
+ * when new version of systemd-boot is installed.
+ */
 enum {
         TIMEOUT_MIN         = 1,
         TIMEOUT_MAX         = UINT32_MAX - 2U,