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