1.. SPDX-License-Identifier: GPL-2.0+
2.. (C) Copyright 2011-2012 Pali Rohár <pali@kernel.org>
3
4bootmenu command
5================
6
7Synopsis
8--------
9::
10
11    bootmenu [delay]
12
13Description
14-----------
15
16The "bootmenu" command uses U-Boot menu interfaces and provides
17a simple mechanism for creating menus with different boot items.
18The cursor keys "Up" and "Down" are used for navigation through
19the items. Current active menu item is highlighted and can be
20selected using the "Enter" key. The selection of the highlighted
21menu entry invokes an U-Boot command (or a list of commands)
22associated with this menu entry.
23
24The "bootmenu" command interprets ANSI escape sequences, so
25an ANSI terminal is required for proper menu rendering and item
26selection.
27
28The assembling of the menu is done via a set of environment variables
29"bootmenu_<num>" and "bootmenu_delay", i.e.::
30
31    bootmenu_delay=<delay>
32    bootmenu_<num>="<title>=<commands>"
33
34<delay>
35    is the autoboot delay in seconds, after which the first
36    menu entry will be selected automatically
37
38<num>
39    is the boot menu entry number, starting from zero
40
41<title>
42    is the text of the menu entry shown on the console
43    or on the boot screen
44
45<commands>
46    are commands which will be executed when a menu
47    entry is selected
48
49Title and commands are separated by the first appearance of a '='
50character in the value of the environment variable.
51
52The first (optional) argument of the "bootmenu" command is a delay specifier
53and it overrides the delay value defined by "bootmenu_delay" environment
54variable. If the environment variable "bootmenu_delay" is not set or if
55the argument of the "bootmenu" command is not specified, the default delay
56will be CONFIG_BOOTDELAY. If delay is 0, no menu entries will be shown on
57the console (or on the screen) and the command of the first menu entry will
58be called immediately. If delay is less then 0, bootmenu will be shown and
59autoboot will be disabled.
60
61Bootmenu always adds menu entry "U-Boot console" at the end of all menu
62entries specified by environment variables. When selecting this entry
63the bootmenu terminates and the usual U-Boot command prompt is presented
64to the user.
65
66Example environment::
67
68    setenv bootmenu_0 Boot 1. kernel=bootm 0x82000000  # Set first menu entry
69    setenv bootmenu_1 Boot 2. kernel=bootm 0x83000000  # Set second menu entry
70    setenv bootmenu_2 Reset board=reset                # Set third menu entry
71    setenv bootmenu_3 U-Boot boot order=boot           # Set fourth menu entry
72    bootmenu 20        # Run bootmenu with autoboot delay 20s
73
74
75The above example will be rendered as below::
76
77    *** U-Boot Boot Menu ***
78
79       Boot 1. kernel
80       Boot 2. kernel
81       Reset board
82       U-Boot boot order
83       U-Boot console
84
85    Hit any key to stop autoboot: 20
86    Press UP/DOWN to move, ENTER to select
87
88The selected menu entry will be highlighted - it will have inverted
89background and text colors.
90
91UEFI boot variable enumeration
92''''''''''''''''''''''''''''''
93If enabled, the bootmenu command will automatically generate and add
94UEFI-related boot menu entries for the following items.
95
96 * possible bootable media with default file names
97 * user-defined UEFI boot options
98
99The bootmenu automatically enumerates the possible bootable
100media devices supporting EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.
101This auto generated entry is named as "<interface> <devnum>:<part>" format.
102(e.g. "usb 0:1")
103
104The bootmenu displays the UEFI-related menu entries in order of "BootOrder".
105When the user selects the UEFI boot menu entry, the bootmenu sets
106the selected boot variable index to "BootNext" without non-volatile attribute,
107then call the uefi boot manager with the command "bootefi bootmgr".
108
109Example bootmenu is as below::
110
111    *** U-Boot Boot Menu ***
112
113       mmc 0:1
114       mmc 0:2
115       debian
116       nvme 0:1
117       ubuntu
118       nvme 0:2
119       usb 0:2
120       U-Boot console
121
122Default behavior when user exits from the bootmenu
123~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
124User can exit from bootmenu by selecting the last entry
125"U-Boot console"/"Quit" or ESC key.
126
127When the CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE is disabled,
128user exits from the bootmenu and returns to the U-Boot console.
129
130When the CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE is enabled, user can not
131enter the U-Boot console. When the user exits from the bootmenu,
132the bootmenu invokes the following default behavior.
133
134 * if CONFIG_CMD_BOOTEFI_BOOTMGR is enabled, execute "bootefi bootmgr" command
135 * "bootefi bootmgr" fails or is not enabled, then execute "run bootcmd" command.
136
137Configuration
138-------------
139
140The "bootmenu" command is enabled by::
141
142    CONFIG_CMD_BOOTMENU=y
143
144To run the bootmenu at startup add these additional settings::
145
146    CONFIG_AUTOBOOT_KEYED=y
147    CONFIG_BOOTDELAY=30
148    CONFIG_AUTOBOOT_MENU_SHOW=y
149
150UEFI boot variable enumeration is enabled by::
151
152    CONFIG_CMD_BOOTEFI_BOOTMGR=y
153
154To improve the product security, entering U-Boot console from bootmenu
155can be disabled by::
156
157    CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE=y
158
159To scan the discoverable devices connected to the buses such as
160USB and PCIe prior to bootmenu showing up, CONFIG_PREBOOT can be
161used to run the command before showing the bootmenu, i.e.::
162
163    CONFIG_USE_PREBOOT=y
164    CONFIG_PREBOOT="pci enum; usb start; scsi scan; nvme scan; virtio scan"
165