loader(8)

NAME

loader - kernel bootstrapping final stage

DESCRIPTION

The program called loader is the final stage of FreeBSD's

kernel bootstrapping process. On IA32 (i386) architectures, it is a

BTX client. It
is linked statically to libstand(3) and usually located in

the directory
/boot.

It provides a scripting language that can be used to auto

mate tasks, do
pre-configuration or assist in recovery procedures. This

scripting language is roughly divided in two main components. The small

er one is a
set of commands designed for direct use by the casual user,

called
"builtin commands" for historical reasons. The main drive

behind these
commands is user-friendliness. The bigger component is an

ANS Forth compatible Forth interpreter based on FICL, by John Sadler.

During initialization, loader will probe for a console and

set the
console variable, or set it to serial console (``comcon

sole'') if the
previous boot stage used that. If multiple consoles are se

lected, they
will be listed separated by spaces. Then, devices are

probed, currdev
and loaddev are set, and LINES is set to 24. Next, FICL is

initialized,
the builtin words are added to its vocabulary, and

/boot/boot.4th is processed if it exists. No disk switching is possible while

that file is
being read. The inner interpreter loader will use with FICL

is then set
to interpret, which is FICL's default. After that,

/boot/loader.rc is
processed if available, and, failing that, /boot/boot.conf

is read for
historical reasons. These files are processed through the

include command, which reads all of them into memory before processing

them, making
disk changes possible.

At this point, if an autoboot has not been tried, and if

autoboot_delay
is not set to ``NO'' (not case sensitive), then an autoboot

will be
tried. If the system gets past this point, prompt will be

set and loader
will engage interactive mode. Please note that historically

even when
autoboot_delay is set to ``0'' user will be able to inter

rupt autoboot
process by pressing some key on the console while kernel and

modules are
being loaded. In some cases such behaviour may be undesir

able, to prevent it set autoboot_delay to ``-1'', in this case loader

will engage
interactive mode only if autoboot has failed.

BUILTIN COMMANDS

In loader, builtin commands take parameters from the command

line.
Presently, the only way to call them from a script is by us

ing evaluate
on a string. If an error condition occurs, an exception

will be generated, which can be intercepted using 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 restor

ing interpreting mode.

The builtin commands available are:

autoboot [seconds [prompt]]

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.

bcachestat

Displays statistics about disk cache usage. For

depuration only.

boot
boot kernelname [...]
boot -flag ...

Immediately proceeds to bootstrap the system, load

ing 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.

WARNING: The behavior of this builtin is changed if

loader.4th(8)
is loaded.

echo [-n] [<message>]

Displays text on the screen. A new line will be

printed unless
-n is specified.

heap Displays memory usage statistics. For debugging

purposes only.

help [topic [subtopic]]

Shows help messages read from /boot/loader.help.

The special
topic index will list the topics available.

include file [file ...]

Process script files. Each file, in turn, is com

pletely read
into memory, and then each of its lines is passed to

the command
line interpreter. If any error is returned by the

interpreter,
the include command aborts immediately, without

reading any other
files, and returns an error itself (see ERRORS).

load [-t type] file ...

Loads a kernel, kernel loadable module (kld), or

file of opaque
contents tagged as being of the type 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. Currently, argument passing does not

work for the
kernel.

ls [-l] [path]

Displays a listing of files in the directory path,

or the root
directory if path is not specified. If -l is speci

fied, file
sizes will be shown too.

lsdev [-v]

Lists all of the devices from which it may be possi

ble to load
modules. If -v is specified, more details are

printed.

lsmod [-v]

Displays loaded modules. If -v is specified, more

details are
shown.

more file [file ...]

Display the files specified, with a pause at each

LINES displayed.

pnpscan [-v]

Scans for Plug-and-Play devices. This is not func

tional at present.

read [-t seconds] [-p prompt] [variable]

Reads a line of input from the terminal, storing it

in variable
if specified. A timeout can be specified with -t,

though it will
be canceled at the first key pressed. A prompt may

also be displayed through the -p flag.

reboot Immediately reboots the system.

set variable
set variable=value

Set loader's environment variables.

show [variable]

Displays the specified variable's value, or all

variables and
their values if variable is not specified.

unload Remove all modules from memory.

