1 LOADER(5) Standards, Environments, and Macros LOADER(5)
2
3 NAME
4 loader - kernel bootstrapping final stage
5
6 DESCRIPTION
7 The loader is the final stage of illumos's kernel bootstrapping process.
8 The actual name for the stage depends on the platform. On IA32 (i386)
9 architectures with BIOS firmware, it is a BTX client and named zfsloader.
10 It is linked statically to libstand and usually located in the directory
11 /boot.
12
13 loader supports booting from ZFS, UFS, PCFS, HSFS and NFS file systems.
14 Additionally, loader can load files from the TFTP file service. The NFS
15 and TFTP based boot is enabled via pxeboot(5). The loader also does
16 support uncompressing gzip files while reading. The uncompression will
17 happen automatically if the compressed file is stored without .gz suffix
18 or if the file is accessed by leaving out the .gz suffix from the name.
19 If the file is referred by full name, including .gz suffix, then the file
20 content is read as is and the uncompression is not performed.
21
22 loader provides a scripting language that can be used to automate tasks,
23 do pre-configuration or assist in recovery procedures. This scripting
24 language is roughly divided in two main components. The smaller one is a
25 set of commands designed for direct use by the casual user, called
26 "builtin commands" for historical reasons. The main drive behind these
27 commands is user-friendliness. The bigger component is an ANS Forth
28 compatible Forth interpreter based on FICL, by John Sadler.
29
30 During initialization, loader will probe for a console and set the
31 console variable, or set it to serial console ("ttya" - "ttyd") if the
32 previous boot stage used that. If multiple consoles are selected, they
33 will be listed separated by commas. Then, devices are probed, currdev
34 and loaddev are set, and screen-#cols, screen-#rows, and ISADIR are set.
35 Next, FICL is initialized, the builtin words are added to its vocabulary.
36 The inner interpreter loader will use with FICL is then set to interpret,
37 which is FICL's default. After that, /boot/loader.rc is processed if
38 available. These files are processed through the include command, which
39 reads all of them into memory before processing them, making disk changes
40 possible.
41
42 At this point, if an autoboot has not been tried, and if autoboot_delay
43 is not set to "NO" (not case sensitive), then an autoboot will be tried.
44 If the system gets past this point, prompt will be set and loader will
45 engage interactive mode. Please note that historically even when
46 autoboot_delay is set to "0" user will be able to interrupt autoboot
47 process by pressing some key on the console while kernel and modules are
48 being loaded. In some cases such behaviour may be undesirable, to
49 prevent it set autoboot_delay to "-1", in this case loader will engage
50 interactive mode only if autoboot has failed.
51
52 Builtin Commands
53 In loader, builtin commands take parameters from the command line. If an
54 error condition occurs, an exception will be generated, which can be
55 intercepted using ANS Forth exception handling words. If not
56 intercepted, an error message will be displayed and the interpreter's
57 state will be reset, emptying the stack and restoring interpreting mode.
58
59 The builtin commands available are:
60
61 autoboot [seconds [prompt]]
62 Proceeds to bootstrap the system after a number of seconds, if
63 not interrupted by the user. Displays a countdown prompt warning
64 the user the system is about to be booted, unless interrupted by
65 a key press. The kernel will be loaded first if necessary.
66 Defaults to 10 seconds.
67
68 bcachestat
69 Displays statistics about disk cache usage. For debugging only.
70
71 boot
72 boot kernelname [...]
73 boot -flag ...
74 Immediately proceeds to bootstrap the system, loading the kernel
75 if necessary. Any flags or arguments are passed to the kernel,
76 but they must precede the kernel name, if a kernel name is
77 provided.
78
79 WARNING: The behavior of this builtin is changed if loader.4th(5)
80 is loaded.
81
82 chain device
83 Chain load another boot loader from the specified device. Device
84 can be either disk name or partition.
85
86 echo [-n] [<message>]
87 Displays text on the screen. A new line will be printed unless
88 -n is specified.
89
90 heap Displays memory usage statistics. For debugging purposes only.
91
92 help [topic [subtopic]]
93 Shows help messages read from /boot/loader.help. The special
94 topic index will list the topics available.
95
96 include file [file ...]
97 Process script files. Each file, in turn, is completely read
98 into memory, and then each of its lines is passed to the command
99 line interpreter. If any error is returned by the interpreter,
100 the include command aborts immediately, without reading any other
101 files, and returns an error itself (see ERRORS).
102
103 load [-t type] file ...
104 Loads a kernel or file of opaque contents tagged as being of the
105 type type. Kernel and modules can be either in a.out or ELF
106 format. Any arguments passed after the name of the file to be
107 loaded will be passed as arguments to that file.
108
109 ls [-l] [path]
110 Displays a listing of files in the directory path, or the root
111 directory if path is not specified. If -l is specified, file
112 sizes will be shown too.
113
114 lsdev [-v]
115 Lists all of the devices from which it may be possible to load
116 modules. If -v is specified, more details are printed.
117
118 lsmod [-v]
119 Displays loaded modules. If -v is specified, more details are
120 shown.
121
122 more file [file ...]
123 Display the files specified, with a pause at each screen-#rows
124 displayed.
125
126 read [-t seconds] [-p prompt] [variable]
127 Reads a line of input from the terminal, storing it in variable
128 if specified. A timeout can be specified with -t, though it will
129 be canceled at the first key pressed. A prompt may also be
130 displayed through the -p flag.
131
132 reboot Immediately reboots the system.
133
134 set variable
135 set variable=value
136 Set loader's environment variables.
137
138 show [variable]
139 Displays the specified variable's value, or all variables and
140 their values if variable is not specified.
141
142 unload Remove all modules from memory.
143
144 unset variable
145 Removes variable from the environment.
146
147 ? Lists available commands.
148
149 Builtin Environment Variables
150 The loader has actually two different kinds of `environment' variables.
151 There are ANS Forth's environmental queries, and a separate space of
152 environment variables used by builtins, which are not directly available
153 to Forth words. It is the latter type that this section covers.
154
155 Environment variables can be set and unset through the set and unset
156 builtins, and can have their values interactively examined through the
157 use of the show builtin. Their values can also be accessed as described
158 in BUILTIN PARSER.
159
160 Notice that these environment variables are not inherited by any shell
161 after the system has been booted.
162
163 A few variables are set automatically by loader. Others can affect the
164 behavior of either loader or the kernel at boot. Some options may
165 require a value, while others define behavior just by being set. Both
166 types of builtin variables are described below.
167
168 autoboot_delay
169 Number of seconds autoboot will wait before booting. If this
170 variable is not defined, autoboot will default to 10 seconds.
171
172 If set to "NO", no autoboot will be automatically attempted
173 after processing /boot/loader.rc, though explicit autoboot's
174 will be processed normally, defaulting to 10 seconds delay.
175
176 If set to "0", no delay will be inserted, but user still will
177 be able to interrupt autoboot process and escape into the
178 interactive mode by pressing some key on the console while
179 kernel and modules are being loaded.
180
181 If set to "-1", no delay will be inserted and loader will
182 engage interactive mode only if autoboot has failed for some
183 reason.
184
185 boot_ask Will set kernel(1M) -a option.
186
187 boot_debug
188 Will set kernel(1M) -d option.
189
190 boot_kmdb
191 Will set kernel(1M) -k option.
192
193 boot_reconfigure
194 Will set kernel(1M) -r option.
195
196 boot_single
197 Will set kernel(1M) -s option.
198
199 boot_verbose
200 Will set kernel(1M) -v option.
201
202 boot-args
203 Will set custom arguments for the kernel. If set in loader
204 configuration, the loader startup will parse the boot-args
205 value to set boot prefixed variables listed above, any
206 unrecognized options are added to kernel command line verbatim.
207
208 bootfile The name of the kernel.
209
210 console Defines the current console or consoles. Multiple consoles may
211 be specified. In that case, the first listed console will
212 become the default console for the kernel(1M).
213
214 currdev Selects the default device. Syntax for devices is odd.
215
216 interpret
217 Has the value "ok" if the Forth's current state is
218 interpreting.
219
220 screen-#rows
221 Define the number of lines on the screen, to be used by the
222 pager.
223
224 module_path
225 Sets the list of directories which will be searched for modules
226 named in a load command or implicitly required by a dependency.
227 The default value for this variable is
228 "/platform/i86pc/${ISADIR}"
229
230 prompt Value of loader's prompt. Defaults to "${interpret}". If
231 variable prompt is unset, the default prompt is `>'.
232
233 os_console
234 If set, the value is used to set kernel(1M) console property.
235
236 Other variables are used for loader or to set kernel properties or for
237 informational purposes.
238
239 Builtin Parser
240 When a builtin command is executed, the rest of the line is taken by it
241 as arguments, and it is processed by a special parser which is not used
242 for regular Forth commands.
243
244 This special parser applies the following rules to the parsed text:
245
246 1. All backslash characters are preprocessed.
247
248 o \b , \f , \r , \n and \t are processed as in C.
249
250 o \s is converted to a space.
251
252 o \v is converted to ASCII 11.
253
254 o \z is just skipped. Useful for things like "\0xf\z\0xf".
255
256 o \0xN and \0xNN are replaced by the hex N or NN.
257
258 o \NNN is replaced by the octal NNN ASCII character.
259
260 o \" , \' and \$ will escape these characters, preventing them
261 from receiving special treatment in Step 2, described below.
262
263 o \\ will be replaced with a single \ .
264
265 o In any other occurrence, backslash will just be removed.
266
267 2. Every string between non-escaped quotes or double-quotes will be
268 treated as a single word for the purposes of the remaining steps.
269
270 3. Replace any $VARIABLE or ${VARIABLE} with the value of the
271 environment variable VARIABLE.
272
273 4. Space-delimited arguments are passed to the called builtin command.
274 Spaces can also be escaped through the use of \\ .
275
276 An exception to this parsing rule exists, and is described in Builtins
277 And FORTH.
278
279 Builtins And FORTH
280 All builtin words are state-smart, immediate words. If interpreted, they
281 behave exactly as described previously. If they are compiled, though,
282 they extract their arguments from the stack instead of the command line.
283
284 If compiled, the builtin words expect to find, at execution time, the
285 following parameters on the stack:
286 addrN lenN ... addr2 len2 addr1 len1 N
287 where addrX lenX are strings which will compose the command line that
288 will be parsed into the builtin's arguments. Internally, these strings
289 are concatenated in from 1 to N, with a space put between each one.
290
291 If no arguments are passed, a 0 must be passed, even if the builtin
292 accepts no arguments.
293
294 While this behavior has benefits, it has its trade-offs. If the
295 execution token of a builtin is acquired (through ' or [']), and then
296 passed to catch or execute, the builtin behavior will depend on the
297 system state at the time catch or execute is processed! This is
298 particularly annoying for programs that want or need to handle
299 exceptions. In this case, the use of a proxy is recommended. For
300 example:
301 : (boot) boot;
302
303 FICL
304 FICL is a Forth interpreter written in C, in the form of a forth virtual
305 machine library that can be called by C functions and vice versa.
306
307 In loader, each line read interactively is then fed to FICL, which may
308 call loader back to execute the builtin words. The builtin include will
309 also feed FICL, one line at a time.
310
311 The words available to FICL can be classified into four groups. The ANS
312 Forth standard words, extra FICL words, extra FreeBSD words, and the
313 builtin commands; the latter were already described. The ANS Forth
314 standard words are listed in the STANDARDS section. The words falling in
315 the two other groups are described in the following subsections.
316
317 FICL Extra Words
318 .env
319
320 .ver
321
322 -roll
323
324 2constant
325
326 >name
327
328 body>
329
330 compare This is the STRING word set's compare.
331
332 compile-only
333
334 endif
335
336 forget-wid
337
338 parse-word
339
340 sliteral This is the STRING word set's sliteral.
341
342 wid-set-super
343
344 w@
345
346 w!
347
348 x.
349
350 empty
351
352 cell-
353
354 -rot
355
356 Loader Extra Words
357 $ (--) Evaluates the remainder of the input buffer, after having
358 printed it first.
359
360 % (--) Evaluates the remainder of the input buffer under a catch
361 exception guard.
362
363 .# Works like . but without outputting a trailing space.
364
365 fclose (fd --)
366 Closes a file.
367
368 fkey (fd -- char)
369 Reads a single character from a file.
370
371 fload (fd --)
372 Processes a file fd.
373
374 fopen (addr len mode -- fd)
375 Opens a file. Returns a file descriptor, or -1 in case of
376 failure. The mode parameter selects whether the file is to be
377 opened for read access, write access, or both. The constants
378 O_RDONLY, O_WRONLY, and O_RDWR are defined in
379 /boot/forth/support.4th, indicating read only, write only, and
380 read-write access, respectively.
381
382 fread (fd addr len -- len')
383 Tries to read len bytes from file fd into buffer addr. Returns
384 the actual number of bytes read, or -1 in case of error or end
385 of file.
386
387 heap? (-- cells)
388 Return the space remaining in the dictionary heap, in cells.
389 This is not related to the heap used by dynamic memory
390 allocation words.
391
392 inb (port -- char)
393 Reads a byte from a port.
394
395 key (-- char)
396 Reads a single character from the console.
397
398 key? (-- flag)
399 Returns true if there is a character available to be read from
400 the console.
401
402 ms (u --)
403 Waits u microseconds.
404
405 outb (port char --)
406 Writes a byte to a port.
407
408 seconds (-- u)
409 Returns the number of seconds since midnight.
410
411 tib> (-- addr len)
412 Returns the remainder of the input buffer as a string on the
413 stack.
414
415 Loader Defined Environmental Queries
416 arch-i386
417 TRUE if the architecture is IA32.
418
419 loader_version
420 loader version.
421
422 Errors
423 The following values are thrown by loader:
424
425 100 Any type of error in the processing of a builtin.
426
427 -1 Abort executed.
428
429 -2 Abort" executed.
430
431 -56 Quit executed.
432
433 -256 Out of interpreting text.
434
435 -257 Need more text to succeed -- will finish on next run.
436
437 -258 Bye executed.
438
439 -259 Unspecified error.
440
441 FILES
442 /boot/defaults/loader.conf
443 /boot/conf.d/*
444 /boot/loader.conf
445 /boot/loader.conf.local loader configuration files, as described in
446 loader.conf(4).
447 /boot/loader.help Loaded by help. Contains the help messages.
448 /boot/loader.rc loader bootstrapping script.
449 /boot/forth/loader.4th Extra builtin-like words.
450 /boot/forth/support.4th loader.conf processing words.
451 /boot/zfsloader loader itself.
452
453 EXAMPLES
454 Boot in single user mode:
455
456 boot -s
457
458 Load the kernel, a boot_archive, and then autoboot in five seconds.
459 Notice that a kernel must be loaded before any other load command is
460 attempted.
461
462 load /platform/i86pc/kernel/amd64/unix
463 load -t rootfs /platform/i86pc/amd64/boot_archive
464 autoboot 5
465
466 SEE ALSO
467 boot(1M), btxld(1onbld), loader.conf(4)
468
469 STANDARDS
470 For the purposes of ANS Forth compliance, loader is an ANS Forth System
471 with Environmental Restrictions, Providing .(, :noname, ?do, parse, pick,
472 roll, refill, to, value, \, false, true, <>, 0<>, compile, , erase, nip,
473 tuck and marker from the Core Extensions word set, Providing the
474 Exception Extensions word set, Providing the Locals Extensions word set,
475 Providing the Memory-Allocation Extensions word set, Providing .s, bye,
476 forget, see, words, [if], [else] and [then] from the Programming-Tools
477 extension word set, Providing the Search-Order extensions word set.
478
479 illumos April 20, 2017 illumos