stand/man/loader.8

   1 .\" Copyright (c) 1999 Daniel C. Sobral
   2 .\" All rights reserved.
   3 .\" Copyright (c) 2021 Warner Losh <imp@FreeBSD.org>
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd September 29, 2021
  29 .Dt LOADER 8
  30 .Os
  31 .Sh NAME
  32 .Nm loader
  33 .Nd kernel bootstrapping final stage
  34 .Sh DESCRIPTION
  35 The program called
  36 .Nm
  37 is the final stage of
  38 .Fx Ns 's
  39 kernel bootstrapping process.
  40 It is responsible for bringing the kernel, kernel modules and other files into
  41 memory.
  42 It creates a set of
  43 .Xr sh 1
  44 like environment variables that are passed to the kernel.
  45 It executes boot scripts written in one of several interpreters.
  46 Together with the scripts, it controls the booting process and
  47 interaction with the user.
  48 .Pp
  49 It provides a scripting language that can be used to
  50 automate tasks, do pre-configuration or assist in recovery
  51 procedures.
  52 This scripting language is roughly divided in
  53 two main components.
  54 The smaller one is a set of commands
  55 designed for direct use by the casual user, called "builtin
  56 commands" for historical reasons.
  57 The main drive behind these commands is user-friendliness.
  58 The larger component is the scripting language built into
  59 the boot loader.
  60 .Fx
  61 provides three different interpreters: Forth, Lua and Simple.
  62 The Forth loader is based on an ANS Forth compatible
  63 Forth interpreter based on FICL, by
  64 .An John Sadler .
  65 The Lua loader is a full Lua interpreter from
  66 .Pa https://www.lua.org/ .
  67 The Simple loader only interprets a list of builtin commands
  68 without any control structure.
  69 .Pp
  70 During initialization,
  71 .Nm
  72 will probe for a console and set the
  73 .Va console
  74 variable, or set it to serial console
  75 .Pq Dq Li comconsole
  76 if the previous boot stage used that.
  77 If multiple consoles are selected, they will be listed separated by spaces.
  78 Then, devices are probed,
  79 .Va currdev
  80 and
  81 .Va loaddev
  82 are set, and
  83 .Va LINES
  84 is set to 24.
  85 Finally, an interpreter specific file will be executed.
  86 .Sh BUILTIN COMMANDS
  87 The commands common to all interpreters are described in the
  88 .Xr loader_simp 8
  89 .Dq BUILTIN COMMANDS
  90 section.
  91 .Ss BUILTIN ENVIRONMENT VARIABLES
  92 The environment variables common to all interpreters are described in the
  93 .Xr loader_simp 8
  94 .Dq BUILTIN ENVIRONMENT VARIABLES
  95 section.
  96 .Sh SEE ALSO
  97 .Xr libsa 3 ,
  98 .Xr loader.conf 5 ,
  99 .Xr tuning 7 ,
 100 .Xr boot 8 ,
 101 .Xr btxld 8 ,
 102 .Xr loader.efi 8 ,
 103 .Xr loader_4th 8 ,
 104 .Xr loader_lua 8 ,
 105 .Xr loader_simp 8
 106 .Sh HISTORY
 107 The
 108 .Nm
 109 first appeared in
 110 .Fx 3.1 .
 111 The
 112 .Nm
 113 scripting language changed to Lua by default in
 114 .Fx 12.0 .
 115 .Sh AUTHORS
 116 .An -nosplit
 117 The
 118 .Nm
 119 was written by
 120 .An Michael Smith Aq msmith@FreeBSD.org .
 121 .Pp
 122 FICL was written by
 123 .An John Sadler Aq john_sadler@alum.mit.edu .
 124 .Pp
 125 .An Warner Losh Aq imp@FreeBSD.org
 126 integrated Lua into the tree based on initial work done by Pedro Souza
 127 for the 2014 Google Summer of Code.