home | help
LOADER(8)		     System Manager's Manual		       LOADER(8)

NAME
     loader -- kernel bootstrapping final stage

DESCRIPTION
     The program called loader is the final stage of FreeBSD's kernel bootstrap-
     ping  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 automate tasks, do
     pre-configuration or assist in recovery procedures.   This  scripting  lan-
     guage  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-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 ("comconsole") if the  previous  boot
     stage  used  that.   If multiple consoles are selected, 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 in-
     terpreter	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 interrupt autoboot process by pressing
     some key on the console while kernel and modules are being loaded.  In some
     cases such behaviour may be undesirable, 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 using 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 restoring 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 debugging only.

     boot
     boot kernelname [...]
     boot -flag ...
	     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.

	     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 completely 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 in-
	     clude 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.

     load_geli [-n keyno] prov file
	     Loads  a  geli(8)	encryption  keyfile for the given provider name.
	     The key index can be specified via keyno or will default to zero.

     ls [-l] [path]
	     Displays a listing of files in the directory path, or the root  di-
	     rectory  if  path is not specified.  If -l is specified, file sizes
	     will be shown too.

     lsdev [-v]
	     Lists all of the devices from which it may be possible to load mod-
	     ules.  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  functional  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  envi-
     ronment  variables  used  by  builtins, which are not directly 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 af-
     ter the system has been booted.

     A few variables are set automatically by loader.  Others can affect the be-
     havior of either loader or the kernel at boot.  Some options may require  a
     value,  while  others  define  behavior  just  by being set.  Both types of
     builtin variables are described below.

     autoboot_delay
	       Number of seconds autoboot will wait  before  booting.	If  this
	       variable is not defined, autoboot will default to 10 seconds.

	       If set to "NO", no autoboot will be automatically attempted after
	       processing  /boot/loader.rc,  though  explicit autoboot's will be
	       processed normally, defaulting to 10 seconds delay.

	       If set to "0", no delay will be inserted, but user still will  be
	       able  to  interrupt autoboot process and escape into the interac-
	       tive mode by pressing some key on the console  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 compiled-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 internal console
	       is present.

     boot_single
	       Prevents the kernel from initiating  a  multi-user  startup;  in-
	       stead,  a  single-user  mode  will be entered when the kernel has
	       finished device probing.

     boot_verbose
	       Setting this variable causes extra debugging  information  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 ef-
	       fect immediately.

     console   Defines the current console or consoles.  Multiple  consoles  may
	       be specified.  In that case, the first listed console will become
	       the default console for userland output (e.g. from init(8)).

     currdev   Selects the default device.  Syntax for devices is odd.

     init_chroot
	       If  set	to  a valid directory in the root file system, it causes
	       init(8) to perform a chroot(2) operation on that directory,  mak-
	       ing it the new root directory.  That happens before entering sin-
	       gle-user  mode  or  multi-user  mode  (but  after  executing  the
	       init_script if enabled).

     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:
	       /rescue/init:/stand/sysinstall".

     init_script
	       If  set	to  a valid file name in the root file system, instructs
	       init(8) to run that script as the very first action, before doing
	       anything else.  Signal handling and exit code  interpretation  is
	       similar	to  running  the /etc/rc script.  In particular, single-
	       user operation is enforced if the script terminates with  a  non-
	       zero  exit  code,  or  if  a  SIGTERM is delivered to the init(8)
	       process (PID 1).

     init_shell
	       Defines the shell binary to be used  for  executing  the  various
	       shell scripts.  The default is "/bin/sh".  It is used for running
	       the   init_script  if  set,  as	well  as  for  the  /etc/rc  and
	       /etc/rc.shutdown scripts.  The value of the corresponding kenv(2)
	       variable is evaluated every time init(8) calls a shell script, so
	       it can be changed later on using the kenv(1) utility.  In partic-
	       ular, if a non-default shell is used for running an  init_script,
	       it  might  be  desirable  to  have that script reset the value of
	       init_shell back to the default, so that the /etc/rc script is ex-
	       ecuted with the standard shell /bin/sh.

     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 "${interpret}".  If  vari-
	       able 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 num-
	       ber can be forced by setting this variable.

     rootdev   By default the value of currdev is used to set the root file sys-
	       tem when the kernel is booted.  This can be overridden by setting
	       rootdev explicitly.

     Other variables are used to override kernel tunable parameters.   The  fol-
     lowing 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 invalid 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  conflict	with  other  re-
		   sources.  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 driver.  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 allocated system ta-
		   bles; see tuning(7) for a description of how to select an ap-
		   propriate value for this tunable.  When set, this tunable re-
		   places the value declared in the kernel compile-time configu-
		   ration file.

     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.

     kern.ipc.nsfbufs
		   Set the number of sendfile(2) buffers to be allocated.  Over-
		   rides NSFBUFS.  Not all architectures use such  buffers;  see
		   sendfile(2) for details.

     kern.maxswzone
		   Limits  the amount of KVM to be used to hold swap meta infor-
		   mation, which directly governs the maximum amount of swap the
		   system can support.	This value is specified in bytes of  KVA
		   space  and  defaults  to  32MBytes  on  i386 and amd64.  Care
		   should be taken to not reduce this value such that the actual
		   amount of configured swap exceeds  1/2  the	kernel-supported
		   swap.   The	default  of  32MB allows the kernel to support a
		   maximum of ~7GB of swap.  Only change this parameter  if  you
		   need  to  greatly  extend  the  KVM reservation for other re-
		   sources such as the	buffer	cache  or  kern.ipc.nmbclusters.
		   Modifies kernel option VM_SWZONE_SIZE_MAX.

     kern.maxbcache
		   Limits  the	amount	of  KVM  reserved  for use by the buffer
		   cache, specified in bytes.  The default maximum is  200MB  on
		   i386, and 400MB on amd64 and sparc64.  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 reserva-
		   tion   for	other	resources  such  as  the  swap	zone  or
		   kern.ipc.nmbclusters.  Note	that  the  NBUF  parameter  will
		   override this limit.  Modifies VM_BCACHE_SIZE_MAX.

     kern.msgbufsize
		   Sets  the  size  of	the  kernel message buffer.  The default
		   limit of 64KB is usually sufficient unless large  amounts  of
		   trace  data need to be collected between opportunities to ex-
		   amine the buffer or dump it to a file.  Overrides kernel  op-
		   tion MSGBUF_SIZE.

     machdep.disable_mtrrs
		   Disable the use of i686 MTRRs (x86 only).

     net.inet.tcp.tcbhashsize
		   Overrides  the  compile-time  set value of TCBHASHSIZE 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.

     vm.kmem_size_min

     vm.kmem_size_max
		   Sets the minimum and maximum (respectively) amount of  kernel
		   memory  that  will  be automatically allocated by the kernel.
		   These override the values determined when the kernel was com-
		   piled.  Modifies VM_KMEM_SIZE_MIN and VM_KMEM_SIZE_MAX.

   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.

	  *   \b , \f , \r , \n and \t are processed as in C.

	  *   \s is converted to a space.

	  *   \v is converted to ASCII 11.

	  *   \z is just skipped.  Useful for things like "\0xf\z\0xf".

	  *   \0xN and \0xNN are replaced by the hex N or NN.

	  *   \NNN is replaced by the octal NNN ASCII character.

	  *   \" , \' and \$ will escape these characters, preventing them  from
	      receiving special treatment in Step 2, described below.

	  *   \\ will be replaced with a single \ .

	  *   In any other occurrence, backslash will just be removed.

     2.   Every  string  between  non-escaped  quotes  or  double-quotes will be
	  treated as a single word for the purposes of the remaining steps.

     3.   Replace any $VARIABLE or ${VARIABLE} with the value of the environment
	  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 interpreted, they
     behave exactly as described previously.  If they are compiled, 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  fol-
     lowing 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 con-
     catenated 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 particularly annoying for pro-
     grams 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 stan-
     dard 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  excep-
	       tion 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 fail-
	       ure.  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 only, and read-write 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.

     FreeBSD_version
	     FreeBSD version at compile time.

     loader_version
	     loader version.

   SYSTEM DOCUMENTATION
