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