stand/man/loader_4th.8

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