1.\" Copyright (c) 1999 Daniel C. Sobral 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd September 29, 2021 26.Dt LOADER_4TH 8 27.Os 28.Sh NAME 29.Nm loader_4th 30.Nd kernel bootstrapping final stage 31.Sh DESCRIPTION 32The program called 33.Nm 34is the final stage of 35.Fx Ns 's 36kernel bootstrapping process. 37On IA32 (i386) architectures, it is a 38.Pa BTX 39client. 40It is linked statically to 41.Xr libsa 3 42and usually located in the directory 43.Pa /boot . 44.Pp 45It provides a scripting language that can be used to 46automate tasks, do pre-configuration or assist in recovery 47procedures. 48This scripting language is roughly divided in 49two main components. 50The smaller one is a set of commands 51designed for direct use by the casual user, called "builtin 52commands" for historical reasons. 53The main drive behind these commands is user-friendliness. 54The bigger component is an 55.Tn ANS 56Forth compatible Forth interpreter based on FICL, by 57.An John Sadler . 58.Pp 59During initialization, 60.Nm 61will probe for a console and set the 62.Va console 63variable, or set it to serial console 64.Pq Dq Li comconsole 65if the previous boot stage used that. 66If multiple consoles are selected, they will be listed separated by spaces. 67Then, devices are probed, 68.Va currdev 69and 70.Va loaddev 71are set, and 72.Va LINES 73is set to 24. 74Next, 75.Tn FICL 76is initialized, the builtin words are added to its vocabulary, and 77.Pa /boot/boot.4th 78is processed if it exists. 79No disk switching is possible while that file is being read. 80The inner interpreter 81.Nm 82will use with 83.Tn FICL 84is then set to 85.Ic interpret , 86which is 87.Tn FICL Ns 's 88default. 89After that, 90.Pa /boot/loader.rc 91is processed if available. 92These files are processed through the 93.Ic include 94command, which reads all of them into memory before processing them, 95making disk changes possible. 96.Pp 97At this point, if an 98.Ic autoboot 99has not been tried, and if 100.Va autoboot_delay 101is not set to 102.Dq Li NO 103(not case sensitive), then an 104.Ic autoboot 105will be tried. 106If the system gets past this point, 107.Va prompt 108will be set and 109.Nm 110will engage interactive mode. 111Please note that historically even when 112.Va autoboot_delay 113is set to 114.Dq Li 0 115user will be able to interrupt autoboot process by pressing some key 116on the console while kernel and modules are being loaded. 117In some 118cases such behaviour may be undesirable, to prevent it set 119.Va autoboot_delay 120to 121.Dq Li -1 , 122in this case 123.Nm 124will engage interactive mode only if 125.Ic autoboot 126has failed. 127.Sh BUILTIN COMMANDS 128In 129.Nm , 130builtin commands take parameters from the command line. 131Presently, 132the only way to call them from a script is by using 133.Pa evaluate 134on a string. 135If an error condition occurs, an exception will be generated, 136which can be intercepted using 137.Tn ANS 138Forth exception handling 139words. 140If not intercepted, an error message will be displayed and 141the interpreter's state will be reset, emptying the stack and restoring 142interpreting mode. 143The commands are described in the 144.Xr loader_simp 8 145.Dq BUILTIN COMMANDS 146section. 147.Ss BUILTIN ENVIRONMENT VARIABLES 148The environment variables common to all interpreters are described in the 149.Xr loader_simp 8 150.Dq BUILTIN ENVIRONMENT VARIABLES 151section. 152.Ss BUILTIN PARSER 153When a builtin command is executed, the rest of the line is taken 154by it as arguments, and it is processed by a special parser which 155is not used for regular Forth commands. 156.Pp 157This special parser applies the following rules to the parsed text: 158.Bl -enum 159.It 160All backslash characters are preprocessed. 161.Bl -bullet 162.It 163\eb , \ef , \er , \en and \et are processed as in C. 164.It 165\es is converted to a space. 166.It 167\ev is converted to 168.Tn ASCII 16911. 170.It 171\ez is just skipped. 172Useful for things like 173.Dq \e0xf\ez\e0xf . 174.It 175\e0xN and \e0xNN are replaced by the hex N or NN. 176.It 177\eNNN is replaced by the octal NNN 178.Tn ASCII 179character. 180.It 181\e" , \e' and \e$ will escape these characters, preventing them from 182receiving special treatment in Step 2, described below. 183.It 184\e\e will be replaced with a single \e . 185.It 186In any other occurrence, backslash will just be removed. 187.El 188.It 189Every string between non-escaped quotes or double-quotes will be treated 190as a single word for the purposes of the remaining steps. 191.It 192Replace any 193.Li $VARIABLE 194or 195.Li ${VARIABLE} 196with the value of the environment variable 197.Va VARIABLE . 198.It 199Space-delimited arguments are passed to the called builtin command. 200Spaces can also be escaped through the use of \e\e . 201.El 202.Pp 203An exception to this parsing rule exists, and is described in 204.Sx BUILTINS AND FORTH . 205.Ss BUILTINS AND FORTH 206All builtin words are state-smart, immediate words. 207If interpreted, they behave exactly as described previously. 208If they are compiled, though, 209they extract their arguments from the stack instead of the command line. 210.Pp 211If compiled, the builtin words expect to find, at execution time, the 212following parameters on the stack: 213.D1 Ar addrN lenN ... addr2 len2 addr1 len1 N 214where 215.Ar addrX lenX 216are strings which will compose the command line that will be parsed 217into the builtin's arguments. 218Internally, these strings are concatenated in from 1 to N, 219with a space put between each one. 220.Pp 221If no arguments are passed, a 0 222.Em must 223be passed, even if the builtin accepts no arguments. 224.Pp 225While this behavior has benefits, it has its trade-offs. 226If the execution token of a builtin is acquired (through 227.Ic ' 228or 229.Ic ['] ) , 230and then passed to 231.Ic catch 232or 233.Ic execute , 234the builtin behavior will depend on the system state 235.Bf Em 236at the time 237.Ic catch 238or 239.Ic execute 240is processed! 241.Ef 242This is particularly annoying for programs that want or need to 243handle exceptions. 244In this case, the use of a proxy is recommended. 245For example: 246.Dl : (boot) boot ; 247.Sh FICL 248.Tn FICL 249is a Forth interpreter written in C, in the form of a forth 250virtual machine library that can be called by C functions and vice 251versa. 252.Pp 253In 254.Nm , 255each line read interactively is then fed to 256.Tn FICL , 257which may call 258.Nm 259back to execute the builtin words. 260The builtin 261.Ic include 262will also feed 263.Tn FICL , 264one line at a time. 265.Pp 266The words available to 267.Tn FICL 268can be classified into four groups. 269The 270.Tn ANS 271Forth standard words, extra 272.Tn FICL 273words, extra 274.Fx 275words, and the builtin commands; 276the latter were already described. 277The 278.Tn ANS 279Forth standard words are listed in the 280.Sx STANDARDS 281section. 282The words falling in the two other groups are described in the 283following subsections. 284.Ss FICL EXTRA WORDS 285.Bl -tag -width wid-set-super 286.It Ic .env 287.It Ic .ver 288.It Ic -roll 289.It Ic 2constant 290.It Ic >name 291.It Ic body> 292.It Ic compare 293This is the STRING word set's 294.Ic compare . 295.It Ic compile-only 296.It Ic endif 297.It Ic forget-wid 298.It Ic parse-word 299.It Ic sliteral 300This is the STRING word set's 301.Ic sliteral . 302.It Ic wid-set-super 303.It Ic w@ 304.It Ic w! 305.It Ic x. 306.It Ic empty 307.It Ic cell- 308.It Ic -rot 309.El 310.Ss FREEBSD EXTRA WORDS 311.Bl -tag -width XXXXXXXX 312.It Ic \&$ Pq -- 313Evaluates the remainder of the input buffer, after having printed it first. 314.It Ic \&% Pq -- 315Evaluates the remainder of the input buffer under a 316.Ic catch 317exception guard. 318.It Ic .# 319Works like 320.Ic "." 321but without outputting a trailing space. 322.It Ic fclose Pq Ar fd -- 323Closes a file. 324.It Ic fkey Pq Ar fd -- char 325Reads a single character from a file. 326.It Ic fload Pq Ar fd -- 327Processes a file 328.Em fd . 329.It Ic fopen Pq Ar addr len mode Li -- Ar fd 330Opens a file. 331Returns a file descriptor, or \-1 in case of failure. 332The 333.Ar mode 334parameter selects whether the file is to be opened for read access, write 335access, or both. 336The constants 337.Dv O_RDONLY , O_WRONLY , 338and 339.Dv O_RDWR 340are defined in 341.Pa /boot/support.4th , 342indicating read only, write only, and read-write access, respectively. 343.It Xo 344.Ic fread 345.Pq Ar fd addr len -- len' 346.Xc 347Tries to read 348.Em len 349bytes from file 350.Em fd 351into buffer 352.Em addr . 353Returns the actual number of bytes read, or -1 in case of error or end of 354file. 355.It Ic heap? Pq -- Ar cells 356Return the space remaining in the dictionary heap, in cells. 357This is not related to the heap used by dynamic memory allocation words. 358.It Ic inb Pq Ar port -- char 359Reads a byte from a port. 360.It Ic key Pq -- Ar char 361Reads a single character from the console. 362.It Ic key? Pq -- Ar flag 363Returns 364.Ic true 365if there is a character available to be read from the console. 366.It Ic ms Pq Ar u -- 367Waits 368.Em u 369microseconds. 370.It Ic outb Pq Ar port char -- 371Writes a byte to a port. 372.It Ic seconds Pq -- Ar u 373Returns the number of seconds since midnight. 374.It Ic tib> Pq -- Ar addr len 375Returns the remainder of the input buffer as a string on the stack. 376.It Ic trace! Pq Ar flag -- 377Activates or deactivates tracing. 378Does not work with 379.Ic catch . 380.El 381.Ss FREEBSD DEFINED ENVIRONMENTAL QUERIES 382.Bl -tag -width Ds 383.It arch-i386 384.Ic TRUE 385if the architecture is IA32. 386.It FreeBSD_version 387.Fx 388version at compile time. 389.It loader_version 390.Nm 391version. 392.El 393.Sh SECURITY 394Access to the 395.Nm 396command line provides several ways of compromising system security, 397including, but not limited to: 398.Pp 399.Bl -bullet 400.It 401Booting from removable storage, by setting the 402.Va currdev 403or 404.Va loaddev 405variables 406.It 407Executing binary of choice, by setting the 408.Va init_path 409or 410.Va init_script 411variables 412.It 413Overriding ACPI DSDT to inject arbitrary code into the ACPI subsystem 414.El 415.Pp 416One can prevent unauthorized access 417to the 418.Nm 419command line by setting the 420.Va password , 421or setting 422.Va autoboot_delay 423to -1. 424See 425.Xr loader.conf 5 426for details. 427In order for this to be effective, one should also configure the firmware 428(BIOS or UEFI) to prevent booting from unauthorized devices. 429.Sh MD 430Memory disk (MD) can be used when the 431.Nm 432was compiled with 433.Va MD_IMAGE_SIZE . 434The size of the memory disk is determined by 435.Va MD_IMAGE_SIZE . 436If MD available, a file system can be embedded into the 437.Nm 438with 439.Pa /sys/tools/embed_mfs.sh . 440Then, MD will be probed and be set to 441.Va currdev 442during initialization. 443.Pp 444Currently, MD is only supported in 445.Xr loader.efi 8 . 446.Sh FILES 447.Bl -tag -width /usr/share/examples/bootforth/ -compact 448.It Pa /boot/loader 449.Nm 450itself. 451.It Pa /boot/boot.4th 452Additional 453.Tn FICL 454initialization. 455.It Pa /boot/defaults/loader.conf 456.It Pa /boot/loader.4th 457Extra builtin-like words. 458.It Pa /boot/loader.conf 459.It Pa /boot/loader.conf.local 460.Nm 461configuration files, as described in 462.Xr loader.conf 5 . 463.It Pa /boot/loader.rc 464.Nm 465bootstrapping script. 466.It Pa /boot/loader.help 467Loaded by 468.Ic help . 469Contains the help messages. 470.It Pa /boot/support.4th 471.Pa loader.conf 472processing words. 473.It Pa /usr/share/examples/bootforth/ 474Assorted examples. 475.El 476.Sh EXAMPLES 477Boot in single user mode: 478.Pp 479.Dl boot -s 480.Pp 481Load the kernel, a splash screen, and then autoboot in five seconds. 482Notice that a kernel must be loaded before any other 483.Ic load 484command is attempted. 485.Bd -literal -offset indent 486load kernel 487load splash_bmp 488load -t splash_image_data /boot/chuckrulez.bmp 489autoboot 5 490.Ed 491.Pp 492Set the disk unit of the root device to 2, and then boot. 493This would be needed in a system with two IDE disks, 494with the second IDE disk hardwired to ada2 instead of ada1. 495.Bd -literal -offset indent 496set root_disk_unit=2 497boot /boot/kernel/kernel 498.Ed 499.Pp 500Set the default device used for loading a kernel from a ZFS filesystem: 501.Bd -literal -offset indent 502set currdev=zfs:tank/ROOT/knowngood: 503.Ed 504.Pp 505.Sh ERRORS 506The following values are thrown by 507.Nm : 508.Bl -tag -width XXXXX -offset indent 509.It 100 510Any type of error in the processing of a builtin. 511.It -1 512.Ic Abort 513executed. 514.It -2 515.Ic Abort" 516executed. 517.It -56 518.Ic Quit 519executed. 520.It -256 521Out of interpreting text. 522.It -257 523Need more text to succeed -- will finish on next run. 524.It -258 525.Ic Bye 526executed. 527.It -259 528Unspecified error. 529.El 530.Sh SEE ALSO 531.Xr libsa 3 , 532.Xr loader.conf 5 , 533.Xr tuning 7 , 534.Xr boot 8 , 535.Xr btxld 8 536.Sh STANDARDS 537For the purposes of ANS Forth compliance, loader is an 538.Bf Em 539ANS Forth System with Environmental Restrictions, Providing 540.Ef 541.Bf Li 542.No .( , 543.No :noname , 544.No ?do , 545parse, pick, roll, refill, to, value, \e, false, true, 546.No <> , 547.No 0<> , 548compile\&, , erase, nip, tuck 549.Ef 550.Em and 551.Li marker 552.Bf Em 553from the Core Extensions word set, Providing the Exception Extensions 554word set, Providing the Locals Extensions word set, Providing the 555Memory-Allocation Extensions word set, Providing 556.Ef 557.Bf Li 558\&.s, 559bye, forget, see, words, 560\&[if], 561\&[else] 562.Ef 563.Em and 564.Li [then] 565.Bf Em 566from the Programming-Tools extension word set, Providing the 567Search-Order extensions word set. 568.Ef 569.Sh HISTORY 570The 571.Nm 572first appeared in 573.Fx 3.1 . 574.Sh AUTHORS 575.An -nosplit 576The 577.Nm 578was written by 579.An Michael Smith Aq msmith@FreeBSD.org . 580.Pp 581.Tn FICL 582was written by 583.An John Sadler Aq john_sadler@alum.mit.edu . 584