unset variable

Removes variable from the environment.

? Lists available commands.

BUILTIN ENVIRONMENT VARIABLES

The loader has actually two different kinds of `environment'

variables.
There are ANS Forth's environmental queries, and a separate

space of
environment variables used by builtins, which are not di

rectly available
to Forth words. It is the latter type that this section

covers.

Environment variables can be set and unset through the set

and unset
builtins, and can have their values interactively examined

through the
use of the show builtin. Their values can also be accessed

as described
in BUILTIN PARSER.

Notice that these environment variables are not inherited by

any shell
after the system has been booted.

A few variables are set automatically by loader. Others can

affect the
behavior of either loader or the kernel at boot. Some op

tions may
require a value, while others define behavior just by being

set. Both
types of builtin variables are described below.

acpi_load

Unset this to disable automatic loading of the

ACPI module.
See also hint.acpi.0.disabled in device.hints(5).

autoboot_delay

Number of seconds autoboot will wait before boot

ing. If this
variable is not defined, autoboot will default to

10 seconds.

If set to ``NO'', no autoboot will be automatical

ly attempted
after processing /boot/loader.rc, though explicit

autoboot's
will be processed normally, defaulting to 10 sec

onds delay.

If set to ``0'', no delay will be inserted, but

user still will
be able to interrupt autoboot process and escape

into the
interactive mode by pressing some key on the con

sole while kernel and modules are being loaded.

If set to ``-1'', no delay will be inserted and

loader will
engage interactive mode only if autoboot has

failed for some
reason.

boot_askname

Instructs the kernel to prompt the user for the

name of the
root device when the kernel is booted.

boot_cdrom

Instructs the kernel to try to mount the root file

system from
CD-ROM.

boot_ddb Instructs the kernel to start in the DDB debugger,

rather than

proceeding to initialize when booted.

boot_dfltroot

Instructs the kernel to mount the statically com

piled-in root
file system.

boot_gdb Selects gdb-remote mode for the kernel debugger by

default.

boot_multicons

Enables multiple console support in the kernel

early on boot.
In a running system, console configuration can be

manipulated
by the conscontrol(8) utility.

boot_mute

All console output is suppressed when console is

muted. In a
running system, the state of console muting can be

manipulated
by the conscontrol(8) utility.

boot_pause

During the device probe, pause after each line is

printed.

boot_serial

Force the use of a serial console even when an in

ternal console
is present.

boot_single

Prevents the kernel from initiating a multi-user

startup;
instead, a single-user mode will be entered when

the kernel has
finished device probing.

boot_verbose

Setting this variable causes extra debugging in

formation to be
printed by the kernel during the boot phase.

bootfile List of semicolon-separated search path for

bootable kernels.

The default is ``kernel''.

comconsole_speed

Defines the speed of the serial console (i386 and

amd64 only).
If the previous boot stage indicated that a serial

console is
in use then this variable is initialized to the

current speed
of the console serial port. Otherwise it is set

to 9600 unless
this was overridden using the

BOOT_COMCONSOLE_SPEED variable
when loader was compiled. Changes to the

comconsole_speed
variable take effect immediately.

console Defines the current console or consoles. Multiple

consoles may

be specified. In that case, the first listed con

sole will
become the default console for userland output

(e.g. from
init(8)).

currdev Selects the default device. Syntax for devices is

odd.

init_path

Sets the list of binaries which the kernel will

try to run as
the initial process. The first matching binary is

used. The
default list is
``/sbin/init:/sbin/oinit:/sbin/init.bak:/res

cue/init:/stand/sysinstall''.

interpret

Has the value ``OK'' if the Forth's current state

is interpreting.

LINES Define the number of lines on the screen, to be

used by the

pager.

module_path

Sets the list of directories which will be

searched for modules
named in a load command or implicitly required by

a dependency.
The default value for this variable is
``/boot/kernel;/boot/modules''.

num_ide_disks

Sets the number of IDE disks as a workaround for

some problems
in finding the root disk at boot. This has been

deprecated in
favor of root_disk_unit.

prompt Value of loader's prompt. Defaults to ``${inter

pret}''. If

variable prompt is unset, the default prompt is

`>'.

root_disk_unit

If the code which detects the disk unit number for

