Add generic, reusable menu code

This will be used first by the pxecfg code, but is intended to be
generic and reusable for other jobs in U-boot.

Signed-off-by: Jason Hobbs <jason.hobbs@calxeda.com>

1 files changed, 158 insertions, 0 deletions

diff --git a/doc/README.menu b/doc/README.menu
new file mode 100644
index 000000000..bca44be3f
--- /dev/null
+++ b/doc/README.menu
@@ -0,0 +1,158 @@
+/*
+ * Copyright 2010-2011 Calxeda, Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+U-boot provides a set of interfaces for creating and using simple, text
+based menus. Menus are displayed as lists of labeled entries on the
+console, and an entry can be selected by entering its label.
+
+To use the menu code, enable CONFIG_MENU, and include "menu.h" where
+the interfaces should be available.
+
+Menus are composed of items. Each item has a key used to identify it in
+the menu, and an opaque pointer to data controlled by the consumer.
+
+Interfaces
+----------
+#include "menu.h"
+
+struct menu;
+
+struct menu *menu_create(char *title, int prompt,
+				void (*item_data_print)(void *));
+int menu_item_add(struct menu *m, char *item_key, void *item_data);
+int menu_default_set(struct menu *m, char *item_key);
+int menu_get_choice(struct menu *m, void **choice);
+int menu_destroy(struct menu *m);
+
+menu_create() - Creates a menu handle with default settings
+
+  title - If not NULL, points to a string that will be displayed before
+  the list of menu items. It will be copied to internal storage, and is
+  safe to discard after passing to menu_create().
+
+  prompt - If 0, don't ask for user input. If 1, the user will be ed for
+  promptinput.
+
+  item_data_print - If not NULL, will be called for each item when
+  the menu is displayed, with the pointer to the item's data passed
+  as the argument. If NULL, each item's key will be printed instead.
+  Since an item's key is what must be entered to select an item, the
+  item_data_print function should make it obvious what the key for each
+  entry is.
+
+  Returns a pointer to the menu if successful, or NULL if there is
+  insufficient memory available to create the menu.
+
+
+menu_item_add() - Adds or replaces a menu item
+
+  m - Points to a menu created by menu_create().
+
+  item_key - Points to a string that will uniquely identify the item.
+  The string will be copied to internal storage, and is safe to discard
+  after passing to menu_item_add.
+
+  item_data - An opaque pointer associated with an item. It is never
+  dereferenced internally, but will be passed to the item_data_print,
+  and will be returned from menu_get_choice if the menu item is
+  selected.
+
+  Returns 1 if successful, -EINVAL if m is NULL, or -ENOMEM if there is
+  insufficient memory to add the menu item.
+
+
+menu_default_set() - Sets the default choice for the menu. This is safe
+to call more than once.
+
+  m - Points to a menu created by menu_create().
+
+  item_key - Points to a string that, when compared using strcmp,
+  matches the key for an existing item in the menu.
+
+  Returns 1 if successful, -EINVAL if m is NULL, or -ENOENT if no item
+  with a key matching item_key is found.
+
+
+menu_get_choice() - Returns the user's selected menu entry, or the
+default if the menu is set to not prompt. This is safe to call more than
+once.
+
+  m - Points to a menu created by menu_create().
+
+  choice - Points to a location that will store a pointer to the
+  selected menu item. If no item is selected or there is an error, no
+  value will be written at the location it points to.
+
+  Returns 1 if successful, -EINVAL if m or choice is NULL, -ENOENT if no
+  default has been set and the menu is set to not prompt, or -EINTR if
+  the user exits the menu via ctrl+c.
+
+
+menu_destroy() - frees the memory used by a menu and its items.
+
+  m - Points to a menu created by menu_create().
+
+  Returns 1 if successful, or -EINVAL if m is NULL.
+
+
+Example
+-------
+This example creates a menu that always prompts, and allows the user
+to pick from a list of tools.  The item key and data are the same.
+
+#include "menu.h"
+
+char *tools[] = {
+	"Hammer",
+	"Screwdriver",
+	"Nail gun",
+	NULL
+};
+
+char *pick_a_tool(void)
+{
+	struct menu *m;
+	int i;
+	char *tool = NULL;
+
+	m = menu_create("Tools", 1, NULL);
+
+	for(i = 0; tools[i]; i++) {
+		if (menu_item_add(m, tools[i], tools[i]) != 1) {
+			printf("failed to add item!");
+			menu_destroy(m);
+			return NULL;
+                }
+	}
+
+	if (menu_get_choice(m, (void **)&tool) != 1)
+		printf("Problem picking tool!\n");
+
+	menu_destroy(m);
+
+	return tool;
+}
+
+void caller(void)
+{
+	char *tool = pick_a_tool();
+
+	if (tool) {
+		printf("picked a tool: %s\n", tool);
+		use_tool(tool);
+	}
+}