The man page, version 0.1.
This commit is contained in:
parent
6b23715173
commit
306a07af57
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=44780
747
sys/boot/common/loader.8
Normal file
747
sys/boot/common/loader.8
Normal file
@ -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.
|
||||
|
@ -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
|
||||
|
747
sys/boot/i386/loader/loader.8
Normal file
747
sys/boot/i386/loader/loader.8
Normal file
@ -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.
|
||||
|
Loading…
Reference in New Issue
Block a user