the root
disk is confused, e.g. by a mix of SCSI and IDE

disks, or IDE
disks with gaps in the sequence (e.g. no primary

slave), the
unit number can be forced by setting this vari

able.

rootdev By default the value of currdev is used to set the

root file

system when the kernel is booted. This can be

overridden by
setting rootdev explicitly.

Other variables are used to override kernel tunable parame

ters. The following tunables are available:

hw.physmem Limit the amount of physical memory the system

will use.

By default the size is in bytes, but the k, K,

m, M, g and
G suffixes are also accepted and indicate

kilobytes,
megabytes and gigabytes respectively. An in

valid suffix
will result in the variable being ignored by

the kernel.

hw.pci.host_start_mem, hw.acpi.host_start_mem

When not otherwise constrained, this limits

the memory
start address. The default is 0x80000000 and

should be set
to at least size of the memory and not con

flict with other
resources. Typically, only systems without

PCI bridges
need to set this variable since PCI bridges

typically constrain the memory starting address (and the

variable is
only used when bridges do not constrain this

address).

hw.pci.enable_io_modes

Enable PCI resources which are left off by

some BIOSes or
are not enabled correctly by the device driv

er. Tunable
value set to ON (1) by default, but this may

cause problems
with some peripherals.

kern.maxusers

Set the size of a number of statically allo

cated system
tables; see tuning(7) for a description of how

to select an
appropriate value for this tunable. When set,

this tunable
replaces the value declared in the kernel com

pile-time configuration file.

kern.ipc.nmbclusters

Set the number of mbuf clusters to be allocat

ed. The value
cannot be set below the default determined

when the kernel
was compiled. Modifies NMBCLUSTERS.

kern.ipc.nsfbufs

Set the number of sendfile(2) buffers to be

allocated.
Overrides NSFBUFS.

kern.maxswzone

Limits the amount of KVM to be used to hold

swap meta
information, which directly governs the maxi

mum amount of
swap the system can support. This value is

specified in
bytes of KVA space and defaults to around

70MBytes. Care
should be taken to not reduce this value such

that the
actual amount of configured swap exceeds 1/2

the kernelsupported swap. The default 70MB allows the

kernel to support a maximum of (approximately) 14GB of con

figured swap.
Only mess around with this parameter if you

need to greatly
extend the KVM reservation for other resources

such as the
buffer cache or NMBCLUSTERS. Modifies

VM_SWZONE_SIZE_MAX.

kern.maxbcache

Limits the amount of KVM reserved for use by

the buffer
cache, specified in bytes. The default maxi

mum is 200MB.
This parameter is used to prevent the buffer

cache from
eating too much KVM in large-memory machine

configurations.
Only mess around with this parameter if you

need to greatly
extend the KVM reservation for other resources

such as the
swap zone or NMBCLUSTERS. Note that the NBUF

parameter
will override this limit. Modifies

VM_BCACHE_SIZE_MAX.

machdep.disable_mtrrs

Disable the use of i686 MTRRs (x86 only).

net.inet.tcp.tcbhashsize

Overrides the compile-time set value of TCB

HASHSIZE or the
preset default of 512. Must be a power of 2.

vm.kmem_size Sets the size of kernel memory (bytes). This

overrides the

value determined when the kernel was compiled.

Modifies
VM_KMEM_SIZE.

BUILTIN PARSER

When a builtin command is executed, the rest of the line is

taken by it
as arguments, and it is processed by a special parser which

is not used
for regular Forth commands.

This special parser applies the following rules to the

parsed text:

1. All backslash characters are preprocessed.
, and are processed as in C.

+o ,,

+o is converted to a space.

+o is converted to ASCII 11.

+o is just skipped. Useful for things like `` xfxf''.

+o xN and xNN are replaced by the hex N or NN.

+o is replaced by the octal NNN ASCII character.

+o
from receiving special treatment in Step 2, de

scribed below.

+o will be replaced with a single .

+o In any other occurrence, backslash will just be re

moved.

2. Every string between non-escaped quotes or double

quotes will be
treated as a single word for the purposes of the re

maining steps.

3. Replace any $VARIABLE or ${VARIABLE} with the value of

the environ
ment variable VARIABLE.

4. Space-delimited arguments are passed to the called

