123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584 |
- .\" Copyright (c) 1999 Daniel C. Sobral
- .\" All rights reserved.
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
- .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
- .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- .\" SUCH DAMAGE.
- .\"
- .Dd September 29, 2021
- .Dt LOADER_4TH 8
- .Os
- .Sh NAME
- .Nm loader_4th
- .Nd kernel bootstrapping final stage
- .Sh DESCRIPTION
- The program called
- .Nm
- is the final stage of
- .Fx Ns 's
- kernel bootstrapping process.
- On IA32 (i386) architectures, it is a
- .Pa BTX
- client.
- It is linked statically to
- .Xr libsa 3
- and usually located in the directory
- .Pa /boot .
- .Pp
- It provides a scripting language that can be used to
- automate tasks, do pre-configuration or assist in recovery
- procedures.
- This scripting language is roughly divided in
- two main components.
- The smaller one is a set of commands
- designed for direct use by the casual user, called "builtin
- commands" for historical reasons.
- The main drive behind these commands is user-friendliness.
- The bigger component is an
- .Tn ANS
- Forth compatible Forth interpreter based on FICL, by
- .An John Sadler .
- .Pp
- During initialization,
- .Nm
- will probe for a console and set the
- .Va console
- variable, or set it to serial console
- .Pq Dq Li comconsole
- if the previous boot stage used that.
- If multiple consoles are selected, they will be listed separated by spaces.
- Then, devices are probed,
- .Va currdev
- and
- .Va loaddev
- are set, and
- .Va LINES
- is set to 24.
- Next,
- .Tn FICL
- is initialized, the builtin words are added to its vocabulary, and
- .Pa /boot/boot.4th
- is processed if it exists.
- No disk switching is possible while that file is being read.
- The inner interpreter
- .Nm
- will use with
- .Tn FICL
- is then set to
- .Ic interpret ,
- which is
- .Tn FICL Ns 's
- default.
- After that,
- .Pa /boot/loader.rc
- is processed if available.
- These files are processed through the
- .Ic include
- command, which reads all of them into memory before processing them,
- making disk changes possible.
- .Pp
- At this point, if an
- .Ic autoboot
- has not been tried, and if
- .Va autoboot_delay
- is not set to
- .Dq Li NO
- (not case sensitive), then an
- .Ic autoboot
- will be tried.
- If the system gets past this point,
- .Va prompt
- will be set and
- .Nm
- will engage interactive mode.
- Please note that historically even when
- .Va autoboot_delay
- is set to
- .Dq Li 0
- user will be able to interrupt autoboot process by pressing some key
- on the console while kernel and modules are being loaded.
- In some
- cases such behaviour may be undesirable, to prevent it set
- .Va autoboot_delay
- to
- .Dq Li -1 ,
- in this case
- .Nm
- will engage interactive mode only if
- .Ic autoboot
- has failed.
- .Sh BUILTIN COMMANDS
- In
- .Nm ,
- builtin commands take parameters from the command line.
- Presently,
- the only way to call them from a script is by using
- .Pa evaluate
- on a string.
- If an error condition occurs, an exception will be generated,
- which can be intercepted using
- .Tn ANS
- Forth exception handling
- words.
- If not intercepted, an error message will be displayed and
- the interpreter's state will be reset, emptying the stack and restoring
- interpreting mode.
- The commands are described in the
- .Xr loader_simp 8
- .Dq BUILTIN COMMANDS
- section.
- .Ss BUILTIN ENVIRONMENT VARIABLES
- The environment variables common to all interpreters are described in the
- .Xr loader_simp 8
- .Dq BUILTIN ENVIRONMENT VARIABLES
- section.
- .Ss BUILTIN PARSER
- When a builtin command is executed, the rest of the line is taken
- by it as arguments, and it is processed by a special parser which
- is not used for regular Forth commands.
- .Pp
- This special parser applies the following rules to the parsed text:
- .Bl -enum
- .It
- All backslash characters are preprocessed.
- .Bl -bullet
- .It
- \eb , \ef , \er , \en and \et are processed as in C.
- .It
- \es is converted to a space.
- .It
- \ev is converted to
- .Tn ASCII
- 11.
- .It
- \ez is just skipped.
- Useful for things like
- .Dq \e0xf\ez\e0xf .
- .It
- \e0xN and \e0xNN are replaced by the hex N or NN.
- .It
- \eNNN is replaced by the octal NNN
- .Tn ASCII
- character.
- .It
- \e" , \e' and \e$ will escape these characters, preventing them from
- receiving special treatment in Step 2, described below.
- .It
- \e\e will be replaced with a single \e .
- .It
- In any other occurrence, backslash will just be removed.
- .El
- .It
- Every string between non-escaped quotes or double-quotes will be treated
- as a single word for the purposes of the remaining steps.
- .It
- Replace any
- .Li $VARIABLE
- or
- .Li ${VARIABLE}
- with the value of the environment variable
- .Va VARIABLE .
- .It
- Space-delimited arguments are passed to the called builtin command.
- Spaces can also be escaped through the use of \e\e .
- .El
- .Pp
- An exception to this parsing rule exists, and is described in
- .Sx BUILTINS AND FORTH .
- .Ss BUILTINS AND FORTH
- All builtin words are state-smart, immediate words.
- If interpreted, they behave exactly as described previously.
- If they are compiled, though,
- they extract their arguments from the stack instead of the command line.
- .Pp
- If compiled, the builtin words expect to find, at execution time, the
- following parameters on the stack:
- .D1 Ar addrN lenN ... addr2 len2 addr1 len1 N
- where
- .Ar addrX lenX
- are strings which will compose the command line that will be parsed
- into the builtin's arguments.
- Internally, these strings are concatenated in from 1 to N,
- with a space put between each one.
- .Pp
- If no arguments are passed, a 0
- .Em must
- be passed, even if the builtin accepts no arguments.
- .Pp
- While this behavior has benefits, it has its trade-offs.
- If the execution token of a builtin is acquired (through
- .Ic '
- or
- .Ic ['] ) ,
- and then passed to
- .Ic catch
- or
- .Ic execute ,
- the builtin behavior will depend on the system state
- .Bf Em
- at the time
- .Ic catch
- or
- .Ic execute
- is processed!
- .Ef
- This is particularly annoying for programs that want or need to
- handle exceptions.
- In this case, the use of a proxy is recommended.
- For example:
- .Dl : (boot) boot ;
- .Sh FICL
- .Tn FICL
- is a Forth interpreter written in C, in the form of a forth
- virtual machine library that can be called by C functions and vice
- versa.
- .Pp
- In
- .Nm ,
- each line read interactively is then fed to
- .Tn FICL ,
- which may call
- .Nm
- back to execute the builtin words.
- The builtin
- .Ic include
- will also feed
- .Tn FICL ,
- one line at a time.
- .Pp
- The words available to
- .Tn FICL
- can be classified into four groups.
- The
- .Tn ANS
- Forth standard words, extra
- .Tn FICL
- words, extra
- .Fx
- words, and the builtin commands;
- the latter were already described.
- The
- .Tn ANS
- Forth standard words are listed in the
- .Sx STANDARDS
- section.
- The words falling in the two other groups are described in the
- following subsections.
- .Ss FICL EXTRA WORDS
- .Bl -tag -width wid-set-super
- .It Ic .env
- .It Ic .ver
- .It Ic -roll
- .It Ic 2constant
- .It Ic >name
- .It Ic body>
- .It Ic compare
- This is the STRING word set's
- .Ic compare .
- .It Ic compile-only
- .It Ic endif
- .It Ic forget-wid
- .It Ic parse-word
- .It Ic sliteral
- This is the STRING word set's
- .Ic sliteral .
- .It Ic wid-set-super
- .It Ic w@
- .It Ic w!
- .It Ic x.
- .It Ic empty
- .It Ic cell-
- .It Ic -rot
- .El
- .Ss FREEBSD EXTRA WORDS
- .Bl -tag -width XXXXXXXX
- .It Ic \&$ Pq --
- Evaluates the remainder of the input buffer, after having printed it first.
- .It Ic \&% Pq --
- Evaluates the remainder of the input buffer under a
- .Ic catch
- exception guard.
- .It Ic .#
- Works like
- .Ic "."
- but without outputting a trailing space.
- .It Ic fclose Pq Ar fd --
- Closes a file.
- .It Ic fkey Pq Ar fd -- char
- Reads a single character from a file.
- .It Ic fload Pq Ar fd --
- Processes a file
- .Em fd .
- .It Ic fopen Pq Ar addr len mode Li -- Ar fd
- Opens a file.
- Returns a file descriptor, or \-1 in case of failure.
- The
- .Ar mode
- parameter selects whether the file is to be opened for read access, write
- access, or both.
- The constants
- .Dv O_RDONLY , O_WRONLY ,
- and
- .Dv O_RDWR
- are defined in
- .Pa /boot/support.4th ,
- indicating read only, write only, and read-write access, respectively.
- .It Xo
- .Ic fread
- .Pq Ar fd addr len -- len'
- .Xc
- Tries to read
- .Em len
- bytes from file
- .Em fd
- into buffer
- .Em addr .
- Returns the actual number of bytes read, or -1 in case of error or end of
- file.
- .It Ic heap? Pq -- Ar cells
- Return the space remaining in the dictionary heap, in cells.
- This is not related to the heap used by dynamic memory allocation words.
- .It Ic inb Pq Ar port -- char
- Reads a byte from a port.
- .It Ic key Pq -- Ar char
- Reads a single character from the console.
- .It Ic key? Pq -- Ar flag
- Returns
- .Ic true
- if there is a character available to be read from the console.
- .It Ic ms Pq Ar u --
- Waits
- .Em u
- microseconds.
- .It Ic outb Pq Ar port char --
- Writes a byte to a port.
- .It Ic seconds Pq -- Ar u
- Returns the number of seconds since midnight.
- .It Ic tib> Pq -- Ar addr len
- Returns the remainder of the input buffer as a string on the stack.
- .It Ic trace! Pq Ar flag --
- Activates or deactivates tracing.
- Does not work with
- .Ic catch .
- .El
- .Ss FREEBSD DEFINED ENVIRONMENTAL QUERIES
- .Bl -tag -width Ds
- .It arch-i386
- .Ic TRUE
- if the architecture is IA32.
- .It FreeBSD_version
- .Fx
- version at compile time.
- .It loader_version
- .Nm
- version.
- .El
- .Sh SECURITY
- Access to the
- .Nm
- command line provides several ways of compromising system security,
- including, but not limited to:
- .Pp
- .Bl -bullet
- .It
- Booting from removable storage, by setting the
- .Va currdev
- or
- .Va loaddev
- variables
- .It
- Executing binary of choice, by setting the
- .Va init_path
- or
- .Va init_script
- variables
- .It
- Overriding ACPI DSDT to inject arbitrary code into the ACPI subsystem
- .El
- .Pp
- One can prevent unauthorized access
- to the
- .Nm
- command line by setting the
- .Va password ,
- or setting
- .Va autoboot_delay
- to -1.
- See
- .Xr loader.conf 5
- for details.
- In order for this to be effective, one should also configure the firmware
- (BIOS or UEFI) to prevent booting from unauthorized devices.
- .Sh MD
- Memory disk (MD) can be used when the
- .Nm
- was compiled with
- .Va MD_IMAGE_SIZE .
- The size of the memory disk is determined by
- .Va MD_IMAGE_SIZE .
- If MD available, a file system can be embedded into the
- .Nm
- with
- .Pa /sys/tools/embed_mfs.sh .
- Then, MD will be probed and be set to
- .Va currdev
- during initialization.
- .Pp
- Currently, MD is only supported in
- .Xr loader.efi 8 .
- .Sh FILES
- .Bl -tag -width /usr/share/examples/bootforth/ -compact
- .It Pa /boot/loader
- .Nm
- itself.
- .It Pa /boot/boot.4th
- Additional
- .Tn FICL
- initialization.
- .It Pa /boot/defaults/loader.conf
- .It Pa /boot/loader.4th
- Extra builtin-like words.
- .It Pa /boot/loader.conf
- .It Pa /boot/loader.conf.local
- .Nm
- configuration files, as described in
- .Xr loader.conf 5 .
- .It Pa /boot/loader.rc
- .Nm
- bootstrapping script.
- .It Pa /boot/loader.help
- Loaded by
- .Ic help .
- Contains the help messages.
- .It Pa /boot/support.4th
- .Pa loader.conf
- processing words.
- .It Pa /usr/share/examples/bootforth/
- Assorted examples.
- .El
- .Sh EXAMPLES
- Boot in single user mode:
- .Pp
- .Dl boot -s
- .Pp
- Load the kernel, a splash screen, and then autoboot in five seconds.
- Notice that a kernel must be loaded before any other
- .Ic load
- command is attempted.
- .Bd -literal -offset indent
- load kernel
- load splash_bmp
- load -t splash_image_data /boot/chuckrulez.bmp
- autoboot 5
- .Ed
- .Pp
- Set the disk unit of the root device to 2, and then boot.
- This would be needed in a system with two IDE disks,
- with the second IDE disk hardwired to ada2 instead of ada1.
- .Bd -literal -offset indent
- set root_disk_unit=2
- boot /boot/kernel/kernel
- .Ed
- .Pp
- Set the default device used for loading a kernel from a ZFS filesystem:
- .Bd -literal -offset indent
- set currdev=zfs:tank/ROOT/knowngood:
- .Ed
- .Pp
- .Sh ERRORS
- The following values are thrown by
- .Nm :
- .Bl -tag -width XXXXX -offset indent
- .It 100
- Any type of error in the processing of a builtin.
- .It -1
- .Ic Abort
- executed.
- .It -2
- .Ic Abort"
- executed.
- .It -56
- .Ic Quit
- executed.
- .It -256
- Out of interpreting text.
- .It -257
- Need more text to succeed -- will finish on next run.
- .It -258
- .Ic Bye
- executed.
- .It -259
- Unspecified error.
- .El
- .Sh SEE ALSO
- .Xr libsa 3 ,
- .Xr loader.conf 5 ,
- .Xr tuning 7 ,
- .Xr boot 8 ,
- .Xr btxld 8
- .Sh STANDARDS
- For the purposes of ANS Forth compliance, loader is an
- .Bf Em
- ANS Forth System with Environmental Restrictions, Providing
- .Ef
- .Bf Li
- .No .( ,
- .No :noname ,
- .No ?do ,
- parse, pick, roll, refill, to, value, \e, false, true,
- .No <> ,
- .No 0<> ,
- compile\&, , erase, nip, tuck
- .Ef
- .Em and
- .Li marker
- .Bf Em
- from the Core Extensions word set, Providing the Exception Extensions
- word set, Providing the Locals Extensions word set, Providing the
- Memory-Allocation Extensions word set, Providing
- .Ef
- .Bf Li
- \&.s,
- bye, forget, see, words,
- \&[if],
- \&[else]
- .Ef
- .Em and
- .Li [then]
- .Bf Em
- from the Programming-Tools extension word set, Providing the
- Search-Order extensions word set.
- .Ef
- .Sh HISTORY
- The
- .Nm
- first appeared in
- .Fx 3.1 .
- .Sh AUTHORS
- .An -nosplit
- The
- .Nm
- was written by
- .An Michael Smith Aq msmith@FreeBSD.org .
- .Pp
- .Tn FICL
- was written by
- .An John Sadler Aq john_sadler@alum.mit.edu .
|