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