From c35e50888f46640cc8524542df23da1b1a379dd2 Mon Sep 17 00:00:00 2001 From: dcs Date: Fri, 19 May 2000 08:44:48 +0000 Subject: [PATCH] This file got repo-copied to common/. --- sys/boot/i386/loader/loader.8 | 756 ---------------------------------- 1 file changed, 756 deletions(-) delete mode 100644 sys/boot/i386/loader/loader.8 diff --git a/sys/boot/i386/loader/loader.8 b/sys/boot/i386/loader/loader.8 deleted file mode 100644 index de82afa776b9..000000000000 --- a/sys/boot/i386/loader/loader.8 +++ /dev/null @@ -1,756 +0,0 @@ -.\" Copyright (c) 1999 Daniel C. Sobral -.\" 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. -.\" -.\" $FreeBSD$ -.\" -.\" Note: The date here should be updated whenever a non-trivial -.\" change is made to the manual page. -.Dd March 14, 1999 -.Dt LOADER 8 -.Os -.Sh NAME -.Nm loader -.Nd kernel bootstrapping final stage -.Sh DESCRIPTION -The program called -.Nm -is the final stage of FreeBSD's kernel bootstrapping process. -On IA32 (i386) architectures, it is a -.Pa BTX -client. It is linked statically to -.Xr libstand 3 -and usually located in the directory -.Pa /boot . -.Pp -It 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-friendlyness. 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 Dq comconsole -if the previous boot stage used that. Then, devices are probed, -.Va currdev -and -.Va loaddev -are set, and -.Va LINES -is set to 24 . Next, -.Tn FICL -is initialized, the builtin words are added to its vocabulary, and -.Pa /boot/boot.4th -will be processed if it exists. No disk switching is possible while -that file is being read. 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, and, failing that, -.Pa /boot/boot.conf -will be read for historical reasons. These files are processed -through the -.Ic include -command, which read 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 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. -.Sh BUILTIN COMMANDS -.Nm Loader Ns No 's -builtin commands take its parameters from the command line. Presently, -the only way to call them from a script is by using -.Pa evaluate -on a string. 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 -offset indent -.It Ic autoboot Op Ar seconds -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 depuration 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 -.It Ic echo Xo -.Op Fl n -.Op Aq message -.Xc -Displays a 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 is, at a turn, completely read into -memory, and then have each of its lines passed to the command line -interpreter. If any error is returned by the interpreter, the include -commands 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, kernel loadable module (kld), or a 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. Notice, though, that, at the present, this does -not work for the kernel. -.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. If -.Fl v -is specified, more details are printed. -.Pp -.It Ic lsmod Op Fl v -Displays loaded modules. If -.Fl v -is specified, more details are shown. -.Pp -.It Ic more Ar file Op Ar -Display the files specified, with a pause at each -.Va LINES -displayed. -.Pp -.It Ic pnpscan Op Fl v -Scans for Plug-and-Play devices. This is not functional at the present. -.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 \&? -Same as -.Dq help index . -.Pp -.El -.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 later ones that -this session covers. -.Pp -Environment variables can be set and unset through the use of the -.Ic set -and -.Ic unset -builtins, and have their value 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 this environment variables are not inherited by any shell -after the system has been booted. -.Pp -A few variables are set automatically by -.Nm loader . -Others can affect either -.Nm -or kernel's behavior at boot. While some of these may require a value, -others define behavior just by being set. These are described below. -.Bl -tag -width bootfile -offset indent -.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 NO , -no -.Ic autoboot -will be automatically attempted after processing -.Pa /boot/loader.rc , -though explict -.Ic autoboot Ns 's -will be processed normally, defaulting to 10 seconds delay. -.It Va boot_askname -Instructs the kernel to prompt the user for the name of the root device -when the kernel is booted. -.It Va boot_ddb -Instructs the kernel to start in the DDB debugger, rather than -proceeding to initialise when booted. -.It Va boot_gdb -Selects gdb-remote mode for the kernel debugger by default. -.It Va boot_single -Prevents the kernel from initiating a multi-user startup, single-user -mode will be entered when the kernel has finished device probes. -.It Va boot_userconfig -Requests that the kernel's interactive device configuration program -be run when the kernel is booted. -.It Va boot_verbose -Setting this variable causes extra debugging information to be printed -by the kernel during the boot phase. -.It Va bootfile -List of semicolon-separated search path for bootable kernels. The default -is -.Li Dq kernel;kernel.old . -.It Va console -Defines the current console. -.It Va currdev -Selects the default device. Syntax for devices is odd. -.It Va init_path -Sets the list of binaries which the kernel will try to run as initial -process. The default is -.Li Dq /sbin/init:/sbin/oinit:/sbin/init.bak:/stand/sysinstall . -.It Va interpret -Has the value -.Li Dq ok -if the Forth's current state is interpreting. -.It Va LINES -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 in for modules -named in a load command or implicitly required by a dependancy. The -default value for this variable is -.Li Dq /;/boot;/modules . -.It Va num_ide_disks -Sets the number of IDE disks as a work around for some problems in -finding the root disk at boot. This has been deprecated in favour of -.Va root_disk_unit . -.It Va prompt -Value of -.Nm Ns No 's -prompt. Defaults to -.Li Dq "${currdev}>" . -.It Va root_disk_unit -If the code which detects the disk unit number for the root disk is -confused, eg. by a mix of SCSI and IDE disks, or IDE disks with -gaps in the sequence (eg. no primary slave), the unit number can -be forced by setting this variable. -.It Va rootdev -By default the value of -.Va currdev -is used to set the root filesystem -when the kernel is booted. This can be overridden by setting -.Va rootdev -explicitly. -.El -.Pp -Other variables are used to override kernel tunnable parameters. -The following tunables are available: -.Bl -tag -width Va -offset indent -.It Va 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. Modifies -.Va NMBCLUSTERS . -.It Va kern.vm.kmem.size -Sets the size of kernel memory (bytes). This overrides -completely the value determined when the kernel was -compiled. Modifies -.Va VM_KMEM_SIZE . -.It Va machdep.pccard.pcic_irq -Overrides the IRQ normally assigned to a PCCARD controller. -Typically the first available interrupt will be allocated, -which may conflict with other hardware. If this value is -set to 0, an interrupt will not be assigned and the -controller will operate in polled mode only. -.It Va net.inet.tcp.tcbhashsize -Overrides the compile-time set value of -.Va TCBHASHSIZE -or the preset default of 512. Must be a power of 2. -.El -.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: -.Pp -.Bl -enum -.It -All backslash characters are preprocessed. -.Bl -bullet -.It -\eb , \ef , \er , \en and \et are processed as by C's -.Fn printf . -.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 semantics on the step 2 described below. -.It -\e\e will be replaced with a single \e . -.It -In any other occurance, 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 environemnt variable -.Va VARIABLE . -.It -Passes multiple space-delimited arguments to the builtin command called. -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 No ' -or -.Ic No ['] ) , -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 particular annoying for programs that want or need to -treat exceptions. In this case, it is recommended the use of a proxy. -For example: -.Dl : (boot) boot ; -.Sh 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 No , -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 in four groups. The -.Tn ANS -Forth standard words, extra -.Tn FICL -words, extra -.Os -words, and the builtin commands. The later 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 -offset indent -.It Ic .env -.It Ic .ver -.It Ic -roll -.It Ic 2constant -.It Ic >name -.It Ic body> -.It Ic compare -This 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 FREEBSD EXTRA WORDS -.Bl -tag -width XXXXXXXX -offset indent -.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 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 -- -Process file -.Em fd . -.It Ic fopen Pq Ar addr len -- fd -Open a file. Returns a file descriptor, or -1 in case of failure. -.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 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. -.It Ic trace! Pq Ar flag -- -Activates or deactivates tracing. Does not work with -.Ic catch . -.El -.Ss FREEBSD DEFINED ENVIRONMENTAL QUERIES -.Bl -tag -width Ds -offset indent -.It arch-i386 -.Ic TRUE -if the architecture is IA32. -.It arch-alpha -.Ic TRUE -if the architecture is AXP. -.It FreeBSD_version -.Fx -version at compile time. -.It loader_version -.Nm -version. -.El -.Ss SYSTEM DOCUMENTATION -.Sh FILES -.Bl -tag -width /dev/loader.helpX -compact -.It Pa /boot/loader -.Nm -itself. -.It Pa /boot/boot.4th -Additional -.Tn FICL -initialization. -.It Pa /boot/boot.conf -.Nm -bootstrapping script. Deprecated. -.It Pa /boot/loader.rc -.Nm -bootstrapping script. -.It Pa /boot/loader.help -Loaded by -.Ic help . -Contains the help messages. -.El -.Sh EXAMPLES -Boot in single user mode: -.Pp -.Dl boot -s -.Pp -Loads kernel's user configuration file. Notice that a kernel must be -loaded before any other -.Ic load -command is attempted. -.Pp -.Bd -literal -offset indent -compact -load kernel -load -t userconfig_script /boot/kernel.conf -.Ed -.Pp -Loads the kernel, a splash screen, and then autoboots in five seconds. -.Pp -.Bd -literal -offset indent -compact -load kernel -load splash_bmp -load -t splash_image_data /boot/chuckrulez.bmp -autoboot 5 -.Ed -.Pp -Sets the disk unit of the root device to 2, and then boots. This would -be needed in the case of a two IDE disks system, with the second IDE -hardwired to wd2 instead of wd1. -.Pp -.Bd -literal -offset indent -compact -set root_disk_unit=2 -boot /kernel -.Ed -.Pp -See also: -.Bl -tag -width /usr/share/examples/bootforth/X -.It Pa /boot/loader.4th -Extra builtin-like words. -.It Pa /boot/support.4th -.Pa loader.conf -processing words. -.It Pa /usr/share/examples/bootforth/ -Assorted examples. -.El -.Sh 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 SEE ALSO -.Xr libstand 3 , -.Xr loader.conf 5 , -.Xr boot 8 , -.Xr btxld 8 -.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 No [then] -.Bf Em -from the Programming-Tools extension word set, Providing the -Search-Order extensions word set. -.Ef -.Sh HISTORY -.Nm -first appeared in -.Fx 3.1 . -.Sh AUTHORS -.Bl -item -.It -.Nm -was written by -.An Michael Smith Aq msmith@freebsd.org . -.It -.Tn FICL -was written by -.An John Sadler Aq john_sadler@alum.mit.edu . -.El -.Sh BUGS -.Tn FICL -is case sensitive. Though this is not a standard violation, all Forth -words are lower cased, which would result in a standard violation. Do -not rely on this bug. -.Pp -The -.Ic expect -and -.Ic accept -words will read from the input buffer instead of the console. The latter -will be fixed, but the former will not. -