The man page, version 0.1.

1 files changed, 747 insertions, 0 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.
+