xref: /openbmc/u-boot/doc/README.menu (revision f77d4410) 
1SPDX-License-Identifier: GPL-2.0+
2/*
3 * Copyright 2010-2011 Calxeda, Inc.
4 */
5
6U-Boot provides a set of interfaces for creating and using simple, text
7based menus. Menus are displayed as lists of labeled entries on the
8console, and an entry can be selected by entering its label.
9
10To use the menu code, enable CONFIG_MENU, and include "menu.h" where
11the interfaces should be available.
12
13Menus are composed of items. Each item has a key used to identify it in
14the menu, and an opaque pointer to data controlled by the consumer.
15
16If you want to show a menu, instead starting the shell, define
17CONFIG_MENU_SHOW. You have to code the int menu_show(int bootdelay)
18function, which handle your menu. This function returns the remaining
19bootdelay.
20
21Interfaces
22----------
23#include "menu.h"
24
25/*
26 * Consumers of the menu interfaces will use a struct menu * as the
27 * handle for a menu. struct menu is only fully defined in menu.c,
28 * preventing consumers of the menu interfaces from accessing its
29 * contents directly.
30 */
31struct menu;
32
33/*
34 * NOTE: See comments in common/menu.c for more detailed documentation on
35 * these interfaces.
36 */
37
38/*
39 * menu_create() - Creates a menu handle with default settings
40 */
41struct menu *menu_create(char *title, int timeout, int prompt,
42				void (*item_data_print)(void *),
43				char *(*item_choice)(void *),
44				void *item_choice_data);
45
46/*
47 * menu_item_add() - Adds or replaces a menu item
48 */
49int menu_item_add(struct menu *m, char *item_key, void *item_data);
50
51/*
52 * menu_default_set() - Sets the default choice for the menu
53 */
54int menu_default_set(struct menu *m, char *item_key);
55
56/*
57 * menu_default_choice() - Set *choice to point to the default item's data
58 */
59int menu_default_choice(struct menu *m, void **choice);
60
61/*
62 * menu_get_choice() - Returns the user's selected menu entry, or the
63 * default if the menu is set to not prompt or the timeout expires.
64 */
65int menu_get_choice(struct menu *m, void **choice);
66
67/*
68 * menu_destroy() - frees the memory used by a menu and its items.
69 */
70int menu_destroy(struct menu *m);
71
72/*
73 * menu_display_statusline(struct menu *m);
74 * shows a statusline for every menu_display call.
75 */
76void menu_display_statusline(struct menu *m);
77
78Example Code
79------------
80This example creates a menu that always prompts, and allows the user
81to pick from a list of tools.  The item key and data are the same.
82
83#include "menu.h"
84
85char *tools[] = {
86	"Hammer",
87	"Screwdriver",
88	"Nail gun",
89	NULL
90};
91
92char *pick_a_tool(void)
93{
94	struct menu *m;
95	int i;
96	char *tool = NULL;
97
98	m = menu_create("Tools", 0, 1, NULL);
99
100	for(i = 0; tools[i]; i++) {
101		if (menu_item_add(m, tools[i], tools[i]) != 1) {
102			printf("failed to add item!");
103			menu_destroy(m);
104			return NULL;
105		}
106	}
107
108	if (menu_get_choice(m, (void **)&tool) != 1)
109		printf("Problem picking tool!\n");
110
111	menu_destroy(m);
112
113	return tool;
114}
115
116void caller(void)
117{
118	char *tool = pick_a_tool();
119
120	if (tool) {
121		printf("picked a tool: %s\n", tool);
122		use_tool(tool);
123	}
124}
125