FILES
     /boot/loader		 loader itself.
     /boot/boot.4th		 Additional FICL initialization.
     /boot/boot.conf		 loader bootstrapping script.  Deprecated.
     /boot/defaults/loader.conf
     /boot/loader.conf
     /boot/loader.conf.local	 loader  configuration	files,	as  described in
				 loader.conf(5).
     /boot/loader.rc		 loader bootstrapping script.
     /boot/loader.help		 Loaded by help.  Contains the help messages.

EXAMPLES
     Boot in single user mode:

	   boot -s

     Load the kernel, a splash screen, and then autoboot in five  seconds.   No-
     tice  that  a  kernel  must  be loaded before any other load command is at-
     tempted.

	   load kernel
	   load splash_bmp
	   load -t splash_image_data /boot/chuckrulez.bmp
	   autoboot 5

     Set the disk unit of the root device to 2, and then boot.	 This  would  be
     needed  in  a system with two IDE disks, with the second IDE disk hardwired
     to wd2 instead of wd1.

	   set root_disk_unit=2
	   boot /kernel

     See also:

     /boot/loader.4th		      Extra builtin-like words.

     /boot/support.4th		      loader.conf processing words.

     /usr/share/examples/bootforth/   Assorted examples.

ERRORS
     The following values are thrown by loader:

	   100	  Any type of error in the processing of a builtin.

	   -1	  Abort executed.

	   -2	  Abort" executed.

	   -56	  Quit executed.

	   -256   Out of interpreting text.

	   -257   Need more text to succeed -- will finish on next run.

	   -258   Bye executed.

	   -259   Unspecified error.

SEE ALSO
     libstand(3), loader.conf(5), tuning(7), boot(8), btxld(8)

STANDARDS
     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 .s, bye, forget, 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@FreeBSD.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.

FreeBSD 9.0			February 15, 2009		       LOADER(8)

home | help