builtin command.
Spaces can also be escaped through the use of .

An exception to this parsing rule exists, and is described

in BUILTINS
AND FORTH.

BUILTINS AND FORTH
All builtin words are state-smart, immediate words. If in

terpreted, they
behave exactly as described previously. If they are com

piled, though,
they extract their arguments from the stack instead of the

command line.

If compiled, the builtin words expect to find, at execution

time, the
following parameters on the stack:
addrN lenN ... addr2 len2 addr1 len1 N

where 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.

If no arguments are passed, a 0 must be passed, even if the

builtin
accepts no arguments.

While this behavior has benefits, it has its trade-offs. If

the execution token of a builtin is acquired (through ' or [']), and

then passed
to catch or execute, the builtin behavior will depend on the

system state
at the time catch or execute is processed! This is particu

larly annoying
for programs that want or need to handle exceptions. In

this case, the
use of a proxy is recommended. For example:
: (boot) boot;

FICL

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.

In loader, each line read interactively is then fed to FICL,

which may
call loader back to execute the builtin words. The builtin

include will
also feed FICL, one line at a time.

The words available to FICL can be classified into four

groups. The ANS
Forth standard words, extra FICL words, extra FreeBSD words,

and the
builtin commands; the latter were already described. The

ANS Forth standard words are listed in the STANDARDS section. The words

falling in the
two other groups are described in the following subsections.

FICL EXTRA WORDS

.env

.ver

-roll

2constant

>name

body>

compare This is the STRING word set's compare.

compile-only

endif

forget-wid

parse-word

sliteral This is the STRING word set's sliteral.

wid-set-super

w@

w!

x.

empty

cell

-rot

FREEBSD EXTRA WORDS

$ (--) Evaluates the remainder of the input buffer, after

having
printed it first.

% (--) Evaluates the remainder of the input buffer under

a catch
exception guard.

.# Works like . but without outputting a trailing

space.

fclose (fd --)
Closes a file.

fkey (fd -- char)
Reads a single character from a file.

fload (fd --)
Processes a file fd.

fopen (addr len mode -- fd)
Opens a file. Returns a file descriptor, or -1 in

case of
failure. The mode parameter selects whether the

file is to be
opened for read access, write access, or both.

The constants
O_RDONLY, O_WRONLY, and O_RDWR are defined in
/boot/support.4th, indicating read only, write on

ly, and readwrite access, respectively.

fread (fd addr len -- len')
Tries to read len bytes from file fd into buffer

addr. Returns
the actual number of bytes read, or -1 in case of

error or end
of file.

heap? (-- cells)
Return the space remaining in the dictionary heap,

in cells.
This is not related to the heap used by dynamic

memory allocation words.

inb (port -- char)
Reads a byte from a port.

key (-- char)
Reads a single character from the console.

key? (-- flag)
Returns true if there is a character available to

be read from
the console.

ms (u --)
Waits u microseconds.

outb (port char --)
Writes a byte to a port.

seconds (-- u)
Returns the number of seconds since midnight.

tib> (-- addr len)
Returns the remainder of the input buffer as a

string on the
stack.

trace! (flag --)
Activates or deactivates tracing. Does not work

with catch.

FREEBSD DEFINED ENVIRONMENTAL QUERIES

arch-i386
TRUE if the architecture is IA32.

arch-alpha
TRUE if the architecture is AXP.

FreeBSD_version
FreeBSD version at compile time.

loader_version
loader version.

SYSTEM DOCUMENTATION

For the purposes of ANS Forth compliance, loader is an ANS

Forth System
with Environmental Restrictions, Providing .(, :noname, ?do,

parse, pick,
roll, refill, to, value, false, true, <>, 0<>, compile, ,

erase, nip,
tuck and marker 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 get, see, words, [if], [else] and [then] from the

Programming-Tools
extension word set, Providing the Search-Order extensions

word set.

HISTORY

The loader first appeared in FreeBSD 3.1.

AUTHORS

The loader was written by Michael Smith <msmith@FreeB

SD.org>.

FICL was written by John Sadler <john_sadler@alum.mit.edu>.

BUGS

The expect and accept words will read from the input buffer

instead of
the console. The latter will be fixed, but the former will

not.

BSD September 22, 2005

BSD