blob: 2f4882899b6d7769c4447b89af0696b8c67d40c5 [file] [log] [blame]
Simon Glass311bd352023-01-06 08:52:43 -06001.. SPDX-License-Identifier: GPL-2.0+
2
3Expo menu
4=========
5
6U-Boot provides a menu implementation for use with selecting bootflows and
7changing U-Boot settings. This is in early stages of development.
8
9Motivation
10----------
11
12U-Boot already has a text-based menu system accessed via the
13:doc:`../usage/cmd/bootmenu`. This works using environment variables, or via
14some EFI-specific hacks.
15
16The command makes use of a lower-level `menu` implementation, which is quite
17flexible and can be used to make menu hierarchies.
18
19However this system is not flexible enough for use with standard boot. It does
20not support a graphical user interface and cannot currently support anything
21more than a very simple list of items. While it does support multiple menus in
22hierarchies, these are implemented by the caller. See for example `eficonfig.c`.
23
24Another challenge with the current menu implementation is that it controls
25the event loop, such that bootmenu_loop() does not return until a key is
26pressed. This makes it difficult to implement dynamic displays or to do other
27things while the menu is running, such as searching for more bootflows.
28
29For these reasons an attempt has been made to develop a more flexible system
30which can handle menus as well as other elements. This is called 'expo', short
31for exposition, in an attempt to avoid common words like display, screen, menu
32and the like. The primary goal is to support Verified Boot for Embedded (VBE),
33although it is available to any boot method, using the 'bootflow menu' command.
34
35Efforts have been made to use common code with the existing menu, including
36key processing in particular.
37
38Previous work looked at integrating Nuklear into U-Boot. This works fine and
39could provide a way to provide a more flexible UI, perhaps with expo dealing
40with the interface to Nuklear. But this is quite a big step and it may be years
41before this becomes desirable, if at all. For now, U-Boot only needs a fairly
42simple set of menus and options, so rendering them directly is fairly
43straightforward.
44
45Concepts
46--------
47
48The creator of the expo is here called a `controller` and it controls most
49aspects of the expo. This is the code that you must write to use expo.
50
51An `expo` is a set of scenes which can be presented to the user one at a time,
52to show information and obtain input from the user.
53
54A `scene` is a collection of objects which are displayed together on the screen.
55Only one scene is visible at a time and scenes do not share objects.
56
57A `scene object` is something that appears in the scene, such as some text, an
58image or a menu. Objects can be positioned and hidden.
59
60A `menu object` contains a title, a set of `menu items` and a pointer to the
61current item. Menu items consist of a keypress (indicating what to press to
62select the item), label and description. All three are shown in a single line
63within the menu. Items can also have a preview image, which is shown when the
64item is highlighted.
65
66All components have a name. This is purely for debugging, so it is easy to see
67what object is referred to. Of course the ID numbers can help as well, but they
68are less easy to distinguish.
69
70While the expo implementation provides support for handling keypresses and
71rendering on the display or serial port, it does not actually deal with reading
72input from the user, nor what should be done when a particular menu item is
73selected. This is deliberate since having the event loop outside the expo is
74more flexible, particularly in a single-threaded environment like U-Boot.
75
76Everything within an expo has a unique ID number. This is done so that it is
77easy to refer to things after the expo has been created. The expectation is that
78the controller declares an enum containing all of the elements in the expo,
79passing the ID of each object as it is created. When a menu item is selected,
80its ID is returned. When a object's font or position needs to change, the ID is
81passed to expo functions to indicate which object it is. It is possible for expo
82to auto-allocate IDs, but this is not recommended. The use of IDs is a
83convenience, removing the need for the controller to store pointers to objects,
84or even the IDs of objects. Programmatic creation of many items in a loop can be
85handled by allocating space in the enum for a maximum number of items, then
86adding the loop count to the enum values to obtain unique IDs.
87
Simon Glass6e9e4152023-06-01 10:22:47 -060088Where dynamic IDs are need, use expo_set_dynamic_start() to set the start value,
89so that they are allocated above the starting (enum) IDs.
90
Simon Glass311bd352023-01-06 08:52:43 -060091All text strings are stored in a structure attached to the expo, referenced by
92a text ID. This makes it easier at some point to implement multiple languages or
93to support Unicode strings.
94
95Menu objects do not have their own text and image objects. Instead they simply
96refer to objects which have been created. So a menu item is just a collection
97of IDs of text and image objects. When adding a menu item you must create these
98objects first, then create the menu item, passing in the relevant IDs.
99
100Creating an expo
101----------------
102
103To create an expo, use `expo_new()` followed by `scene_new()` to create a scene.
104Then add objects to the scene, using functions like `scene_txt_str()` and
105`scene_menu()`. For every menu item, add text and image objects, then create
106the menu item with `scene_menuitem()`, referring to those objects.
107
108Layout
109------
110
111Individual objects can be positioned using `scene_obj_set_pos()`. Menu items
112cannot be positioned manually: this is done by `scene_arrange()` which is called
113automatically when something changes. The menu itself determines the position of
114its items.
115
116Rendering
117---------
118
119Rendering is performed by calling `expo_render()`. This uses either the
120vidconsole, if present, or the serial console in `text mode`. Expo handles
121presentation automatically in either case, without any change in how the expo is
122created.
123
124For the vidconsole, Truetype fonts can be used if enabled, to enhance the
125quality of the display. For text mode, each menu item is shown in a single line,
126allowing easy selection using arrow keys.
127
128Input
129-----
130
131The controller is responsible for collecting keyboard input. A good way to do
132this is to use `cli_ch_process()`, since it handles conversion of escape
133sequences into keys. However, expo has some special menu-key codes for
134navigating the interface. These are defined in `enum bootmenu_key` and include
135`BKEY_UP` for moving up and `BKEY_SELECT` for selecting an item. You can use
136`bootmenu_conv_key()` to convert an ASCII key into one of these.
137
138Once a keypress is decoded, call `expo_send_key()` to send it to the expo. This
139may cause an update to the expo state and may produce an action.
140
141Actions
142-------
143
144Call `expo_action_get()` in the event loop to check for any actions that the
145expo wants to report. These can include selecting a particular menu item, or
146quitting the menu. Processing of these is the responsibility of your controller.
147
148Event loop
149----------
150
151Expo is intended to be used in an event loop. For an example loop, see
152`bootflow_menu_run()`. It is possible to perform other work in your event loop,
153such as scanning devices for more bootflows.
154
155Themes
156------
157
Simon Glassc999e172023-06-01 10:22:53 -0600158Expo supports simple themes, for setting the font size, for example. Use the
159expo_apply_theme() function to load a theme, passing a node with the required
160properties:
161
162font-size
163 Font size to use for all text (type: u32)
164
Simon Glass311bd352023-01-06 08:52:43 -0600165
166API documentation
167-----------------
168
169.. kernel-doc:: include/expo.h
170
171Future ideas
172------------
173
174Some ideas for future work:
175
176- Default menu item and a timeout
177- Higher-level / automatic / more flexible layout of objects
178- Image formats other than BMP
179- Use of ANSI sequences to control a serial terminal
180- Colour selection
181- Better support for handling lots of settings, e.g. with multiple menus and
182 radio/option widgets
183- Mouse support
184- Integrate Nuklear, NxWidgets or some other library for a richer UI
185- Optimise rendering by only updating the display with changes since last render
186- Use expo to replace the existing menu implementation
187- Add a Kconfig option to drop the names to save code / data space
188- Add a Kconfig option to disable vidconsole support to save code / data space
189- Support both graphical and text menus at the same time on different devices
Simon Glass311bd352023-01-06 08:52:43 -0600190- Support unicode
191- Support curses for proper serial-terminal menus
192
193.. Simon Glass <sjg@chromium.org>
194.. 7-Oct-22