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