diff options
Diffstat (limited to 'usr/src/man/man5/loader.5')
| -rw-r--r-- | usr/src/man/man5/loader.5 | 909 |
1 files changed, 0 insertions, 909 deletions
diff --git a/usr/src/man/man5/loader.5 b/usr/src/man/man5/loader.5 deleted file mode 100644 index 4c8edf3d3f..0000000000 --- a/usr/src/man/man5/loader.5 +++ /dev/null @@ -1,909 +0,0 @@ -.\" Copyright (c) 1999 Daniel C. Sobral -.\" Copyright 2019 OmniOS Community Edition (OmniOSce) Association. -.\" 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. -.\" -.Dd January 25, 2022 -.Dt LOADER 5 -.Os -.Sh NAME -.Nm loader -.Nd kernel bootstrapping final stage -.Sh DESCRIPTION -The -.Nm -is the final stage of -.Nm illumos Ns 's -kernel bootstrapping process. -The actual name for the stage depends on the platform. -On IA32 (i386) architectures with BIOS firmware, it is a -.Pa BTX -client and named -.Nm loader . -It is linked statically to libstand and usually located in the directory -.Pa /boot . -.Pp -.Nm -supports booting from -.Cm ZFS , -.Cm UFS , -.Cm PCFS , -.Cm HSFS -and -.Cm NFS -file systems. -Additionally, -.Nm -can load files from the -.Cm TFTP -file service. -The NFS and TFTP based boot is enabled via -.Xr pxeboot 5 . -The -.Nm -also does support uncompressing gzip files while reading. -The uncompression will happen automatically if the compressed file is stored -without .gz suffix or if the file is accessed by leaving out the .gz suffix from -the name. -If the file is referred by full name, including .gz suffix, then the file -content is read as is and the uncompression is not performed. -.Pp -.Nm -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-friendliness. -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 Do Li ttya Dc - Dq Li ttyd -if the previous boot stage used that. -If multiple consoles are selected, they will be listed separated by commas. -Then, devices are probed, -.Va currdev -and -.Va loaddev -are set, and -.Va screen-#cols , -.Va screen-#rows , -and -.Va ISADIR -are set. -Next, -.Tn FICL -is initialized, the builtin words are added to its vocabulary. -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. -These files are processed through the -.Ic include -command, which reads 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 Li 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. -Please note that historically even when -.Va autoboot_delay -is set to -.Dq Li 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 -.Va autoboot_delay -to -.Dq Li -1 , -in this case -.Nm -will engage interactive mode only if -.Ic autoboot -has failed. -.Ss Builtin Commands -In -.Nm , -builtin commands take parameters from the command line. -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 -.It Ic autoboot Op Ar seconds Op Ar 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. -.Pp -.It Ic bcachestat -Displays statistics about disk cache usage. -For debugging 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 -.Em WARNING : -The behavior of this builtin is changed if -.Xr loader.4th 5 -is loaded. -.Pp -.It Ic chain Ar device -Chain load another boot loader from the specified device. -Device can be either disk name or partition. -.Pp -.It Ic echo Xo -.Op Fl n -.Op Aq message -.Xc -Displays 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, 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 include -command 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 or 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. -.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. -In addition to disks and partitions, ZFS pools are also listed. -If -.Fl v -is specified, more details are printed. -For ZFS pools the output resembles -.Nm zpool Cm status -output. -.Pp -.It Ic lsmod Op Fl v -Displays loaded modules. -If -.Fl v -is specified, more details are shown. -.Pp -.It Ic lszfs Ar filesystem -A ZFS extended command that can be used to explore the ZFS filesystem -hierarchy in a pool. -Lists the immediate children of the -.Ar filesystem . -The filesystem hierarchy is rooted at a filesystem with the same name -as the pool. -.Pp -.It Ic more Ar file Op Ar -Display the files specified, with a pause at each -.Va screen-#rows -displayed. -.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 \&? -Lists available commands. -.El -.Ss ZFS Features -.Nm -supports the following format for specifying ZFS filesystems which -can be used wherever -.Nm -refers to a device specification: -.Pp -.Ar zfs:pool/filesystem: -.Pp -where -.Pa pool/filesystem -is a ZFS filesystem name as described in -.Xr zfs 1M . -.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 latter type that this section covers. -.Pp -Environment variables can be set and unset through the -.Ic set -and -.Ic unset -builtins, and can have their values 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 these 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 the behavior of either -.Nm -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. -.Bl -tag -width bootfile -.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 Li NO , -no -.Ic autoboot -will be automatically attempted after processing -.Pa /boot/loader.rc , -though explicit -.Ic autoboot Ns 's -will be processed normally, defaulting to 10 seconds delay. -.Pp -If set to -.Dq Li 0 , -no delay will be inserted, but user still will be able to interrupt -.Ic autoboot -process and escape into the interactive mode by pressing some key -on the console while kernel and -modules are being loaded. -.Pp -If set to -.Dq Li -1 , -no delay will be inserted and -.Nm -will engage interactive mode only if -.Ic autoboot -has failed for some reason. -.It Va boot_ask -Will set -.Xr kernel 1M -.Fl a -option. -.It Va boot_debug -Will set -.Xr kernel 1M -.Fl d -option. -.It Va boot_kmdb -Will set -.Xr kernel 1M -.Fl k -option. -.It Va boot_reconfigure -Will set -.Xr kernel 1M -.Fl r -option. -.It Va boot_single -Will set -.Xr kernel 1M -.Fl s -option. -.It Va boot_verbose -Will set -.Xr kernel 1M -.Fl v -option. -.It Va boot-args -Will set custom arguments for the kernel. -If set in -.Nm -configuration, the -.Nm -startup will parse the -.Va boot-args -value to set boot prefixed variables listed above, any unrecognized options -are added to kernel command line verbatim. -.It Va bootfile -The name of the kernel. -.It Va 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 -the -.Xr kernel 1M . -.It Va currdev -Selects the default device. -Syntax for devices is odd. -.It Va interpret -Has the value -.Dq Li ok -if the Forth's current state is interpreting. -.It Va screen-#rows -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 for modules -named in a load command or implicitly required by a dependency. -The default value for this variable is -.Dq Li /platform/i86pc/${ISADIR} -.It Va prompt -Value of -.Nm Ns 's -prompt. -Defaults to -.Dq Li "${interpret}" . -If variable -.Va prompt -is unset, the default prompt is -.Ql > . -.It Va os_console -If set, the value is used to set -.Xr kernel 1M -.Va console -property. -.El -.Pp -Other variables are used for loader or to set kernel properties or for -informational purposes. -.Ss 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. -.Pp -This special parser applies the following rules to the parsed text: -.Bl -enum -.It -All backslash characters are preprocessed. -.Bl -bullet -.It -\eb , \ef , \er , \en and \et are processed as in C. -.It -\es is converted to a space. -.It -\ev is converted to -.Tn ASCII -11. -.It -\ez is just skipped. -Useful for things like -.Dq \e0xf\ez\e0xf . -.It -\e0xN and \e0xNN 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 treatment in Step 2, described below. -.It -\e\e will be replaced with a single \e . -.It -In any other occurrence, 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 environment variable -.Va VARIABLE . -.It -Space-delimited arguments are passed to the called builtin command. -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 its trade-offs. -If the execution token of a builtin is acquired (through -.Ic ' -or -.Ic ['] ) , -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 particularly annoying for programs that want or need to -handle exceptions. -In this case, the use of a proxy is recommended. -For example: -.Dl : (boot) boot ; -.Ss 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 into four groups. -The -.Tn ANS -Forth standard words, extra -.Tn FICL -words, extra -.Fx -words, and the builtin commands; -the latter 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 -.It Ic .env -.It Ic .ver -.It Ic -roll -.It Ic 2constant -.It Ic >name -.It Ic body> -.It Ic compare -This is 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 Loader Extra Words -.Bl -tag -width XXXXXXXX -.It Ic \&$ Pq -- -Evaluates the remainder of the input buffer, after having printed it first. -.It Ic \&% Pq -- -Evaluates the remainder of the input buffer under a -.Ic catch -exception guard. -.It Ic .# -Works like -.Ic \&. -but without outputting a trailing space. -.It Ic fclose Pq Ar fd -- -Closes a file. -.It Ic fkey Pq Ar fd -- char -Reads a single character from a file. -.It Ic fload Pq Ar fd -- -Processes a file -.Em fd . -.It Ic fopen Pq Ar addr len mode Li -- Ar fd -Opens a file. -Returns a file descriptor, or \-1 in case of failure. -The -.Ar mode -parameter selects whether the file is to be opened for read access, write -access, or both. -The constants -.Dv O_RDONLY , O_WRONLY , -and -.Dv O_RDWR -are defined in -.Pa /boot/forth/support.4th , -indicating read only, write only, and read-write access, respectively. -.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 heap? Pq -- Ar cells -Return the space remaining in the dictionary heap, in cells. -This is not related to the heap used by dynamic memory allocation words. -.It Ic inb Pq Ar port -- char -Reads a byte from a port. -.It Ic isvirtualized? Pq -- Ar addr len flag | Ar flag -Returns -.Ic true -and string with virtualization engine name or -.Ic false . -.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 outb Pq Ar port char -- -Writes a byte to a port. -.It Ic seconds Pq -- Ar u -Returns the number of seconds since midnight. -.It Ic tib> Pq -- Ar addr len -Returns the remainder of the input buffer as a string on the stack. -.El -.Ss Loader Extra Framebuffer Words -.Bl -tag -width XXXXXXXX -.It Ic fb-bezier Pq Ar x1 y1 x2 y2 x3 y3 width -- -Draws a quadratic Bezier curve in the current foreground color using the -three provided points and specified line with. -.It Ic fb-drawrect Pq Ar x1 y1 x2 y2 fill -- -Draws a rectangle to the screen with the top left at -.Em (x1,y1) -and the bottom right at -.Em (x2,y2) -, using the current foreground color. -If -.Em fill -is -.Ic true -then the rectangle will be filled in. -.It Ic fb-line Pq Ar x1 y1 x2 y2 width -- -Draws a line from -.Em (x1,y1) -to -.Em (x2,y2) -in the current foreground color and with the specified width. -.It Ic fb-putimage Pq Ar flags x1 y1 x2 y2 addr len -- flag -Outputs an image to the screen. -Returns -.Ic true -if the image was able to be written and -.Ic false -otherwise. -Only truecolor PNG images are supported and the path to the file -must be provided through the -.Em addr -and -.Em len -arguments on the stack. -The image will be displayed in the rectangular screen region with the top left -at -.Em (x1,y1) -and the bottom right at -.Em (x2,y2) -. -.Pp -Either -.Em x2 -or -.Em y2 -can be set to "0" which causes it to be calculated to maintain the aspect -ratio of the image. -If both are "0" then the native resolution of the image will be used. -.Pp -If -.Em x1 -is "0", then the image will be placed as far over to the right of the -screen as possible. -Similarly, if -.Em y1 -is "0", then the image will be placed as far down the screen as possible. -.Pp -Flags is a bitfield; the following bits are defined: -.Bl -tag -width XXXXX -offset indent -.It 1 -Draw a single pixel border around the image in the current foreground color. -.It 2 -Do not scroll the image with the rest of the screen. -.It 128 -Output diagnostic information (for debugging). -.El -.It Ic fb-setpixel Pq Ar x y -- -Colors the pixel at -.Em (x,y) -with the current foreground color. -.It Ic term-drawrect Pq Ar x1 y1 x2 y2 -- -Draws a rectangle with rounded corners using terminal coordinates and the -current foreground color. -.El -.Ss Loader Defined Environmental Queries -.Bl -tag -width Ds -.It arch-i386 -.Ic TRUE -if the architecture is IA32. -.It loader_version -.Nm -version. -.El -.Ss 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 FILES -.Bl -tag -width /boot/defaults/loader.conf -compact -.It Pa /boot/defaults/loader.conf -.It Pa /boot/conf.d/* -.It Pa /boot/loader.conf -.It Pa /boot/loader.conf.local -.Nm -configuration files, as described in -.Xr loader.conf 4 . -.It Pa /boot/loader.help -Loaded by -.Ic help . -Contains the help messages. -.It Pa /boot/loader.rc -.Nm -bootstrapping script. -.It Pa /boot/forth/loader.4th -Extra builtin-like words. -.It Pa /boot/forth/support.4th -.Pa loader.conf -processing words. -.It Pa /boot/loader -.Nm -itself. -.El -.Sh EXAMPLES -Boot in single user mode: -.Pp -.Dl boot -s -.Pp -Load the kernel, a boot_archive, and then autoboot in five seconds. -Notice that a kernel must be loaded before any other -.Ic load -command is attempted. -.Bd -literal -offset indent -load /platform/i86pc/kernel/amd64/unix -load -t rootfs /platform/i86pc/amd64/boot_archive -autoboot 5 -.Ed -.Pp -Set the default device used for loading a kernel from a ZFS filesystem: -.Bd -literal -offset indent -set currdev=zfs:rpool/ROOT/knowngood: -.Ed -.Sh NOTES -Although setting the -.Va currdev -as shown in the example above is supported, it is advisable to use loader -beadm command or boot environment menu instead. -The reason is, the beadm or menu selection will also instruct loader to clean up -the currently set configuration and load configuration from the new boot -environment. -.Sh SEE ALSO -.Xr boot 1M , -.Xr btxld 1onbld , -.Xr loader.conf 4 -.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 [then] -.Bf Em -from the Programming-Tools extension word set, Providing the -Search-Order extensions word set. -.Ef |