blob: f7b636e5fc628b2df1f301af5a0b3731c4d2900f [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
Simon Glass00f6c402023-10-01 19:13:40 -060066A `textline object` contains a label and an editable string.
67
68All components have a name. This is mostly for debugging, so it is easy to see
69what object is referred to, although the name is also used for saving values.
70Of course the ID numbers can help as well, but they are less easy to
71distinguish.
Simon Glass311bd352023-01-06 08:52:43 -060072
73While the expo implementation provides support for handling keypresses and
74rendering on the display or serial port, it does not actually deal with reading
75input from the user, nor what should be done when a particular menu item is
76selected. This is deliberate since having the event loop outside the expo is
77more flexible, particularly in a single-threaded environment like U-Boot.
78
79Everything within an expo has a unique ID number. This is done so that it is
80easy to refer to things after the expo has been created. The expectation is that
81the controller declares an enum containing all of the elements in the expo,
82passing the ID of each object as it is created. When a menu item is selected,
83its ID is returned. When a object's font or position needs to change, the ID is
84passed to expo functions to indicate which object it is. It is possible for expo
85to auto-allocate IDs, but this is not recommended. The use of IDs is a
86convenience, removing the need for the controller to store pointers to objects,
87or even the IDs of objects. Programmatic creation of many items in a loop can be
88handled by allocating space in the enum for a maximum number of items, then
89adding the loop count to the enum values to obtain unique IDs.
90
Simon Glass6e9e4152023-06-01 10:22:47 -060091Where dynamic IDs are need, use expo_set_dynamic_start() to set the start value,
92so that they are allocated above the starting (enum) IDs.
93
Simon Glass311bd352023-01-06 08:52:43 -060094All text strings are stored in a structure attached to the expo, referenced by
95a text ID. This makes it easier at some point to implement multiple languages or
96to support Unicode strings.
97
98Menu objects do not have their own text and image objects. Instead they simply
99refer to objects which have been created. So a menu item is just a collection
100of IDs of text and image objects. When adding a menu item you must create these
101objects first, then create the menu item, passing in the relevant IDs.
102
103Creating an expo
104----------------
105
Simon Glass61300722023-06-01 10:23:01 -0600106To create an expo programmatically, use `expo_new()` followed by `scene_new()`
107to create a scene. Then add objects to the scene, using functions like
108`scene_txt_str()` and `scene_menu()`. For every menu item, add text and image
109objects, then create the menu item with `scene_menuitem()`, referring to those
110objects.
111
112To create an expo using a description file, see :ref:`expo_format` below.
Simon Glass311bd352023-01-06 08:52:43 -0600113
114Layout
115------
116
117Individual objects can be positioned using `scene_obj_set_pos()`. Menu items
118cannot be positioned manually: this is done by `scene_arrange()` which is called
119automatically when something changes. The menu itself determines the position of
120its items.
121
122Rendering
123---------
124
125Rendering is performed by calling `expo_render()`. This uses either the
126vidconsole, if present, or the serial console in `text mode`. Expo handles
127presentation automatically in either case, without any change in how the expo is
128created.
129
130For the vidconsole, Truetype fonts can be used if enabled, to enhance the
131quality of the display. For text mode, each menu item is shown in a single line,
132allowing easy selection using arrow keys.
133
134Input
135-----
136
137The controller is responsible for collecting keyboard input. A good way to do
138this is to use `cli_ch_process()`, since it handles conversion of escape
139sequences into keys. However, expo has some special menu-key codes for
140navigating the interface. These are defined in `enum bootmenu_key` and include
141`BKEY_UP` for moving up and `BKEY_SELECT` for selecting an item. You can use
Simon Glass00f6c402023-10-01 19:13:40 -0600142`bootmenu_conv_key()` to convert an ASCII key into one of these, but if it
143returns a value >= `BKEY_FIRST_EXTRA` then you should pass the unmodified ASCII
144key to the expo, since it may be used by textline objects.
Simon Glass311bd352023-01-06 08:52:43 -0600145
146Once a keypress is decoded, call `expo_send_key()` to send it to the expo. This
147may cause an update to the expo state and may produce an action.
148
149Actions
150-------
151
152Call `expo_action_get()` in the event loop to check for any actions that the
153expo wants to report. These can include selecting a particular menu item, or
154quitting the menu. Processing of these is the responsibility of your controller.
155
156Event loop
157----------
158
159Expo is intended to be used in an event loop. For an example loop, see
160`bootflow_menu_run()`. It is possible to perform other work in your event loop,
161such as scanning devices for more bootflows.
162
163Themes
164------
165
Simon Glassc999e172023-06-01 10:22:53 -0600166Expo supports simple themes, for setting the font size, for example. Use the
167expo_apply_theme() function to load a theme, passing a node with the required
168properties:
169
170font-size
171 Font size to use for all text (type: u32)
172
Simon Glass86f1ac52023-06-01 10:23:00 -0600173menu-inset
174 Number of pixels to inset the menu on the sides and top (type: u32)
175
176menuitem-gap-y
177 Number of pixels between menu items
178
Simon Glass377f18e2024-10-14 16:31:55 -0600179menu-title-margin-x
180 Number of pixels between right side of menu title to the left size of the
181 menu labels
182
Simon Glass61300722023-06-01 10:23:01 -0600183Pop-up mode
184-----------
185
186Expos support two modes. The simple mode is used for selecting from a single
187menu, e.g. when choosing with OS to boot. In this mode the menu items are shown
188in a list (label, > pointer, key and description) and can be chosen using arrow
189keys and enter::
190
191 U-Boot Boot Menu
192
193 UP and DOWN to choose, ENTER to select
194
195 mmc1 > 0 Fedora-Workstation-armhfp-31-1.9
196 mmc3 1 Armbian
197
198The popup mode allows multiple menus to be present in a scene. Each is shown
199just as its title and label, as with the `CPU Speed` and `AC Power` menus here::
200
201 Test Configuration
202
203
204 CPU Speed <2 GHz> (highlighted)
205
206 AC Power Always Off
207
208
209 UP and DOWN to choose, ENTER to select
210
211
Simon Glassc8925112023-06-01 10:23:02 -0600212.. _expo_format:
213
Simon Glass61300722023-06-01 10:23:01 -0600214Expo Format
215-----------
216
217It can be tedious to create a complex expo using code. Expo supports a
218data-driven approach, where the expo description is in a devicetree file. This
219makes it easier and faster to create and edit the description. An expo builder
220is provided to convert this format into an expo structure.
221
222Layout of the expo scenes is handled automatically, based on a set of simple
Simon Glassc8925112023-06-01 10:23:02 -0600223rules. The :doc:`../usage/cmd/cedit` can be used to load a configuration
224and create an expo from it.
Simon Glass61300722023-06-01 10:23:01 -0600225
226Top-level node
227~~~~~~~~~~~~~~
228
229The top-level node has the following properties:
230
231dynamic-start
232 type: u32, optional
233
234 Specifies the start of the dynamically allocated objects. This results in
235 a call to expo_set_dynamic_start().
236
237The top-level node has the following subnodes:
238
239scenes
240 Specifies the scenes in the expo, each one being a subnode
241
242strings
243 Specifies the strings in the expo, each one being a subnode
244
245`scenes` node
246~~~~~~~~~~~~~
247
248Contains a list of scene subnodes. The name of each subnode is passed as the
249name to `scene_new()`.
250
251`strings` node
252~~~~~~~~~~~~~~
253
254Contains a list of string subnodes. The name of each subnode is ignored.
255
256`strings` subnodes
257~~~~~~~~~~~~~~~~~~
258
259Each subnode defines a string which can be used by scenes and objects. Each
260string has an ID number which is used to refer to it.
261
262The `strings` subnodes have the following properties:
263
264id
265 type: u32, required
266
267 Specifies the ID number for the string.
268
269value:
270 type: string, required
271
272 Specifies the string text. For now only a single value is supported. Future
273 work may add support for multiple languages by using a value for each
274 language.
275
276Scene nodes (`scenes` subnodes)
277~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
278
279Each subnode of the `scenes` node contains a scene description.
280
281Most properties can use either a string or a string ID. For example, a `title`
282property can be used to provide the title for a menu; alternatively a `title-id`
283property can provide the string ID of the title. If both are present, the
284ID takes preference, except that if a string with that ID does not exist, it
285falls back to using the string from the property (`title` in this example). The
286description below shows these are alternative properties with the same
287description.
288
289The scene nodes have the following properties:
290
291id
292 type: u32, required
293
294 Specifies the ID number for the string.
295
296title / title-id
297 type: string / u32, required
298
299 Specifies the title of the scene. This is shown at the top of the scene.
300
301prompt / prompt-id
302 type: string / u32, required
303
304 Specifies a prompt for the scene. This is shown at the bottom of the scene.
305
306The scene nodes have a subnode for each object in the scene.
307
308Object nodes
309~~~~~~~~~~~~
310
311The object-node name is used as the name of the object, e.g. when calling
312`scene_menu()` to create a menu.
313
314Object nodes have the following common properties:
315
316type
317 type: string, required
318
319 Specifies the type of the object. Valid types are:
320
321 "menu"
322 Menu containing items which can be selected by the user
323
Simon Glass00f6c402023-10-01 19:13:40 -0600324 "textline"
325 A line of text which can be edited
326
Simon Glass61300722023-06-01 10:23:01 -0600327id
328 type: u32, required
329
330 Specifies the ID of the object. This is used when referring to the object.
331
Simon Glass2b91ca62023-08-14 16:40:37 -0600332Where CMOS RAM is used for reading and writing settings, the following
333additional properties are required:
334
335start-bit
336 Specifies the first bit in the CMOS RAM to use for this setting. For a RAM
337 with 0x100 bytes, there are 0x800 bit locations. For example, register 0x80
338 holds bits 0x400 to 0x407.
339
340bit-length
341 Specifies the number of CMOS RAM bits to use for this setting. The bits
342 extend from `start-bit` to `start-bit + bit-length - 1`. Note that the bits
343 must be contiguous.
Simon Glass61300722023-06-01 10:23:01 -0600344
345Menu nodes have the following additional properties:
346
347title / title-id
348 type: string / u32, required
349
350 Specifies the title of the menu. This is shown to the left of the area for
351 this menu.
352
353item-id
354 type: u32 list, required
355
356 Specifies the ID for each menu item. These are used for checking which item
357 has been selected.
358
359item-label / item-label-id
360 type: string list / u32 list, required
361
362 Specifies the label for each item in the menu. These are shown to the user.
363 In 'popup' mode these form the items in the menu.
364
365key-label / key-label-id
366 type: string list / u32 list, optional
367
368 Specifies the key for each item in the menu. These are currently only
369 intended for use in simple mode.
370
371desc-label / desc-label-id
372 type: string list / u32 list, optional
373
374 Specifies the description for each item in the menu. These are currently
375 only intended for use in simple mode.
376
Simon Glass00f6c402023-10-01 19:13:40 -0600377Textline nodes have the following additional properties:
378
379label / label-id
380 type: string / u32, required
381
382 Specifies the label of the textline. This is shown to the left of the area
383 for this textline.
384
385edit-id
386 type: u32, required
387
388 Specifies the ID of the of the editable text object. This can be used to
389 obtain the text from the textline
390
391max-chars:
392 type: u32, required
393
394 Specifies the maximum number of characters permitted to be in the textline.
395 The user will be prevented from adding more.
396
Simon Glass61300722023-06-01 10:23:01 -0600397
398Expo layout
399~~~~~~~~~~~
400
401The `expo_arrange()` function can be called to arrange the expo objects in a
402suitable manner. For each scene it puts the title at the top, the prompt at the
403bottom and the objects in order from top to bottom.
404
Simon Glass40eb3c32023-08-14 16:40:29 -0600405
406.. _expo_example:
407
Simon Glass61300722023-06-01 10:23:01 -0600408Expo format example
409~~~~~~~~~~~~~~~~~~~
410
411This example shows an expo with a single scene consisting of two menus. The
412scene title is specified using a string from the strings table, but all other
413strings are provided inline in the nodes where they are used.
414
415::
416
Simon Glassb1263bc2023-08-14 16:40:28 -0600417 /* this comment is parsed by the expo.py tool to insert the values below
Simon Glass61300722023-06-01 10:23:01 -0600418
Simon Glassb1263bc2023-08-14 16:40:28 -0600419 enum {
420 ZERO,
421 ID_PROMPT,
422 ID_SCENE1,
423 ID_SCENE1_TITLE,
Simon Glass61300722023-06-01 10:23:01 -0600424
Simon Glassb1263bc2023-08-14 16:40:28 -0600425 ID_CPU_SPEED,
426 ID_CPU_SPEED_TITLE,
427 ID_CPU_SPEED_1,
428 ID_CPU_SPEED_2,
429 ID_CPU_SPEED_3,
430
431 ID_POWER_LOSS,
432 ID_AC_OFF,
433 ID_AC_ON,
434 ID_AC_MEMORY,
Simon Glass61300722023-06-01 10:23:01 -0600435
Simon Glass00f6c402023-10-01 19:13:40 -0600436 ID_MACHINE_NAME,
437 ID_MACHINE_NAME_EDIT,
438
Simon Glassb1263bc2023-08-14 16:40:28 -0600439 ID_DYNAMIC_START,
440 */
Simon Glass61300722023-06-01 10:23:01 -0600441
442 &cedit {
443 dynamic-start = <ID_DYNAMIC_START>;
444
445 scenes {
446 main {
447 id = <ID_SCENE1>;
448
449 /* value refers to the matching id in /strings */
450 title-id = <ID_SCENE1_TITLE>;
451
452 /* simple string is used as it is */
453 prompt = "UP and DOWN to choose, ENTER to select";
454
455 /* defines a menu within the scene */
456 cpu-speed {
457 type = "menu";
458 id = <ID_CPU_SPEED>;
459
460 /*
461 * has both string and ID. The string is ignored
462 * if the ID is present and points to a string
463 */
464 title = "CPU speed";
465 title-id = <ID_CPU_SPEED_TITLE>;
466
467 /* menu items as simple strings */
468 item-label = "2 GHz", "2.5 GHz", "3 GHz";
469
470 /* IDs for the menu items */
471 item-id = <ID_CPU_SPEED_1 ID_CPU_SPEED_2
472 ID_CPU_SPEED_3>;
473 };
474
475 power-loss {
476 type = "menu";
477 id = <ID_POWER_LOSS>;
478
479 title = "AC Power";
480 item-label = "Always Off", "Always On",
481 "Memory";
482
483 item-id = <ID_AC_OFF ID_AC_ON ID_AC_MEMORY>;
484 };
Simon Glass00f6c402023-10-01 19:13:40 -0600485
486 machine-name {
487 id = <ID_MACHINE_NAME>;
488 type = "textline";
489 max-chars = <20>;
490 title = "Machine name";
491 edit-id = <ID_MACHINE_NAME_EDIT>;
Simon Glass61300722023-06-01 10:23:01 -0600492 };
493 };
494
495 strings {
496 title {
497 id = <ID_SCENE1_TITLE>;
498 value = "Test Configuration";
499 value-es = "configuraciĆ³n de prueba";
500 };
501 };
502 };
503
Simon Glass311bd352023-01-06 08:52:43 -0600504
505API documentation
506-----------------
507
508.. kernel-doc:: include/expo.h
509
510Future ideas
511------------
512
513Some ideas for future work:
514
515- Default menu item and a timeout
Simon Glass311bd352023-01-06 08:52:43 -0600516- Image formats other than BMP
517- Use of ANSI sequences to control a serial terminal
518- Colour selection
Simon Glass00f6c402023-10-01 19:13:40 -0600519- Support for more widgets, e.g. numeric, radio/option
Simon Glass311bd352023-01-06 08:52:43 -0600520- Mouse support
521- Integrate Nuklear, NxWidgets or some other library for a richer UI
522- Optimise rendering by only updating the display with changes since last render
523- Use expo to replace the existing menu implementation
524- Add a Kconfig option to drop the names to save code / data space
525- Add a Kconfig option to disable vidconsole support to save code / data space
526- Support both graphical and text menus at the same time on different devices
Simon Glass311bd352023-01-06 08:52:43 -0600527- Support unicode
528- Support curses for proper serial-terminal menus
Simon Glass61300722023-06-01 10:23:01 -0600529- Add support for large menus which need to scroll
Simon Glass2b91ca62023-08-14 16:40:37 -0600530- Update expo.py tool to check for overlapping names and CMOS locations
Simon Glass311bd352023-01-06 08:52:43 -0600531
532.. Simon Glass <sjg@chromium.org>
533.. 7-Oct-22