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>

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"))

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,