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 .Dd September 29, 2021
32 .Nd kernel bootstrapping final stage
38 kernel bootstrapping process.
39 On IA32 (i386) architectures, it is a
42 It is linked statically to
44 and usually located in the directory
47 It provides a scripting language that can be used to
48 automate tasks, do pre-configuration or assist in recovery
50 This scripting language is roughly divided in
52 The smaller one is a set of commands
53 designed for direct use by the casual user, called "builtin
54 commands" for historical reasons.
55 The main drive behind these commands is user-friendliness.
56 The bigger component is an
58 Forth compatible Forth interpreter based on FICL, by
61 During initialization,
63 will probe for a console and set the
65 variable, or set it to serial console
67 if the previous boot stage used that.
68 If multiple consoles are selected, they will be listed separated by spaces.
69 Then, devices are probed,
78 is initialized, the builtin words are added to its vocabulary, and
80 is processed if it exists.
81 No disk switching is possible while that file is being read.
93 is processed if available.
94 These files are processed through the
96 command, which reads all of them into memory before processing them,
97 making disk changes possible.
101 has not been tried, and if
105 (not case sensitive), then an
108 If the system gets past this point,
112 will engage interactive mode.
113 Please note that historically even when
117 user will be able to interrupt autoboot process by pressing some key
118 on the console while kernel and modules are being loaded.
120 cases such behaviour may be undesirable, to prevent it set
126 will engage interactive mode only if
132 builtin commands take parameters from the command line.
134 the only way to call them from a script is by using
137 If an error condition occurs, an exception will be generated,
138 which can be intercepted using
140 Forth exception handling
142 If not intercepted, an error message will be displayed and
143 the interpreter's state will be reset, emptying the stack and restoring
145 The commands are described in the
149 .Ss BUILTIN ENVIRONMENT VARIABLES
150 The environment variables common to all interpreters are described in the
152 .Dq BUILTIN ENVIRONMENT VARIABLES
155 When a builtin command is executed, the rest of the line is taken
156 by it as arguments, and it is processed by a special parser which
157 is not used for regular Forth commands.
159 This special parser applies the following rules to the parsed text:
162 All backslash characters are preprocessed.
165 \eb , \ef , \er , \en and \et are processed as in C.
167 \es is converted to a space.
174 Useful for things like
177 \e0xN and \e0xNN are replaced by the hex N or NN.
179 \eNNN is replaced by the octal NNN
183 \e" , \e' and \e$ will escape these characters, preventing them from
184 receiving special treatment in Step 2, described below.
186 \e\e will be replaced with a single \e .
188 In any other occurrence, backslash will just be removed.
191 Every string between non-escaped quotes or double-quotes will be treated
192 as a single word for the purposes of the remaining steps.
198 with the value of the environment variable
201 Space-delimited arguments are passed to the called builtin command.
202 Spaces can also be escaped through the use of \e\e .
205 An exception to this parsing rule exists, and is described in
206 .Sx BUILTINS AND FORTH .
207 .Ss BUILTINS AND FORTH
208 All builtin words are state-smart, immediate words.
209 If interpreted, they behave exactly as described previously.
210 If they are compiled, though,
211 they extract their arguments from the stack instead of the command line.
213 If compiled, the builtin words expect to find, at execution time, the
214 following parameters on the stack:
215 .D1 Ar addrN lenN ... addr2 len2 addr1 len1 N
218 are strings which will compose the command line that will be parsed
219 into the builtin's arguments.
220 Internally, these strings are concatenated in from 1 to N,
221 with a space put between each one.
223 If no arguments are passed, a 0
225 be passed, even if the builtin accepts no arguments.
227 While this behavior has benefits, it has its trade-offs.
228 If the execution token of a builtin is acquired (through
236 the builtin behavior will depend on the system state
244 This is particularly annoying for programs that want or need to
246 In this case, the use of a proxy is recommended.
251 is a Forth interpreter written in C, in the form of a forth
252 virtual machine library that can be called by C functions and vice
257 each line read interactively is then fed to
261 back to execute the builtin words.
268 The words available to
270 can be classified into four groups.
273 Forth standard words, extra
277 words, and the builtin commands;
278 the latter were already described.
281 Forth standard words are listed in the
284 The words falling in the two other groups are described in the
285 following subsections.
287 .Bl -tag -width wid-set-super
295 This is the STRING word set's
302 This is the STRING word set's
312 .Ss FREEBSD EXTRA WORDS
313 .Bl -tag -width XXXXXXXX
315 Evaluates the remainder of the input buffer, after having printed it first.
317 Evaluates the remainder of the input buffer under a
323 but without outputting a trailing space.
324 .It Ic fclose Pq Ar fd --
326 .It Ic fkey Pq Ar fd -- char
327 Reads a single character from a file.
328 .It Ic fload Pq Ar fd --
331 .It Ic fopen Pq Ar addr len mode Li -- Ar fd
333 Returns a file descriptor, or \-1 in case of failure.
336 parameter selects whether the file is to be opened for read access, write
339 .Dv O_RDONLY , O_WRONLY ,
343 .Pa /boot/support.4th ,
344 indicating read only, write only, and read-write access, respectively.
347 .Pq Ar fd addr len -- len'
355 Returns the actual number of bytes read, or -1 in case of error or end of
357 .It Ic heap? Pq -- Ar cells
358 Return the space remaining in the dictionary heap, in cells.
359 This is not related to the heap used by dynamic memory allocation words.
360 .It Ic inb Pq Ar port -- char
361 Reads a byte from a port.
362 .It Ic key Pq -- Ar char
363 Reads a single character from the console.
364 .It Ic key? Pq -- Ar flag
367 if there is a character available to be read from the console.
372 .It Ic outb Pq Ar port char --
373 Writes a byte to a port.
374 .It Ic seconds Pq -- Ar u
375 Returns the number of seconds since midnight.
376 .It Ic tib> Pq -- Ar addr len
377 Returns the remainder of the input buffer as a string on the stack.
378 .It Ic trace! Pq Ar flag --
379 Activates or deactivates tracing.
383 .Ss FREEBSD DEFINED ENVIRONMENTAL QUERIES
387 if the architecture is IA32.
390 version at compile time.
398 command line provides several ways of compromising system security,
399 including, but not limited to:
403 Booting from removable storage, by setting the
409 Executing binary of choice, by setting the
415 Overriding ACPI DSDT to inject arbitrary code into the ACPI subsystem
418 One can prevent unauthorized access
421 command line by setting the
429 In order for this to be effective, one should also configure the firmware
430 (BIOS or UEFI) to prevent booting from unauthorized devices.
432 Memory disk (MD) can be used when the
436 The size of the memory disk is determined by
438 If MD available, a file system can be embedded into the
441 .Pa /sys/tools/embed_mfs.sh .
442 Then, MD will be probed and be set to
444 during initialization.
446 Currently, MD is only supported in
449 .Bl -tag -width /usr/share/examples/bootforth/ -compact
453 .It Pa /boot/boot.4th
457 .It Pa /boot/defaults/loader.conf
458 .It Pa /boot/loader.4th
459 Extra builtin-like words.
460 .It Pa /boot/loader.conf
461 .It Pa /boot/loader.conf.local
463 configuration files, as described in
465 .It Pa /boot/loader.rc
467 bootstrapping script.
468 .It Pa /boot/loader.help
471 Contains the help messages.
472 .It Pa /boot/support.4th
475 .It Pa /usr/share/examples/bootforth/
479 Boot in single user mode:
483 Load the kernel, a splash screen, and then autoboot in five seconds.
484 Notice that a kernel must be loaded before any other
486 command is attempted.
487 .Bd -literal -offset indent
490 load -t splash_image_data /boot/chuckrulez.bmp
494 Set the disk unit of the root device to 2, and then boot.
495 This would be needed in a system with two IDE disks,
496 with the second IDE disk hardwired to ada2 instead of ada1.
497 .Bd -literal -offset indent
499 boot /boot/kernel/kernel
502 Set the default device used for loading a kernel from a ZFS filesystem:
503 .Bd -literal -offset indent
504 set currdev=zfs:tank/ROOT/knowngood:
508 The following values are thrown by
510 .Bl -tag -width XXXXX -offset indent
512 Any type of error in the processing of a builtin.
523 Out of interpreting text.
525 Need more text to succeed -- will finish on next run.
539 For the purposes of ANS Forth compliance, loader is an
541 ANS Forth System with Environmental Restrictions, Providing
547 parse, pick, roll, refill, to, value, \e, false, true,
550 compile\&, , erase, nip, tuck
555 from the Core Extensions word set, Providing the Exception Extensions
556 word set, Providing the Locals Extensions word set, Providing the
557 Memory-Allocation Extensions word set, Providing
561 bye, forget, see, words,
568 from the Programming-Tools extension word set, Providing the
569 Search-Order extensions word set.
581 .An Michael Smith Aq msmith@FreeBSD.org .
585 .An John Sadler Aq john_sadler@alum.mit.edu .