diff options
| -rw-r--r-- | sys/boot/common/loader.8 | 747 | ||||
| -rw-r--r-- | sys/boot/i386/loader/Makefile | 5 | ||||
| -rw-r--r-- | sys/boot/i386/loader/loader.8 | 747 |
3 files changed, 1497 insertions, 2 deletions
diff --git a/sys/boot/common/loader.8 b/sys/boot/common/loader.8 new file mode 100644 index 0000000..32133d8 --- /dev/null +++ b/sys/boot/common/loader.8 @@ -0,0 +1,747 @@ +.\" 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. +.\" +.\" $Id$ +.\" +.\" Note: The date here should be updated whenever a non-trivial +.\" change is made to the manual page. +.Dd March 14, 1999 +.Dt LOADER 8 +.Os +.Sh NAME +.Nm loader +.Nd system bootstrap stage three +.Sh DESCRIPTION +The program called +.Nm +is the third stage of FreeBSD's three stage bootstrap. +It is a +.Pa BTX +client linked statically to libstand(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-friendlyness. 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 comconsole +if the previous boot stage used that. 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 it's vocabulary, and +.Pa /boot/boot.4th +will be 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, and, failing that, +.Pa /boot/boot.conf +will be read for historical reasons. These files are processed +through the +.Ic include +command, which read 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 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. +.Sh BUILTIN COMMANDS +.Nm Loader Ns No 's +builtin commands take it's 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. +.Pp +The builtin commands available are: +.Pp +.Bl -tag -width Ds -compact -offset indent +.It Ic autoboot Op Ar seconds +Proceeds to bootstrap the system after a number of seconds, if not +interrupted by the user. Displays a countdown prompt warning the +user the system is about to be booted, unless interrupted by a key +press. The kernel will be loaded first if necessary. Defaults to +10 seconds. +.Pp +.It Ic bcachestat +Displays statistics about disk cache usage. For depuration only. +.Pp +.It Ic boot +.It Ic boot Ar kernelname Op Cm ... +.It Ic boot Fl flag Cm ... +Immediately proceeds to bootstrap the system, loading the kernel +if necessary. Any flags or arguments are passed to the kernel, but they +must precede the kernel name, if a kernel name is provided. +.Pp +.It Ic echo Xo +.Op Fl n +.Op Aq message +.Xc +Displays a text on the screen. A new line will be printed unless +.Fl n +is specified. +.Pp +.It Ic heap +Displays memory usage statistics. For debugging purposes only. +.Pp +.It Ic help Op topic Op subtopic +Shows help messages read from +.Pa /boot/loader.help . +The special topic +.Em index +will list the topics available. +.Pp +.It Ic include Ar file Op Ar +Process script files. Each file is, at a turn, completely read into +memory, and then have each of it's lines passed to the command line +interpreter. If any error is returned by the interpreter, the include +commands aborts immediately, without reading any other files, and +returns an error itself (see +.Sx ERRORS ) . +.Pp +.It Ic load Xo +.Op Fl t Ar type +.Ar file Cm ... +.Xc +Loads a kernel, kernel loadable module (kld), or a file of opaque +contents tagged as being of the type +.Ar type . +Kernel and modules can be either in a.out or elf format. Any arguments +passed after the name of the file to be loaded will be passed as +arguments to that file. Notice, though, that, at the present, this does +not work for the kernel. +.Pp +.It Ic ls Xo +.Op Fl l +.Op Ar path +.Xc +Displays a listing of files in the directory +.Ar path , +or the root directory if +.Ar path +is not specified. If +.Fl l +is specified, file sizes will be shown too. +.Pp +.It Ic lsdev Op Fl v +Lists all of the devices from which it may be possible to load modules. If +.Fl v +is specified, more details are printed. +.Pp +.It Ic lsmod Op Fl v +Displays loaded modules. If +.Fl v +is specified, more details are shown. +.Pp +.It Ic more Ar file Op Ar +Display the files specified, with a pause at each +.Va LINES +displayed. +.Pp +.It Ic pnpscan Op Fl v +Scans for Plug-and-Play devices. This is not functional at the present. +.Pp +.It Ic read Xo +.Op Fl t Ar seconds +.Op Fl p Ar prompt +.Op Va variable +.Xc +Reads a line of input from the terminal, storing it in +.Va variable +if specified. A timeout can be specified with +.Fl t , +though it will be canceled at the first key pressed. A prompt may +also be displayed through the +.Fl p +flag. +.Pp +.It Ic reboot +Immediately reboots the system. +.Pp +.It Ic set Ar variable +.It Ic set Ar variable Ns = Ns Ar value +Set loader's environment variables. +.Pp +.It Ic show Op Va variable +Displays the specified variable's value, or all variables and their +values if +.Va variable +is not specified. +.Pp +.It Ic unload +Remove all modules from memory. +.Pp +.It Ic unset Va variable +Removes +.Va variable +from the environment. +.Pp +.It Ic \&? +Same as +.Dq help index . +.Pp +.El +.Ss BUILTIN ENVIRONMENT VARIABLES +The +.Nm +has actually two different kinds of +.Sq environment +variables. There are ANS Forth's +.Em environmental queries , +and a separate space of environment variables used by builtins, which +are not directly available to Forth words. It is the later ones that +this session covers. +.Pp +Environment variables can be set and unset through the use of the +.Ic set +and +.Ic unset +builtins, and have their value interactively examined through the +use of the +.Ic show +builtin. Their values can also be accessed as described in +.Sx BUILTIN PARSER . +.Pp +Notice that this environment variables are not inherited by any shell +after the system has been booted. +.Pp +A few variables are set automatically by +.Nm . +Others can affect either +.Nm +or kernel's behavior at boot. While some of these may require a value, +others define behavior just by being set. These are described below. +.Bl -tag -width bootfile -offset indent +.It Va autoboot_delay +Number of seconds +.Ic autoboot +will wait before booting. If this variable is not defined, +.Ic autoboot +will default to 10 seconds. +.Pp +If set to +.Dq NO , +no +.Ic autoboot +will be automatically attempted after processing +.Pa /boot/loader.rc , +though explict +.Ic autoboot Ns 's +will be processed normally, defaulting to 10 seconds delay. +.It Va boot_askname +Instructs the kernel to prompt the user for the name of the root device +when the kernel is booted. +.It Va boot_ddb +Instructs the kernel to start in the DDB debugger, rather than +proceeding to initialise when booted. +.It Va boot_gdb +Selects gdb-remote mode for the kernel debugger by default. +.It Va boot_single +Prevents the kernel from initiating a multi-user startup, single-user +mode will be entered when the kernel has finished device probes. +.It Va boot_userconfig +Requests that the kernel's interactive device configuration program +be run when the kernel is booted. +.It Va boot_verbose +Setting this variable causes extra debugging information to be printed +by the kernel during the boot phase. +.It Va bootfile +List of semicolon-separated search path for bootable kernels. The default +is +.Li Dq kernel;kernel.old . +.It Va console +Defines the current console. +.It Va currdev +Selects the default device. Syntax for devices is odd. +.It Va interpret +Has the value +.Li Dq ok +if the Forth's current state is interpreting. +.It Va LINES +Define the number of lines on the screen, to be used by the pager. +.It Va module_path +Sets the list of directories which will be searched in for modules +named in a load command or implicitly required by a dependancy. The +default value for this variable is +.Li Dq /;/boot;/modules . +.It Va num_ide_disks +Sets the number of IDE disks as a work around for some problems in +finding the root disk at boot. This has been deprecated in favour of +.Va root_disk_unit . +.It Va prompt +Value of +.Nm Ns No 's +prompt. Defaults to +.Li Dq "${currdev}>" . +.It Va root_disk_unit +If the code which detects the disk unit number for the root disk is +confused, eg. by a mix of SCSI and IDE disks, or IDE disks with +gaps in the sequence (eg. no primary slave), the unit number can +be forced by setting this variable. +.It Va rootdev +By default the value of +.Va currdev +is used to set the root filesystem +when the kernel is booted. This can be overridden by setting +.Va rootdev +explicitly. +.El +.Pp +Other variables are used to override kernel tunnable parameters. +The following tunables are available: +.Bl -tag -width Va -offset indent +.It Va kern.ipc.nmbclusters +Set the number of mbuf clusters to be allocated. The value +cannot be set below the default determined when the kernel +was compiled. Modifies +.Va NMBCLUSTERS . +.It Va kern.vm.kmem.size +Sets the size of kernel memory (bytes). This overrides +completely the value determined when the kernel was +compiled. Modifies +.Va VM_KMEM_SIZE . +.It Va machdep.pccard.pcic_irq +Overrides the IRQ normally assigned to a PCCARD controller. +Typically the first available interrupt will be allocated, +which may conflict with other hardware. If this value is +set to 0, an interrupt will not be assigned and the +controller will operate in polled mode only. +.It Va net.inet.tcp.tcbhashsize +Overrides the compile-time set value of +.Va TCBHASHSIZE +or the preset default of 512. Must be a power of 2. +.El +.Ss BUILTIN PARSER +When a builtin command is executed, the rest of the line is taken +by it as arguments, and it's 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: +.Pp +.Bl -enum +.It +All backslash characters are preprocessed. +.Bl -bullet +.It +\eb , \ef , \er , \en and \et are processed as by C's +.fn printf() . +.It +\es is converted to a space. +.It +\ev is converted to +.Tn ASCII +11. +.It +\ez is just skipped. +.It +\eN and \eNN 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 semantics on the step 2 described below. +.It +\e\e will be replaced with a single \e . +.It +In any other occurance, 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 environemnt variable +.Va VARIABLE . +.It +Passes multiple space-delimited arguments to the builtin command called. +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 it's trade-offs. If the +execution token of a builtin is acquired (through +.Ic No ' +or +.Ic No ['] ) , +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 particular annoying for programs that want or need to +treat exceptions. In this case, it is recommended the use of a proxy. +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 in four groups. The +.Tn ANS +Forth standard words, extra +.Tn FICL +words, extra +.Os +words, and the builtin commands. The later 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 -offset indent +.It Ic .env +.It Ic .ver +.It Ic -roll +.It Ic 2constant +.It Ic >name +.It Ic body> +.It Ic compare +This 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 XXXXXXX -offset indent +.It Ic tib> Pq -- Ar addr len +Returns the remainder of the input buffer as a string on the stack. +.It Ic \&% Pq -- +Evaluates the remainder of the input buffer under a +.Ic catch +exception guard. +.It Ic \&$ Pq -- +Evaluates the remainder of the input buffer, after having printed it first. +.It Ic fopen Pq Ar addr len -- fd +Open a file. Returns a file descriptor, or -1 in case of failure. +.It Ic fclose Pq Ar fd -- +Closes a file. +.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 fload Pq Ar fd -- +Process file +.Em fd . +.It Ic fkey Pq Ar fd -- char +Reads a single character from a file. +.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 seconds Pq -- Ar u +Returns the number of seconds since midnight. +.It Ic trace! Pq Ar flag -- +Activates or deactivates tracing. Does not work with +.Ic catch . +.It Ic outb Pq Ar port char -- +Writes a byte to a port. +.It Ic inb Pq Ar port -- char +Reads a byte from a port. +.El +.Ss FREEBSD DEFINED ENVIRONMENTAL QUERIES +.Bl -tag -width Ds -offset indent +.It arch-i386 +.Ic TRUE +if the architecture is IA32. +.It arch-alpha +.Ic TRUE +if the architecture is AXP. +.It FreeBSD_version +.Fx +version at compile time. +.It loader_version +.Nm +version. +.El +.Ss SYSTEM DOCUMENTATION +.Sh FILES +.Bl -tag -width /dev/loader.helpX -compact +.It Pa /boot/loader +.Nm +itself. +.It Pa /boot/boot.4th +Additional +.Tn FICL +initialization. +.It Pa /boot/boot.conf +.Nm +bootstrapping script. Deprecated. +.It Pa /boot/loader.rc +.Nm +bootstrapping script. +.It Pa /boot/loader.help +Loaded by +.Ic help . +Contains the help messages. +.El +.Sh EXAMPLES +Boot in single user mode: +.Pp +.Dl boot -s +.Pp +Loads kernel's user configuration file. Notice that a kernel must be +loaded before any other +.Ic load +command is attempted. +.Pp +.Bd -literal -offset indent -compact +load kernel +load -t userconfig_script /boot/kernel.conf +.Ed +.Pp +Loads the kernel, a splash screen, and then autoboots in five seconds. +.Pp +.Bd -literal -offset indent -compact +load kernel +load splash_bmp +load -t splash_image_data /boot/chuckrulez.bmp +autoboot 5 +.Ed +.Pp +Sets the disk unit of the root device to 2, and then boots. This would +be needed in the case of a two IDE disks system, with the second IDE +hardwired to wd2 instead of wd1. +.Pp +.Bd -literal -offset indent -compact +set root_disk_unit=2 +boot /kernel +.Ed +.Pp +See also: +.Bl -tag -width /usr/share/examples/bootforth/X +.It Pa /boot/loader.4th +Extra builtin-like words. +.It Pa /boot/support.4th +.Pa loader.conf +processing words. +.It Pa /usr/share/examples/bootforth/ +Assorted examples. +.El +.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 libstand 3 , +.Xr loader.conf 5 , +.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 No [then] +.Bf Em +from the Programming-Tools extension word set, Providing the +Search-Order extensions word set. +.Ef +.Sh HISTORY +.Nm +first appeared in +.Fx 3.1 . +.Sh AUTHORS +.Bl -item +.It +.Nm +was written by +.An Michael Smith Aq msmisth@freebsd.org . +.It +.Tn FICL +was written by +.An John Sadler Aq john_sadler@alum.mit.edu . +.El +.Sh BUGS +.Tn FICL +is case sensitive. Though this is not a standard violation, all Forth +words are lower cased, which would result in a standard violation. Do +not rely on this bug. +.Pp +The +.Ic expect +and +.Ic accept +words will read from the input buffer instead of the console. The later +will be fixed, but the former will not. + diff --git a/sys/boot/i386/loader/Makefile b/sys/boot/i386/loader/Makefile index dcc0e71..7e35ea4 100644 --- a/sys/boot/i386/loader/Makefile +++ b/sys/boot/i386/loader/Makefile @@ -1,8 +1,9 @@ -# $Id: Makefile,v 1.29 1999/02/24 01:37:23 msmith Exp $ +# $Id: Makefile,v 1.30 1999/03/10 03:34:14 dcs Exp $ BASE= loader PROG= ${BASE} -NOMAN= +MAN8= loader.8 +#NOMAN= STRIP= NEWVERSWHAT= "bootstrap loader" BINDIR?= /boot diff --git a/sys/boot/i386/loader/loader.8 b/sys/boot/i386/loader/loader.8 new file mode 100644 index 0000000..32133d8 --- /dev/null +++ b/sys/boot/i386/loader/loader.8 @@ -0,0 +1,747 @@ +.\" 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. +.\" +.\" $Id$ +.\" +.\" Note: The date here should be updated whenever a non-trivial +.\" change is made to the manual page. +.Dd March 14, 1999 +.Dt LOADER 8 +.Os +.Sh NAME +.Nm loader +.Nd system bootstrap stage three +.Sh DESCRIPTION +The program called +.Nm +is the third stage of FreeBSD's three stage bootstrap. +It is a +.Pa BTX +client linked statically to libstand(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-friendlyness. 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 comconsole +if the previous boot stage used that. 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 it's vocabulary, and +.Pa /boot/boot.4th +will be 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, and, failing that, +.Pa /boot/boot.conf +will be read for historical reasons. These files are processed +through the +.Ic include +command, which read 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 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. +.Sh BUILTIN COMMANDS +.Nm Loader Ns No 's +builtin commands take it's 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. +.Pp +The builtin commands available are: +.Pp +.Bl -tag -width Ds -compact -offset indent +.It Ic autoboot Op Ar seconds +Proceeds to bootstrap the system after a number of seconds, if not +interrupted by the user. Displays a countdown prompt warning the +user the system is about to be booted, unless interrupted by a key +press. The kernel will be loaded first if necessary. Defaults to +10 seconds. +.Pp +.It Ic bcachestat +Displays statistics about disk cache usage. For depuration only. +.Pp +.It Ic boot +.It Ic boot Ar kernelname Op Cm ... +.It Ic boot Fl flag Cm ... +Immediately proceeds to bootstrap the system, loading the kernel +if necessary. Any flags or arguments are passed to the kernel, but they +must precede the kernel name, if a kernel name is provided. +.Pp +.It Ic echo Xo +.Op Fl n +.Op Aq message +.Xc +Displays a text on the screen. A new line will be printed unless +.Fl n +is specified. +.Pp +.It Ic heap +Displays memory usage statistics. For debugging purposes only. +.Pp +.It Ic help Op topic Op subtopic +Shows help messages read from +.Pa /boot/loader.help . +The special topic +.Em index +will list the topics available. +.Pp +.It Ic include Ar file Op Ar +Process script files. Each file is, at a turn, completely read into +memory, and then have each of it's lines passed to the command line +interpreter. If any error is returned by the interpreter, the include +commands aborts immediately, without reading any other files, and +returns an error itself (see +.Sx ERRORS ) . +.Pp +.It Ic load Xo +.Op Fl t Ar type +.Ar file Cm ... +.Xc +Loads a kernel, kernel loadable module (kld), or a file of opaque +contents tagged as being of the type +.Ar type . +Kernel and modules can be either in a.out or elf format. Any arguments +passed after the name of the file to be loaded will be passed as +arguments to that file. Notice, though, that, at the present, this does +not work for the kernel. +.Pp +.It Ic ls Xo +.Op Fl l +.Op Ar path +.Xc +Displays a listing of files in the directory +.Ar path , +or the root directory if +.Ar path +is not specified. If +.Fl l +is specified, file sizes will be shown too. +.Pp +.It Ic lsdev Op Fl v +Lists all of the devices from which it may be possible to load modules. If +.Fl v +is specified, more details are printed. +.Pp +.It Ic lsmod Op Fl v +Displays loaded modules. If +.Fl v +is specified, more details are shown. +.Pp +.It Ic more Ar file Op Ar +Display the files specified, with a pause at each +.Va LINES +displayed. +.Pp +.It Ic pnpscan Op Fl v +Scans for Plug-and-Play devices. This is not functional at the present. +.Pp +.It Ic read Xo +.Op Fl t Ar seconds +.Op Fl p Ar prompt +.Op Va variable +.Xc +Reads a line of input from the terminal, storing it in +.Va variable +if specified. A timeout can be specified with +.Fl t , +though it will be canceled at the first key pressed. A prompt may +also be displayed through the +.Fl p +flag. +.Pp +.It Ic reboot +Immediately reboots the system. +.Pp +.It Ic set Ar variable +.It Ic set Ar variable Ns = Ns Ar value +Set loader's environment variables. +.Pp +.It Ic show Op Va variable +Displays the specified variable's value, or all variables and their +values if +.Va variable +is not specified. +.Pp +.It Ic unload +Remove all modules from memory. +.Pp +.It Ic unset Va variable +Removes +.Va variable +from the environment. +.Pp +.It Ic \&? +Same as +.Dq help index . +.Pp +.El +.Ss BUILTIN ENVIRONMENT VARIABLES +The +.Nm +has actually two different kinds of +.Sq environment +variables. There are ANS Forth's +.Em environmental queries , +and a separate space of environment variables used by builtins, which +are not directly available to Forth words. It is the later ones that +this session covers. +.Pp +Environment variables can be set and unset through the use of the +.Ic set +and +.Ic unset +builtins, and have their value interactively examined through the +use of the +.Ic show +builtin. Their values can also be accessed as described in +.Sx BUILTIN PARSER . +.Pp +Notice that this environment variables are not inherited by any shell +after the system has been booted. +.Pp +A few variables are set automatically by +.Nm . +Others can affect either +.Nm +or kernel's behavior at boot. While some of these may require a value, +others define behavior just by being set. These are described below. +.Bl -tag -width bootfile -offset indent +.It Va autoboot_delay +Number of seconds +.Ic autoboot +will wait before booting. If this variable is not defined, +.Ic autoboot +will default to 10 seconds. +.Pp +If set to +.Dq NO , +no +.Ic autoboot +will be automatically attempted after processing +.Pa /boot/loader.rc , +though explict +.Ic autoboot Ns 's +will be processed normally, defaulting to 10 seconds delay. +.It Va boot_askname +Instructs the kernel to prompt the user for the name of the root device +when the kernel is booted. +.It Va boot_ddb +Instructs the kernel to start in the DDB debugger, rather than +proceeding to initialise when booted. +.It Va boot_gdb +Selects gdb-remote mode for the kernel debugger by default. +.It Va boot_single +Prevents the kernel from initiating a multi-user startup, single-user +mode will be entered when the kernel has finished device probes. +.It Va boot_userconfig +Requests that the kernel's interactive device configuration program +be run when the kernel is booted. +.It Va boot_verbose +Setting this variable causes extra debugging information to be printed +by the kernel during the boot phase. +.It Va bootfile +List of semicolon-separated search path for bootable kernels. The default +is +.Li Dq kernel;kernel.old . +.It Va console +Defines the current console. +.It Va currdev +Selects the default device. Syntax for devices is odd. +.It Va interpret +Has the value +.Li Dq ok +if the Forth's current state is interpreting. +.It Va LINES +Define the number of lines on the screen, to be used by the pager. +.It Va module_path +Sets the list of directories which will be searched in for modules +named in a load command or implicitly required by a dependancy. The +default value for this variable is +.Li Dq /;/boot;/modules . +.It Va num_ide_disks +Sets the number of IDE disks as a work around for some problems in +finding the root disk at boot. This has been deprecated in favour of +.Va root_disk_unit . +.It Va prompt +Value of +.Nm Ns No 's +prompt. Defaults to +.Li Dq "${currdev}>" . +.It Va root_disk_unit +If the code which detects the disk unit number for the root disk is +confused, eg. by a mix of SCSI and IDE disks, or IDE disks with +gaps in the sequence (eg. no primary slave), the unit number can +be forced by setting this variable. +.It Va rootdev +By default the value of +.Va currdev +is used to set the root filesystem +when the kernel is booted. This can be overridden by setting +.Va rootdev +explicitly. +.El +.Pp +Other variables are used to override kernel tunnable parameters. +The following tunables are available: +.Bl -tag -width Va -offset indent +.It Va kern.ipc.nmbclusters +Set the number of mbuf clusters to be allocated. The value +cannot be set below the default determined when the kernel +was compiled. Modifies +.Va NMBCLUSTERS . +.It Va kern.vm.kmem.size +Sets the size of kernel memory (bytes). This overrides +completely the value determined when the kernel was +compiled. Modifies +.Va VM_KMEM_SIZE . +.It Va machdep.pccard.pcic_irq +Overrides the IRQ normally assigned to a PCCARD controller. +Typically the first available interrupt will be allocated, +which may conflict with other hardware. If this value is +set to 0, an interrupt will not be assigned and the +controller will operate in polled mode only. +.It Va net.inet.tcp.tcbhashsize +Overrides the compile-time set value of +.Va TCBHASHSIZE +or the preset default of 512. Must be a power of 2. +.El +.Ss BUILTIN PARSER +When a builtin command is executed, the rest of the line is taken +by it as arguments, and it's 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: +.Pp +.Bl -enum +.It +All backslash characters are preprocessed. +.Bl -bullet +.It +\eb , \ef , \er , \en and \et are processed as by C's +.fn printf() . +.It +\es is converted to a space. +.It +\ev is converted to +.Tn ASCII +11. +.It +\ez is just skipped. +.It +\eN and \eNN 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 semantics on the step 2 described below. +.It +\e\e will be replaced with a single \e . +.It +In any other occurance, 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 environemnt variable +.Va VARIABLE . +.It +Passes multiple space-delimited arguments to the builtin command called. +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 it's trade-offs. If the +execution token of a builtin is acquired (through +.Ic No ' +or +.Ic No ['] ) , +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 particular annoying for programs that want or need to +treat exceptions. In this case, it is recommended the use of a proxy. +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 in four groups. The +.Tn ANS +Forth standard words, extra +.Tn FICL +words, extra +.Os +words, and the builtin commands. The later 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 -offset indent +.It Ic .env +.It Ic .ver +.It Ic -roll +.It Ic 2constant +.It Ic >name +.It Ic body> +.It Ic compare +This 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 XXXXXXX -offset indent +.It Ic tib> Pq -- Ar addr len +Returns the remainder of the input buffer as a string on the stack. +.It Ic \&% Pq -- +Evaluates the remainder of the input buffer under a +.Ic catch +exception guard. +.It Ic \&$ Pq -- +Evaluates the remainder of the input buffer, after having printed it first. +.It Ic fopen Pq Ar addr len -- fd +Open a file. Returns a file descriptor, or -1 in case of failure. +.It Ic fclose Pq Ar fd -- +Closes a file. +.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 fload Pq Ar fd -- +Process file +.Em fd . +.It Ic fkey Pq Ar fd -- char +Reads a single character from a file. +.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 seconds Pq -- Ar u +Returns the number of seconds since midnight. +.It Ic trace! Pq Ar flag -- +Activates or deactivates tracing. Does not work with +.Ic catch . +.It Ic outb Pq Ar port char -- +Writes a byte to a port. +.It Ic inb Pq Ar port -- char +Reads a byte from a port. +.El +.Ss FREEBSD DEFINED ENVIRONMENTAL QUERIES +.Bl -tag -width Ds -offset indent +.It arch-i386 +.Ic TRUE +if the architecture is IA32. +.It arch-alpha +.Ic TRUE +if the architecture is AXP. +.It FreeBSD_version +.Fx +version at compile time. +.It loader_version +.Nm +version. +.El +.Ss SYSTEM DOCUMENTATION +.Sh FILES +.Bl -tag -width /dev/loader.helpX -compact +.It Pa /boot/loader +.Nm +itself. +.It Pa /boot/boot.4th +Additional +.Tn FICL +initialization. +.It Pa /boot/boot.conf +.Nm +bootstrapping script. Deprecated. +.It Pa /boot/loader.rc +.Nm +bootstrapping script. +.It Pa /boot/loader.help +Loaded by +.Ic help . +Contains the help messages. +.El +.Sh EXAMPLES +Boot in single user mode: +.Pp +.Dl boot -s +.Pp +Loads kernel's user configuration file. Notice that a kernel must be +loaded before any other +.Ic load +command is attempted. +.Pp +.Bd -literal -offset indent -compact +load kernel +load -t userconfig_script /boot/kernel.conf +.Ed +.Pp +Loads the kernel, a splash screen, and then autoboots in five seconds. +.Pp +.Bd -literal -offset indent -compact +load kernel +load splash_bmp +load -t splash_image_data /boot/chuckrulez.bmp +autoboot 5 +.Ed +.Pp +Sets the disk unit of the root device to 2, and then boots. This would +be needed in the case of a two IDE disks system, with the second IDE +hardwired to wd2 instead of wd1. +.Pp +.Bd -literal -offset indent -compact +set root_disk_unit=2 +boot /kernel +.Ed +.Pp +See also: +.Bl -tag -width /usr/share/examples/bootforth/X +.It Pa /boot/loader.4th +Extra builtin-like words. +.It Pa /boot/support.4th +.Pa loader.conf +processing words. +.It Pa /usr/share/examples/bootforth/ +Assorted examples. +.El +.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 libstand 3 , +.Xr loader.conf 5 , +.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 No [then] +.Bf Em +from the Programming-Tools extension word set, Providing the +Search-Order extensions word set. +.Ef +.Sh HISTORY +.Nm +first appeared in +.Fx 3.1 . +.Sh AUTHORS +.Bl -item +.It +.Nm +was written by +.An Michael Smith Aq msmisth@freebsd.org . +.It +.Tn FICL +was written by +.An John Sadler Aq john_sadler@alum.mit.edu . +.El +.Sh BUGS +.Tn FICL +is case sensitive. Though this is not a standard violation, all Forth +words are lower cased, which would result in a standard violation. Do +not rely on this bug. +.Pp +The +.Ic expect +and +.Ic accept +words will read from the input buffer instead of the console. The later +will be fixed, but the former will not. + |
