From: Simon Glass <sjg@chromium.org>
Date: Fri, 6 Jan 2023 14:52:21 +0000 (-0600)
Subject: bootmenu: Add a few comments
X-Git-Tag: v2025.01-rc5-pxa1908~1146^2~22
X-Git-Url: http://git.dujemihanovic.xyz/login.html?a=commitdiff_plain;h=ee6c7eb46f3835a027e8e7278418683ff7a32031;p=u-boot.git

bootmenu: Add a few comments

The behaviour of these two functions is completely undocumented. Add some
notes so the poor, suffering dev can figure out what is going on.

Signed-off-by: Simon Glass <sjg@chromium.org>
---

diff --git a/include/menu.h b/include/menu.h
index 702aacb170..0b4d973414 100644
--- a/include/menu.h
+++ b/include/menu.h
@@ -42,6 +42,7 @@ struct bootmenu_data {
 	struct bootmenu_entry *first;	/* first menu entry */
 };
 
+/** enum bootmenu_key - keys that can be returned by the bootmenu */
 enum bootmenu_key {
 	KEY_NONE = 0,
 	KEY_UP,
@@ -53,8 +54,49 @@ enum bootmenu_key {
 	KEY_SPACE,
 };
 
+/**
+ * bootmenu_autoboot_loop() - handle autobooting if no key is pressed
+ *
+ * This shows a prompt to allow the user to press a key to interrupt auto boot
+ * of the first menu option.
+ *
+ * It then waits for the required time (menu->delay in seconds) for a key to be
+ * pressed. If nothing is pressed in that time, @key returns KEY_SELECT
+ * indicating that the current option should be chosen.
+ *
+ * @menu: Menu being processed
+ * @key: Returns the code for the key the user pressed:
+ *	enter: KEY_SELECT
+ *	Ctrl-C: KEY_QUIT
+ *	anything else: KEY_NONE
+ * @esc: Set to 1 if the escape key is pressed, otherwise not updated
+ */
 void bootmenu_autoboot_loop(struct bootmenu_data *menu,
 			    enum bootmenu_key *key, int *esc);
+
+/**
+ * bootmenu_loop() - handle waiting for a keypress when autoboot is disabled
+ *
+ * This is used when the menu delay is negative, indicating that the delay has
+ * elapsed, or there was no delay to begin with.
+ *
+ * It reads a character and processes it, returning a menu-key code if a
+ * character is recognised
+ *
+ * @menu: Menu being processed
+ * @key: Returns the code for the key the user pressed:
+ *	enter: KEY_SELECT
+ *	Ctrl-C: KEY_QUIT
+ *	Up arrow: KEY_UP
+ *	Down arrow: KEY_DOWN
+ *	Escape (by itself): KEY_QUIT
+ *	Plus: KEY_PLUS
+ *	Minus: KEY_MINUS
+ *	Space: KEY_SPACE
+ * @esc: On input, a non-zero value indicates that an escape sequence has
+ *	resulted in that many characters so far. On exit this is updated to the
+ *	new number of characters
+ */
 void bootmenu_loop(struct bootmenu_data *menu,
 		   enum bootmenu_key *key, int *esc);