1 .\" Copyright (c) 1999 Daniel C. Sobral
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" Note: The date here should be updated whenever a non-trivial
28 .\" change is made to the manual page.
34 .Nd kernel bootstrapping final stage
40 kernel bootstrapping process.
41 On IA32 (i386) architectures, it is a
44 It is linked statically to
46 and usually located in the directory
49 It provides a scripting language that can be used to
50 automate tasks, do pre-configuration or assist in recovery
52 This scripting language is roughly divided in
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 bigger component is an
60 Forth compatible Forth interpreter based on ficl, by
63 During initialization,
65 will probe for a console and set the
67 variable, or set it to serial console
69 if the previous boot stage used that.
70 Then, devices are probed,
79 is initialized, the builtin words are added to its vocabulary, and
81 will be processed if it exists.
82 No disk switching is possible while that file is being read.
94 is processed if available, and, failing that,
96 will be read for historical reasons.
97 These files are processed through the
99 command, which reads all of them into memory before processing them,
100 making disk changes possible.
104 has not been tried, and if
108 (not case sensitive), then an
111 If the system gets past this point,
115 will engage interactive mode.
118 builtin commands take its parameters from the command line.
120 the only way to call them from a script is by using
123 If an error condition occurs, an exception will be generated,
124 which can be intercepted using
126 Forth exception handling
128 If not intercepted, an error message will be displayed and
129 the interpreter's state will be reset, emptying the stack and restoring
132 The builtin commands available are:
134 .Bl -tag -width Ds -compact
135 .It Ic autoboot Op Ar seconds
136 Proceeds to bootstrap the system after a number of seconds, if not
137 interrupted by the user.
138 Displays a countdown prompt
139 warning the user the system is about to be booted,
140 unless interrupted by a key press.
141 The kernel will be loaded first if necessary.
142 Defaults to 10 seconds.
145 Displays statistics about disk cache usage.
149 .It Ic boot Ar kernelname Op Cm ...
150 .It Ic boot Fl flag Cm ...
151 Immediately proceeds to bootstrap the system, loading the kernel
153 Any flags or arguments are passed to the kernel, but they
154 must precede the kernel name, if a kernel name is provided.
157 The behavior of this builtin is changed if
165 Displays a text on the screen.
166 A new line will be printed unless
171 Displays memory usage statistics.
172 For debugging purposes only.
174 .It Ic help Op topic Op subtopic
175 Shows help messages read from
176 .Pa /boot/loader.help .
179 will list the topics available.
181 .It Ic include Ar file Op Ar
182 Process script files.
183 Each file is, at a turn, completely read into memory,
184 and then have each of its lines passed to the command line interpreter.
185 If any error is returned by the interpreter, the include
186 commands aborts immediately, without reading any other files, and
187 returns an error itself (see
194 Loads a kernel, kernel loadable module (kld), or a file of opaque
195 contents tagged as being of the type
197 Kernel and modules can be either in a.out or elf format.
198 Any arguments passed after the name of the file to be loaded
199 will be passed as arguments to that file.
200 Notice, though, that, at the present, this does not work for the kernel.
206 Displays a listing of files in the directory
208 or the root directory if
213 is specified, file sizes will be shown too.
216 Lists all of the devices from which it may be possible to load modules.
219 is specified, more details are printed.
222 Displays loaded modules.
225 is specified, more details are shown.
227 .It Ic more Ar file Op Ar
228 Display the files specified, with a pause at each
232 .It Ic pnpscan Op Fl v
233 Scans for Plug-and-Play devices.
234 This is not functional at the present.
241 Reads a line of input from the terminal, storing it in
244 A timeout can be specified with
246 though it will be canceled at the first key pressed.
247 A prompt may also be displayed through the
252 Immediately reboots the system.
254 .It Ic set Ar variable
255 .It Ic set Ar variable Ns = Ns Ar value
256 Set loader's environment variables.
258 .It Ic show Op Va variable
259 Displays the specified variable's value, or all variables and their
265 Remove all modules from memory.
267 .It Ic unset Va variable
270 from the environment.
277 .Ss BUILTIN ENVIRONMENT VARIABLES
280 has actually two different kinds of
283 There are ANS Forth's
284 .Em environmental queries ,
285 and a separate space of environment variables used by builtins, which
286 are not directly available to Forth words.
287 It is the later ones that this session covers.
289 Environment variables can be set and unset through the use of the
293 builtins, and have their value interactively examined through the
297 Their values can also be accessed as described in
300 Notice that these environment variables are not inherited by any shell
301 after the system has been booted.
303 A few variables are set automatically by
305 Others can affect either
307 or kernel's behavior at boot.
308 While some of these may require a value,
309 others define behavior just by being set.
310 These are described below.
311 .Bl -tag -width bootfile
312 .It Va autoboot_delay
315 will wait before booting.
316 If this variable is not defined,
318 will default to 10 seconds.
324 will be automatically attempted after processing
325 .Pa /boot/loader.rc ,
328 will be processed normally, defaulting to 10 seconds delay.
330 Instructs the kernel to prompt the user for the name of the root device
331 when the kernel is booted.
333 Instructs the kernel to start in the DDB debugger, rather than
334 proceeding to initialise when booted.
336 Selects gdb-remote mode for the kernel debugger by default.
338 Prevents the kernel from initiating a multi-user startup, single-user
339 mode will be entered when the kernel has finished device probes.
340 .It Va boot_userconfig
341 Requests that the kernel's interactive device configuration program
342 be run when the kernel is booted.
344 Setting this variable causes extra debugging information to be printed
345 by the kernel during the boot phase.
347 List of semicolon-separated search path for bootable kernels.
349 .Dq Li kernel;kernel.old .
351 Defines the current console.
353 Selects the default device.
354 Syntax for devices is odd.
356 Sets the list of binaries which the kernel will try to run as initial
359 .Dq Li /sbin/init:/sbin/oinit:/sbin/init.bak:/stand/sysinstall .
363 if the Forth's current state is interpreting.
365 Define the number of lines on the screen, to be used by the pager.
367 Sets the list of directories which will be searched in for modules
368 named in a load command or implicitly required by a dependency.
369 The default value for this variable is
370 .Dq Li /;/boot;/modules .
372 Sets the number of IDE disks as a work around for some problems in
373 finding the root disk at boot.
374 This has been deprecated in favor of
381 .Dq Li "${currdev}>" .
382 .It Va root_disk_unit
383 If the code which detects the disk unit number for the root disk is
384 confused, eg. by a mix of SCSI and IDE disks, or IDE disks with
385 gaps in the sequence (eg. no primary slave), the unit number can
386 be forced by setting this variable.
388 By default the value of
390 is used to set the root filesystem
391 when the kernel is booted.
392 This can be overridden by setting
396 A name of device where the kernel can save a crash dump in the case
398 This automatically sets
404 Other variables are used to override kernel tunable parameters.
405 The following tunables are available:
408 Limit the amount of physical memory the system will use.
409 By default the size is in bytes, but the
410 .Cm k , K , m , M , g
414 are also accepted and indicate kilobytes, megabytes and gigabytes
416 An invalid suffix will result in the variable being ignored by the
419 Set the size of a number of statically allocated system tables; see
421 for a description of how to select an appropriate value for this
423 When set, this tunable replaces the value declared in the kernel
424 compile-time configuration file.
425 .It Va kern.ipc.nmbclusters
426 Set the number of mbuf clusters to be allocated.
427 The value cannot be set below the default
428 determined when the kernel was compiled.
431 .It Va kern.vm.kmem.size
432 Sets the size of kernel memory (bytes).
433 This overrides completely the value
434 determined when the kernel was compiled.
437 .It Va kern.maxswzone
438 Limits the amount of KVM to be used to hold swap
439 meta information, which directly governs the
440 maximum amount of swap the system can support.
441 This value is specified in bytes of KVA space
442 and defaults to around 70MBytes.
444 to not reduce this value such that the actual
445 amount of configured swap exceeds 1/2 the
446 kernel-supported swap.
447 The default 70MB allows
448 the kernel to support a maximum of (approximately)
449 14GB of configured swap.
450 Only mess around with
451 this parameter if you need to greatly extend the
452 KVM reservation for other resources such as the
456 .Va VM_SWZONE_SIZE_MAX .
457 .It Va kern.maxbcache
458 Limits the amount of KVM reserved for use by the
459 buffer cache, specified in bytes.
460 The default maximum is 200MB.
461 This parameter is used to
462 prevent the buffer cache from eating too much
463 KVM in large-memory machine configurations.
464 Only mess around with this parameter if you need to
465 greatly extend the KVM reservation for other resources
466 such as the swap zone or
469 the NBUF parameter will override this limit.
471 .Va VM_BCACHE_SIZE_MAX .
472 .It Va machdep.pccard.pcic_irq
473 Overrides the IRQ normally assigned to a PCCARD controller.
474 Typically the first available interrupt will be allocated,
475 which may conflict with other hardware.
476 If this value is set to 0,
477 an interrupt will not be assigned
478 and the controller will operate in polled mode only.
479 .It Va net.inet.tcp.tcbhashsize
480 Overrides the compile-time set value of
482 or the preset default of 512.
483 Must be a power of 2.
486 When a builtin command is executed, the rest of the line is taken
487 by it as arguments, and it is processed by a special parser which
488 is not used for regular Forth commands.
490 This special parser applies the following rules to the parsed text:
494 All backslash characters are preprocessed.
497 \eb , \ef , \er , \en and \et are processed as in C.
499 \es is converted to a space.
506 Useful for things like
509 \e0xN and \e0xNN are replaced by the hex N or NN.
511 \eNNN is replaced by the octal NNN
515 \e" , \e' and \e$ will escape these characters, preventing them from
516 receiving special semantics on the step 2 described below.
518 \e\e will be replaced with a single \e .
520 In any other occurrence, backslash will just be removed.
523 Every string between non-escaped quotes or double-quotes will be treated
524 as a single word for the purposes of the remaining steps.
530 with the value of the environment variable
533 Passes multiple space-delimited arguments to the builtin command called.
534 Spaces can also be escaped through the use of \e\e .
537 An exception to this parsing rule exists, and is described in
538 .Sx BUILTINS AND FORTH .
539 .Ss BUILTINS AND FORTH
540 All builtin words are state-smart, immediate words.
541 If interpreted, they behave exactly as described previously.
542 If they are compiled, though,
543 they extract their arguments from the stack instead of the command line.
545 If compiled, the builtin words expect to find, at execution time, the
546 following parameters on the stack:
547 .D1 Ar addrN lenN ... addr2 len2 addr1 len1 N
550 are strings which will compose the command line that will be parsed
551 into the builtin's arguments.
552 Internally, these strings are concatenated in from 1 to N,
553 with a space put between each one.
555 If no arguments are passed, a 0
557 be passed, even if the builtin accepts no arguments.
559 While this behavior has benefits, it has its trade-offs.
560 If the execution token of a builtin is acquired (through
568 the builtin behavior will depend on the system state
576 \&! This is particular annoying for programs that want or need to
578 In this case, it is recommended to use a proxy.
583 is a Forth interpreter written in C, in the form of a forth
584 virtual machine library that can be called by C functions and vice
589 each line read interactively is then fed to
593 back to execute the builtin words.
600 The words available to
602 can be classified in four groups.
605 Forth standard words, extra
609 words, and the builtin commands.
610 The later were already described.
613 Forth standard words are listed in the
616 The words falling in the two other groups are described in the
617 following subsections.
619 .Bl -tag -width wid-set-super
627 This is the STRING word set's
634 This is the STRING word set's
644 .Ss FREEBSD EXTRA WORDS
645 .Bl -tag -width XXXXXXXX
647 Evaluates the remainder of the input buffer, after having printed it first.
649 Evaluates the remainder of the input buffer under a
655 but without outputting a trailing space.
656 .It Ic fclose Pq Ar fd --
658 .It Ic fkey Pq Ar fd -- char
659 Reads a single character from a file.
660 .It Ic fload Pq Ar fd --
663 .It Ic fopen Pq Ar addr len mode Li -- Ar fd
665 Returns a file descriptor, or \-1 in case of failure.
668 parameter selects whether the file is to be opened for read access, write
671 .Dv O_RDONLY , O_WRONLY ,
675 .Pa /boot/support.4th ,
676 indicating read only, write only, and read-write access, respectively.
679 .Pq Ar fd addr len -- len'
687 Returns the actual number of bytes read, or -1 in case of error or end of
689 .It Ic heap? Pq -- Ar cells
690 Return the space remaining in the dictionary heap, in cells.
691 This is not related to the heap used by dynamic memory allocation words.
692 .It Ic inb Pq Ar port -- char
693 Reads a byte from a port.
694 .It Ic key Pq -- Ar char
695 Reads a single character from the console.
696 .It Ic key? Pq -- Ar flag
699 if there is a character available to be read from the console.
704 .It Ic outb Pq Ar port char --
705 Writes a byte to a port.
706 .It Ic seconds Pq -- Ar u
707 Returns the number of seconds since midnight.
708 .It Ic tib> Pq -- Ar addr len
709 Returns the remainder of the input buffer as a string on the stack.
710 .It Ic trace! Pq Ar flag --
711 Activates or deactivates tracing.
715 .Ss FREEBSD DEFINED ENVIRONMENTAL QUERIES
719 if the architecture is IA32.
722 if the architecture is AXP.
725 version at compile time.
730 .Ss SYSTEM DOCUMENTATION
732 .Bl -tag -width /boot/defaults/loader.conf -compact
736 .It Pa /boot/boot.4th
740 .It Pa /boot/boot.conf
742 bootstrapping script.
744 .It Pa /boot/defaults/loader.conf
745 .It Pa /boot/loader.conf
746 .It Pa /boot/loader.conf.local
748 configuration files, as described in
750 .It Pa /boot/loader.rc
752 bootstrapping script.
753 .It Pa /boot/loader.help
756 Contains the help messages.
759 Boot in single user mode:
763 Loads kernel's user configuration file.
764 Notice that a kernel must be loaded before any other
766 command is attempted.
767 .Bd -literal -offset indent
769 load -t userconfig_script /boot/kernel.conf
772 Loads the kernel, a splash screen, and then autoboots in five seconds.
773 .Bd -literal -offset indent
776 load -t splash_image_data /boot/chuckrulez.bmp
780 Sets the disk unit of the root device to 2, and then boots.
781 This would be needed in the case of a two IDE disks system,
782 with the second IDE hardwired to wd2 instead of wd1.
783 .Bd -literal -offset indent
789 .Bl -tag -width /usr/share/examples/bootforth/X
790 .It Pa /boot/loader.4th
791 Extra builtin-like words.
792 .It Pa /boot/support.4th
795 .It Pa /usr/share/examples/bootforth/
799 The following values are thrown by
801 .Bl -tag -width XXXXX -offset indent
803 Any type of error in the processing of a builtin.
814 Out of interpreting text.
816 Need more text to succeed -- will finish on next run.
830 For the purposes of ANS Forth compliance, loader is an
832 ANS Forth System with Environmental Restrictions, Providing
838 parse, pick, roll, refill, to, value, \e, false, true,
841 compile\&, , erase, nip, tuck
846 from the Core Extensions word set, Providing the Exception Extensions
847 word set, Providing the Locals Extensions word set, Providing the
848 Memory-Allocation Extensions word set, Providing
852 bye, forget, see, words,
859 from the Programming-Tools extension word set, Providing the
860 Search-Order extensions word set.
870 .An Michael Smith Aq msmith@FreeBSD.org .
874 .An John Sadler Aq john_sadler@alum.mit.edu .
880 words will read from the input buffer instead of the console.
881 The latter will be fixed, but the former will not.
projects / FreeBSD / FreeBSD.git / blob