1*bbf21555SRichard Lowe.\" Copyright (c) 2011-2013 Devin Teske 2*bbf21555SRichard Lowe.\" All rights reserved. 3*bbf21555SRichard Lowe.\" 4*bbf21555SRichard Lowe.\" Redistribution and use in source and binary forms, with or without 5*bbf21555SRichard Lowe.\" modification, are permitted provided that the following conditions 6*bbf21555SRichard Lowe.\" are met: 7*bbf21555SRichard Lowe.\" 1. Redistributions of source code must retain the above copyright 8*bbf21555SRichard Lowe.\" notice, this list of conditions and the following disclaimer. 9*bbf21555SRichard Lowe.\" 2. Redistributions in binary form must reproduce the above copyright 10*bbf21555SRichard Lowe.\" notice, this list of conditions and the following disclaimer in the 11*bbf21555SRichard Lowe.\" documentation and/or other materials provided with the distribution. 12*bbf21555SRichard Lowe.\" 13*bbf21555SRichard Lowe.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14*bbf21555SRichard Lowe.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15*bbf21555SRichard Lowe.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16*bbf21555SRichard Lowe.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17*bbf21555SRichard Lowe.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18*bbf21555SRichard Lowe.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19*bbf21555SRichard Lowe.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20*bbf21555SRichard Lowe.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21*bbf21555SRichard Lowe.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22*bbf21555SRichard Lowe.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23*bbf21555SRichard Lowe.\" SUCH DAMAGE. 24*bbf21555SRichard Lowe.\" 25*bbf21555SRichard Lowe.Dd July 20, 2018 26*bbf21555SRichard Lowe.Dt MENU.4TH 7 27*bbf21555SRichard Lowe.Os 28*bbf21555SRichard Lowe.Sh NAME 29*bbf21555SRichard Lowe.Nm menu.4th 30*bbf21555SRichard Lowe.Nd loader dynamic menu boot module 31*bbf21555SRichard Lowe.Sh DESCRIPTION 32*bbf21555SRichard LoweThe file that goes by the name of 33*bbf21555SRichard Lowe.Nm 34*bbf21555SRichard Loweis a set of commands designed to display a dynamic menu system managed through 35*bbf21555SRichard Lowea system of carefully named environment variables. 36*bbf21555SRichard LoweThe commands of 37*bbf21555SRichard Lowe.Nm 38*bbf21555SRichard Loweby themselves are not enough for most uses. 39*bbf21555SRichard LowePlease refer to the 40*bbf21555SRichard Loweexamples below for the most common situations, and to 41*bbf21555SRichard Lowe.Xr loader 7 42*bbf21555SRichard Lowefor additional commands. 43*bbf21555SRichard Lowe.Pp 44*bbf21555SRichard LoweBefore using any of the commands provided in 45*bbf21555SRichard Lowe.Nm , 46*bbf21555SRichard Loweit must be included 47*bbf21555SRichard Lowethrough the command: 48*bbf21555SRichard Lowe.Pp 49*bbf21555SRichard Lowe.Dl include menu.4th 50*bbf21555SRichard Lowe.Pp 51*bbf21555SRichard LoweThis line is present in the default 52*bbf21555SRichard Lowe.Pa /boot/forth/menu.rc 53*bbf21555SRichard Lowefile, so it is not needed (and should not be re-issued) in a normal setup. 54*bbf21555SRichard Lowe.Pp 55*bbf21555SRichard LoweThe commands provided by it are: 56*bbf21555SRichard Lowe.Pp 57*bbf21555SRichard Lowe.Bl -tag -width disable-module_module -compact -offset indent 58*bbf21555SRichard Lowe.It Ic menu-init 59*bbf21555SRichard LoweDraws the menu bounding box and initializes some internal state variables. 60*bbf21555SRichard LoweThis should be called before any other menu-related functions. 61*bbf21555SRichard Lowe.It Ic menu-display 62*bbf21555SRichard LoweDisplays the menu (configured via the below documented environment variables) 63*bbf21555SRichard Loweand blocks on keyboard input, awaiting user action. 64*bbf21555SRichard Lowe.It Ic menu-erase 65*bbf21555SRichard LoweClears the screen area within the menu bounding box. 66*bbf21555SRichard Lowe.It Ic menu-redraw 67*bbf21555SRichard LoweCalls 68*bbf21555SRichard Lowe.Ic menu-erase 69*bbf21555SRichard Loweand then redraws the menu. 70*bbf21555SRichard Lowe.It Ic menu-unset 71*bbf21555SRichard LoweUnsets the environment variables associated with individual menu items, 72*bbf21555SRichard Loweclearing the way for a new menu. 73*bbf21555SRichard Lowe.It Ic menu-clear 74*bbf21555SRichard LoweCalls 75*bbf21555SRichard Lowe.Ic menu-unset 76*bbf21555SRichard Loweand then 77*bbf21555SRichard Lowe.Ic menu-erase . 78*bbf21555SRichard Lowe.El 79*bbf21555SRichard Lowe.Pp 80*bbf21555SRichard LoweThe environment variables that effect its behavior are: 81*bbf21555SRichard Lowe.Bl -tag -width bootfile -offset indent 82*bbf21555SRichard Lowe.It Va loader_color 83*bbf21555SRichard LoweIf set to 84*bbf21555SRichard Lowe.Dq Li NO 85*bbf21555SRichard Lowe(case-insensitive) or 86*bbf21555SRichard Lowe.Dq Li 0 , 87*bbf21555SRichard Lowecauses the menu to be displayed without color. 88*bbf21555SRichard LoweThe default is to use ANSI coloring whenever possible. 89*bbf21555SRichard LoweIf serial boot is enabled, color is disabled by default. 90*bbf21555SRichard LoweColor features include the use of ANSI bold for numbers appearing to the left 91*bbf21555SRichard Loweof menuitems and the use of special 92*bbf21555SRichard Lowe.Dq Li ansi 93*bbf21555SRichard Lowevariables described below. 94*bbf21555SRichard Lowe.It Va autoboot_delay 95*bbf21555SRichard LoweNumber of seconds 96*bbf21555SRichard Lowe.Ic menu-display 97*bbf21555SRichard Lowewill wait before executing 98*bbf21555SRichard Lowe.Va menu_timeout_command 99*bbf21555SRichard Lowe.Ic ( boot 100*bbf21555SRichard Loweby default) unless a key is pressed. 101*bbf21555SRichard LoweIf set to 102*bbf21555SRichard Lowe.Dq Li NO 103*bbf21555SRichard Lowe(case-insensitive) 104*bbf21555SRichard Lowe.Ic menu-display 105*bbf21555SRichard Lowewill wait for user input and never execute 106*bbf21555SRichard Lowe.Ic menu_timeout_command . 107*bbf21555SRichard LoweIf set to 108*bbf21555SRichard Lowe.Dq Li -1 , 109*bbf21555SRichard Lowe.Ic menu-display 110*bbf21555SRichard Lowewill boot immediately, preventing both interruption of the 111*bbf21555SRichard Lowe.Ic autoboot 112*bbf21555SRichard Loweprocess and escaping to the loader prompt. 113*bbf21555SRichard LoweDefault is 114*bbf21555SRichard Lowe.Dq Li 10 . 115*bbf21555SRichard LoweSee 116*bbf21555SRichard Lowe.Xr loader 7 117*bbf21555SRichard Lowefor additional information. 118*bbf21555SRichard Lowe.It Va menu_timeout_command 119*bbf21555SRichard LoweThe command to be executed after 120*bbf21555SRichard Lowe.Va autoboot_delay 121*bbf21555SRichard Loweseconds if a key is not pressed. 122*bbf21555SRichard LoweThe default is 123*bbf21555SRichard Lowe.Ic boot . 124*bbf21555SRichard Lowe.It Va loader_menu_frame 125*bbf21555SRichard LoweSets the desired box style to draw around the boot menu. 126*bbf21555SRichard LowePossible values are: 127*bbf21555SRichard Lowe.Dq Li single 128*bbf21555SRichard Lowe.Pq the default , 129*bbf21555SRichard Lowe.Dq Li double , 130*bbf21555SRichard Loweand 131*bbf21555SRichard Lowe.Dq Li none . 132*bbf21555SRichard Lowe.It Va loader_menu_timeout_x 133*bbf21555SRichard LoweSets the desired column position of the timeout countdown text. 134*bbf21555SRichard LoweDefault is 4. 135*bbf21555SRichard Lowe.It Va loader_menu_timeout_y 136*bbf21555SRichard LoweSets the desired row position of the timeout countdown text. 137*bbf21555SRichard LoweDefault is 23. 138*bbf21555SRichard Lowe.It Va loader_menu_title 139*bbf21555SRichard LoweThe text to display above the menu. 140*bbf21555SRichard LoweDefault is 141*bbf21555SRichard Lowe.Dq Li "Welcome to FreeBSD" . 142*bbf21555SRichard Lowe.It Va loader_menu_title_align 143*bbf21555SRichard LoweDefault is to align 144*bbf21555SRichard Lowe.Ic loader_menu_title 145*bbf21555SRichard Lowecentered above the menu. 146*bbf21555SRichard LoweThis can be set to 147*bbf21555SRichard Lowe.Dq Li left 148*bbf21555SRichard Loweor 149*bbf21555SRichard Lowe.Dq Li right 150*bbf21555SRichard Loweto instead display the title left-or-right justified 151*bbf21555SRichard Lowe.Pq respectively . 152*bbf21555SRichard Lowe.It Va loader_menu_x 153*bbf21555SRichard LoweSets the desired column position of the boot menu. 154*bbf21555SRichard LoweDefault is 5. 155*bbf21555SRichard Lowe.It Va loader_menu_y 156*bbf21555SRichard LoweSets the desired row position of the boot menu. 157*bbf21555SRichard LoweDefault is 10. 158*bbf21555SRichard Lowe.It Va menu_caption[x] 159*bbf21555SRichard LoweThe text to be displayed for the numbered menuitem 160*bbf21555SRichard Lowe.Dq Li x . 161*bbf21555SRichard Lowe.It Va menu_command[x] 162*bbf21555SRichard LoweThe command to be executed when the number associated with menuitem 163*bbf21555SRichard Lowe.Dq Li x 164*bbf21555SRichard Loweis pressed. 165*bbf21555SRichard LoweSee the list of included FICL words below for some ideas. 166*bbf21555SRichard Lowe.It Va menu_keycode[x] 167*bbf21555SRichard LoweAn optional decimal ASCII keycode to be associated with menuitem 168*bbf21555SRichard Lowe.Dq Li x . 169*bbf21555SRichard LoweWhen pressed, will cause the execution of 170*bbf21555SRichard Lowe.Va menu_command[x] . 171*bbf21555SRichard Lowe.It Va ansi_caption[x] 172*bbf21555SRichard LoweIf 173*bbf21555SRichard Lowe.Va loader_color 174*bbf21555SRichard Loweis set 175*bbf21555SRichard Lowe.Pq enabled by default , 176*bbf21555SRichard Loweuse this caption for menuitem 177*bbf21555SRichard Lowe.Dq Li x 178*bbf21555SRichard Loweinstead of 179*bbf21555SRichard Lowe.Va menu_caption[x] . 180*bbf21555SRichard Lowe.It Va toggled_text[x] 181*bbf21555SRichard LoweFor menuitems where 182*bbf21555SRichard Lowe.Va menu_command[x] 183*bbf21555SRichard Loweis set to 184*bbf21555SRichard Lowe.Dq Li toggle_menuitem 185*bbf21555SRichard Lowe(or a derivative thereof), the text displayed 186*bbf21555SRichard Lowewill toggle between this and 187*bbf21555SRichard Lowe.Va menu_caption[x] . 188*bbf21555SRichard Lowe.It Va toggled_ansi[x] 189*bbf21555SRichard LoweLike 190*bbf21555SRichard Lowe.Va toggled_text[x] 191*bbf21555SRichard Loweexcept used when 192*bbf21555SRichard Lowe.Va loader_color 193*bbf21555SRichard Loweis enabled 194*bbf21555SRichard Lowe.Pq default . 195*bbf21555SRichard Lowe.It Va menu_caption[x][y] 196*bbf21555SRichard LoweFor menuitems where 197*bbf21555SRichard Lowe.Va menu_command[x] 198*bbf21555SRichard Loweis set to 199*bbf21555SRichard Lowe.Dq Li cycle_menuitem 200*bbf21555SRichard Lowe(or a derivative thereof), the text displayed will cycle between this and other 201*bbf21555SRichard Lowe.Va menu_caption[x][y] 202*bbf21555SRichard Loweentries. 203*bbf21555SRichard Lowe.It Va ansi_caption[x][y] 204*bbf21555SRichard LoweLike 205*bbf21555SRichard Lowe.Va menu_caption[x][y] 206*bbf21555SRichard Loweexcept used when 207*bbf21555SRichard Lowe.Va loader_color 208*bbf21555SRichard Loweis enabled 209*bbf21555SRichard Lowe.Pq default . 210*bbf21555SRichard Lowe.It Va menu_acpi 211*bbf21555SRichard LoweWhen set to a number 212*bbf21555SRichard Lowe.Dq Li x 213*bbf21555SRichard Loweassociated with a given menuitem, that menuitem will allow to select 214*bbf21555SRichard Loweacpi-user-options 215*bbf21555SRichard Lowe.Pq see Xr eeprom 8 . 216*bbf21555SRichard Lowe.It Va menu_options 217*bbf21555SRichard LoweWhen set to a number 218*bbf21555SRichard Lowe.Dq Li x , 219*bbf21555SRichard Lowea single blank-line and an 220*bbf21555SRichard Lowe.Dq Li Options 221*bbf21555SRichard Loweheader are inserted between 222*bbf21555SRichard Lowe.Va menu_caption[x-1] 223*bbf21555SRichard Loweand 224*bbf21555SRichard Lowe.Va menu_caption[x] 225*bbf21555SRichard Lowe(if configured). 226*bbf21555SRichard Lowe.It Va menu_reboot 227*bbf21555SRichard LoweIf set, adds a built-in 228*bbf21555SRichard Lowe.Dq Li Reboot 229*bbf21555SRichard Lowemenuitem to the end of the last configured menuitem. 230*bbf21555SRichard LoweIf 231*bbf21555SRichard Lowe.Va menu_options 232*bbf21555SRichard Loweis configured, the 233*bbf21555SRichard Lowe.Dq Li Reboot 234*bbf21555SRichard Lowemenuitem will be inserted before the 235*bbf21555SRichard Lowe.Dq Options 236*bbf21555SRichard Loweseparator. 237*bbf21555SRichard Lowe.El 238*bbf21555SRichard Lowe.Pp 239*bbf21555SRichard LoweIn addition, it provides the following FICL words: 240*bbf21555SRichard Lowe.Pp 241*bbf21555SRichard Lowe.Bl -tag -width disable-module_module -compact -offset indent 242*bbf21555SRichard Lowe.It Ic arch-i386? ( -- BOOL ) 243*bbf21555SRichard LoweReturns true (-1) on i386 and false (0) otherwise. 244*bbf21555SRichard Lowe.It Ic acpipresent? ( -- BOOL ) 245*bbf21555SRichard LoweReturns true (-1) if ACPI is present and false (0) otherwise. 246*bbf21555SRichard Lowe.It Ic acpienabled? ( -- BOOL ) 247*bbf21555SRichard LoweReturns true (-1) if ACPI is enabled and false (0) otherwise. 248*bbf21555SRichard Lowe.It Ic toggle_menuitem ( N -- N ) 249*bbf21555SRichard LoweToggles menuitem 250*bbf21555SRichard Lowe.Dq Li N 251*bbf21555SRichard Lowebetween 252*bbf21555SRichard Lowe.Va menu_caption[x] 253*bbf21555SRichard Loweand 254*bbf21555SRichard Lowe.Va toggled_text[x] 255*bbf21555SRichard Lowe(where 256*bbf21555SRichard Lowe.Dq Li N 257*bbf21555SRichard Lowerepresents the ASCII decimal value for 258*bbf21555SRichard Lowe.Dq Li x ) . 259*bbf21555SRichard Lowe.It Ic cycle_menuitem ( N -- N ) 260*bbf21555SRichard LoweCycles menuitem 261*bbf21555SRichard Lowe.Dq Li N 262*bbf21555SRichard Lowebetween 263*bbf21555SRichard Lowe.Va menu_caption[x][y] 264*bbf21555SRichard Loweentries (where 265*bbf21555SRichard Lowe.Va N 266*bbf21555SRichard Lowerepresents the ASCII decimal value for 267*bbf21555SRichard Lowe.Va x ) . 268*bbf21555SRichard Lowe.El 269*bbf21555SRichard Lowe.Pp 270*bbf21555SRichard LoweFor all values of 271*bbf21555SRichard Lowe.Dq Li x 272*bbf21555SRichard Loweabove, use any number between 1 through 9. 273*bbf21555SRichard LoweSorry, double-digits are not currently supported. 274*bbf21555SRichard Lowe.Sh FILES 275*bbf21555SRichard Lowe.Bl -tag -width /boot/forth/loader.4th -compact 276*bbf21555SRichard Lowe.It Pa /boot/loader 277*bbf21555SRichard LoweThe 278*bbf21555SRichard Lowe.Xr loader 7 . 279*bbf21555SRichard Lowe.It Pa /boot/forth/menu.4th 280*bbf21555SRichard Lowe.Nm 281*bbf21555SRichard Loweitself. 282*bbf21555SRichard Lowe.It Pa /boot/loader.rc 283*bbf21555SRichard Lowe.Xr loader 7 284*bbf21555SRichard Lowebootstrapping script. 285*bbf21555SRichard Lowe.El 286*bbf21555SRichard Lowe.Sh EXAMPLES 287*bbf21555SRichard LoweA simple boot menu: 288*bbf21555SRichard Lowe.Pp 289*bbf21555SRichard Lowe.Bd -literal -offset indent -compact 290*bbf21555SRichard Loweinclude /boot/forth/menu.4th 291*bbf21555SRichard Lowemenu-init 292*bbf21555SRichard Loweset menu_caption[1]="Boot" 293*bbf21555SRichard Loweset menu_command[1]="boot" 294*bbf21555SRichard Loweset menu_options=2 295*bbf21555SRichard Loweset menu_caption[2]="Option: NO" 296*bbf21555SRichard Loweset toggled_text[2]="Option: YES" 297*bbf21555SRichard Loweset menu_command[2]="toggle_menuitem" 298*bbf21555SRichard Loweset menu_timeout_command="boot" 299*bbf21555SRichard Loweset menu_reboot 300*bbf21555SRichard Lowemenu-display 301*bbf21555SRichard Lowe.Ed 302*bbf21555SRichard Lowe.Sh SEE ALSO 303*bbf21555SRichard Lowe.Xr loader.conf 5 , 304*bbf21555SRichard Lowe.Xr beastie.4th 7 , 305*bbf21555SRichard Lowe.Xr loader 7 , 306*bbf21555SRichard Lowe.Xr loader.4th 7 , 307*bbf21555SRichard Lowe.Xr eeprom 8 308