Print this page
NEX-16819 loader UEFI support
Includes work by Toomas Soome <tsoome@me.com>
Upstream commits:
loader: pxe receive cleanup
9475 libefi: Do not return only if ReceiveFilter
installboot: should support efi system partition
8931 boot1.efi: scan all display modes rather than
loader: spinconsole updates
loader: gfx experiment to try GOP Blt() function.
sha1 build test
loader: add sha1 hash calculation
common/sha1: update for loader build
loader: biosdisk rework
uts: 32-bit kernel FB needs mapping in low memory
uts: add diag-device
uts: boot console mirror with diag-device
uts: enable very early console on ttya
kmdb: add diag-device as input/output device
uts: test VGA memory exclusion from mapping
uts: clear boot mapping and protect boot pages test
uts: add dboot map debug printf
uts: need to release FB pages in release_bootstrap()
uts: add screenmap ioctl
uts: update sys/queue.h
loader: add illumos uts/common to include path
loader: tem/gfx font cleanup
loader: vbe checks
uts: gfx_private set KD_TEXT when KD_RESETTEXT is
uts: gfx 8-bit update
loader: gfx 8-bit fix
loader: always set media size from partition.
uts: MB2 support for 32-bit kernel
loader: x86 should have tem 80x25
uts: x86 should have tem 80x25
uts: font update
loader: font update
uts: tem attributes
loader: tem.c comment added
uts: use font module
loader: add font module
loader: build rules for new font setup
uts: gfx_private update for new font structure
uts: early boot update for new font structure
uts: font update
uts: font build rules update for new fonts
uts: tem update to new font structure
loader: module.c needs to include tem_impl.h
uts: gfx_private 8x16 font rework
uts: make font_lookup public
loader: font rework
uts: font rework
9259 libefi: efi_alloc_and_read should check for PMBR
uts: tem utf-8 support
loader: implement tem utf-8 support
loader: tem should be able to display UTF-8
7784 uts: console input should support utf-8
7796 uts: ldterm default to utf-8
uts: do not reset serial console
uts: set up colors even if tem is not console
uts: add type for early boot properties
uts: gfx_private experiment with drm and vga
uts: gfx_private should use setmode drm callback.
uts: identify FB types and set up gfx_private based
loader: replace gop and vesa with framebuffer
uts: boot needs simple tem to support mdb
uts: boot_keyboard should emit esc sequences for
uts: gfx_private FB showuld be written by line
kmdb: set terminal window size
uts: gfx_private needs to keep track of early boot FB
pnglite: move pnglite to usr/src/common
loader: gfx_fb
ficl-sys: add gfx primitives
loader: add illumos.png logo
ficl: add fb-putimage
loader: add png support
loader: add alpha blending for gfx_fb
loader: use term-drawrect for menu frame
ficl: add simple gfx words
uts: provide fb_info via fbgattr dev_specific array.
uts: gfx_private add alpha blending
uts: update sys/ascii.h
uts: tem OSC support (incomplete)
uts: implement env module support and use data from
uts: tem get colors from early boot data
loader: use crc32 from libstand (libz)
loader: optimize for size
loader: pass tem info to the environment
loader: import tem for loader console
loader: UEFI loader needs to set ISADIR based on
loader: need UEFI32 support
8918 loader.efi: add vesa edid support
uts: tem_safe_pix_clear_prom_output() should only
uts: tem_safe_pix_clear_entire_screen() should use
uts: tem_safe_check_first_time() should query cursor
uts: tem implement cls callback & visual_io v4
uts: gfx_vgatext use block cursor for vgatext
uts: gfx_private implement cls callback & visual_io
uts: gfx_private bitmap framebuffer implementation
uts: early start frame buffer console support
uts: font functions should check the input char
uts: font rendering should support 16/24/32bit depths
uts: use smallest font as fallback default.
uts: update terminal dimensions based on selected
7834 uts: vgatext should use gfx_private
uts: add spacing property to 8859-1.bdf
terminfo: add underline for sun-color
terminfo: sun-color has 16 colors
uts: add font load callback type
loader: do not repeat int13 calls with error 0x20 and
8905 loader: add skein/edonr support
8904 common/crypto: make skein and edonr loader
Reviewed by: Yuri Pankov <yuri.pankov@nexenta.com>
Reviewed by: Sanjay Nadkarni <sanjay.nadkarni@nexenta.com>
Reviewed by: Evan Layton <evan.layton@nexenta.com>
Revert "NEX-16819 loader UEFI support"
This reverts commit ec06b9fc617b99234e538bf2e7e4d02a24993e0c.
Reverting due to failures in the zfs-tests and the sharefs-tests
NEX-16819 loader UEFI support
Includes work by Toomas Soome <tsoome@me.com>
Upstream commits:
loader: pxe receive cleanup
9475 libefi: Do not return only if ReceiveFilter
installboot: should support efi system partition
8931 boot1.efi: scan all display modes rather than
loader: spinconsole updates
loader: gfx experiment to try GOP Blt() function.
sha1 build test
loader: add sha1 hash calculation
common/sha1: update for loader build
loader: biosdisk rework
uts: 32-bit kernel FB needs mapping in low memory
uts: add diag-device
uts: boot console mirror with diag-device
uts: enable very early console on ttya
kmdb: add diag-device as input/output device
uts: test VGA memory exclusion from mapping
uts: clear boot mapping and protect boot pages test
uts: add dboot map debug printf
uts: need to release FB pages in release_bootstrap()
uts: add screenmap ioctl
uts: update sys/queue.h
loader: add illumos uts/common to include path
loader: tem/gfx font cleanup
loader: vbe checks
uts: gfx_private set KD_TEXT when KD_RESETTEXT is
uts: gfx 8-bit update
loader: gfx 8-bit fix
loader: always set media size from partition.
uts: MB2 support for 32-bit kernel
loader: x86 should have tem 80x25
uts: x86 should have tem 80x25
uts: font update
loader: font update
uts: tem attributes
loader: tem.c comment added
uts: use font module
loader: add font module
loader: build rules for new font setup
uts: gfx_private update for new font structure
uts: early boot update for new font structure
uts: font update
uts: font build rules update for new fonts
uts: tem update to new font structure
loader: module.c needs to include tem_impl.h
uts: gfx_private 8x16 font rework
uts: make font_lookup public
loader: font rework
uts: font rework
libefi: efi_alloc_and_read should check for PMBR
uts: tem utf-8 support
loader: implement tem utf-8 support
loader: tem should be able to display UTF-8
7784 uts: console input should support utf-8
7796 uts: ldterm default to utf-8
uts: do not reset serial console
uts: set up colors even if tem is not console
uts: add type for early boot properties
uts: gfx_private experiment with drm and vga
uts: gfx_private should use setmode drm callback.
uts: identify FB types and set up gfx_private based
loader: replace gop and vesa with framebuffer
uts: boot needs simple tem to support mdb
uts: boot_keyboard should emit esc sequences for
uts: gfx_private FB showuld be written by line
kmdb: set terminal window size
uts: gfx_private needs to keep track of early boot FB
pnglite: move pnglite to usr/src/common
loader: gfx_fb
ficl-sys: add gfx primitives
loader: add illumos.png logo
ficl: add fb-putimage
loader: add png support
loader: add alpha blending for gfx_fb
loader: use term-drawrect for menu frame
ficl: add simple gfx words
uts: provide fb_info via fbgattr dev_specific array.
uts: gfx_private add alpha blending
uts: update sys/ascii.h
uts: tem OSC support (incomplete)
uts: implement env module support and use data from
uts: tem get colors from early boot data
loader: use crc32 from libstand (libz)
loader: optimize for size
loader: pass tem info to the environment
loader: import tem for loader console
loader: UEFI loader needs to set ISADIR based on
loader: need UEFI32 support
8918 loader.efi: add vesa edid support
uts: tem_safe_pix_clear_prom_output() should only
uts: tem_safe_pix_clear_entire_screen() should use
uts: tem_safe_check_first_time() should query cursor
uts: tem implement cls callback & visual_io v4
uts: gfx_vgatext use block cursor for vgatext
uts: gfx_private implement cls callback & visual_io
uts: gfx_private bitmap framebuffer implementation
uts: early start frame buffer console support
uts: font functions should check the input char
uts: font rendering should support 16/24/32bit depths
uts: use smallest font as fallback default.
uts: update terminal dimensions based on selected
7834 uts: vgatext should use gfx_private
uts: add spacing property to 8859-1.bdf
terminfo: add underline for sun-color
terminfo: sun-color has 16 colors
uts: add font load callback type
loader: do not repeat int13 calls with error 0x20 and
8905 loader: add skein/edonr support
8904 common/crypto: make skein and edonr loader
Reviewed by: Yuri Pankov <yuri.pankov@nexenta.com>
Reviewed by: Sanjay Nadkarni <sanjay.nadkarni@nexenta.com>
Reviewed by: Evan Layton <evan.layton@nexenta.com>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man5/loader.5
+++ new/usr/src/man/man5/loader.5
1 1 .\" Copyright (c) 1999 Daniel C. Sobral
2 2 .\" All rights reserved.
3 3 .\"
4 4 .\" Redistribution and use in source and binary forms, with or without
5 5 .\" modification, are permitted provided that the following conditions
6 6 .\" are met:
7 7 .\" 1. Redistributions of source code must retain the above copyright
8 8 .\" notice, this list of conditions and the following disclaimer.
9 9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 10 .\" notice, this list of conditions and the following disclaimer in the
11 11 .\" documentation and/or other materials provided with the distribution.
12 12 .\"
13 13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23 23 .\" SUCH DAMAGE.
24 24 .\"
25 25 .Dd Apr 20, 2017
26 26 .Dt LOADER 5
27 27 .Os
28 28 .Sh NAME
29 29 .Nm loader
30 30 .Nd kernel bootstrapping final stage
31 31 .Sh DESCRIPTION
32 32 The
33 33 .Nm
34 34 is the final stage of
35 35 .Nm illumos Ns 's
36 36 kernel bootstrapping process.
37 37 The actual name for the stage depends on the platform.
38 38 On IA32 (i386) architectures with BIOS firmware, it is a
39 39 .Pa BTX
40 40 client and named
41 41 .Nm zfsloader .
42 42 It is linked statically to libstand and usually located in the directory
43 43 .Pa /boot .
44 44 .Pp
45 45 .Nm
46 46 supports booting from
47 47 .Cm ZFS ,
48 48 .Cm UFS ,
49 49 .Cm PCFS ,
50 50 .Cm HSFS
51 51 and
52 52 .Cm NFS
53 53 file systems.
54 54 Additionally,
55 55 .Nm
56 56 can load files from the
57 57 .Cm TFTP
58 58 file service.
59 59 The NFS and TFTP based boot is enabled via
60 60 .Xr pxeboot 5 .
61 61 The
62 62 .Nm
63 63 also does support uncompressing gzip files while reading.
64 64 The uncompression will happen automatically if the compressed file is stored
65 65 without .gz suffix or if the file is accessed by leaving out the .gz suffix from
66 66 the name.
67 67 If the file is referred by full name, including .gz suffix, then the file
68 68 content is read as is and the uncompression is not performed.
69 69 .Pp
70 70 .Nm
71 71 provides a scripting language that can be used to
72 72 automate tasks, do pre-configuration or assist in recovery
73 73 procedures.
74 74 This scripting language is roughly divided in
75 75 two main components.
76 76 The smaller one is a set of commands
77 77 designed for direct use by the casual user, called "builtin
78 78 commands" for historical reasons.
79 79 The main drive behind these commands is user-friendliness.
80 80 The bigger component is an
81 81 .Tn ANS
82 82 Forth compatible Forth interpreter based on FICL, by
83 83 .An John Sadler .
84 84 .Pp
85 85 During initialization,
86 86 .Nm
87 87 will probe for a console and set the
|
↓ open down ↓ |
87 lines elided |
↑ open up ↑ |
88 88 .Va console
89 89 variable, or set it to serial console
90 90 .Pq Do Li ttya Dc - Dq Li ttyd
91 91 if the previous boot stage used that.
92 92 If multiple consoles are selected, they will be listed separated by commas.
93 93 Then, devices are probed,
94 94 .Va currdev
95 95 and
96 96 .Va loaddev
97 97 are set, and
98 -.Va COLUMNS ,
99 -.Va LINES ,
98 +.Va screen-#cols ,
99 +.Va screen-#rows ,
100 100 and
101 101 .Va ISADIR
102 102 are set.
103 103 Next,
104 104 .Tn FICL
105 105 is initialized, the builtin words are added to its vocabulary.
106 106 The inner interpreter
107 107 .Nm
108 108 will use with
109 109 .Tn FICL
110 110 is then set to
111 111 .Ic interpret ,
112 112 which is
113 113 .Tn FICL Ns 's
114 114 default.
115 115 After that,
116 116 .Pa /boot/loader.rc
117 117 is processed if available.
118 118 These files are processed through the
119 119 .Ic include
120 120 command, which reads all of them into memory before processing them,
121 121 making disk changes possible.
122 122 .Pp
123 123 At this point, if an
124 124 .Ic autoboot
125 125 has not been tried, and if
126 126 .Va autoboot_delay
127 127 is not set to
128 128 .Dq Li NO
129 129 (not case sensitive), then an
130 130 .Ic autoboot
131 131 will be tried.
132 132 If the system gets past this point,
133 133 .Va prompt
134 134 will be set and
135 135 .Nm
136 136 will engage interactive mode.
137 137 Please note that historically even when
138 138 .Va autoboot_delay
139 139 is set to
140 140 .Dq Li 0
141 141 user will be able to interrupt autoboot process by pressing some key
142 142 on the console while kernel and modules are being loaded.
143 143 In some
144 144 cases such behaviour may be undesirable, to prevent it set
145 145 .Va autoboot_delay
146 146 to
147 147 .Dq Li -1 ,
148 148 in this case
149 149 .Nm
150 150 will engage interactive mode only if
151 151 .Ic autoboot
152 152 has failed.
153 153 .Ss Builtin Commands
154 154 In
155 155 .Nm ,
156 156 builtin commands take parameters from the command line.
157 157 If an error condition occurs, an exception will be generated,
158 158 which can be intercepted using
159 159 .Tn ANS
160 160 Forth exception handling
161 161 words.
162 162 If not intercepted, an error message will be displayed and
163 163 the interpreter's state will be reset, emptying the stack and restoring
164 164 interpreting mode.
165 165 .Pp
166 166 The builtin commands available are:
167 167 .Pp
168 168 .Bl -tag -width Ds -compact
169 169 .It Ic autoboot Op Ar seconds Op Ar prompt
170 170 Proceeds to bootstrap the system after a number of seconds, if not
171 171 interrupted by the user.
172 172 Displays a countdown prompt
173 173 warning the user the system is about to be booted,
174 174 unless interrupted by a key press.
175 175 The kernel will be loaded first if necessary.
176 176 Defaults to 10 seconds.
177 177 .Pp
178 178 .It Ic bcachestat
179 179 Displays statistics about disk cache usage.
180 180 For debugging only.
181 181 .Pp
182 182 .It Ic boot
183 183 .It Ic boot Ar kernelname Op Cm ...
184 184 .It Ic boot Fl flag Cm ...
185 185 Immediately proceeds to bootstrap the system, loading the kernel
186 186 if necessary.
187 187 Any flags or arguments are passed to the kernel, but they
188 188 must precede the kernel name, if a kernel name is provided.
189 189 .Pp
190 190 .Em WARNING :
191 191 The behavior of this builtin is changed if
192 192 .Xr loader.4th 5
193 193 is loaded.
194 194 .Pp
195 195 .It Ic chain Ar device
196 196 Chain load another boot loader from the specified device.
197 197 Device can be either disk name or partition.
198 198 .Pp
199 199 .It Ic echo Xo
200 200 .Op Fl n
201 201 .Op Aq message
202 202 .Xc
203 203 Displays text on the screen.
204 204 A new line will be printed unless
205 205 .Fl n
206 206 is specified.
207 207 .Pp
208 208 .It Ic heap
209 209 Displays memory usage statistics.
210 210 For debugging purposes only.
211 211 .Pp
212 212 .It Ic help Op topic Op subtopic
213 213 Shows help messages read from
214 214 .Pa /boot/loader.help .
215 215 The special topic
216 216 .Em index
217 217 will list the topics available.
218 218 .Pp
219 219 .It Ic include Ar file Op Ar
220 220 Process script files.
221 221 Each file, in turn, is completely read into memory,
222 222 and then each of its lines is passed to the command line interpreter.
223 223 If any error is returned by the interpreter, the include
224 224 command aborts immediately, without reading any other files, and
225 225 returns an error itself (see
226 226 .Sx ERRORS ) .
227 227 .Pp
228 228 .It Ic load Xo
229 229 .Op Fl t Ar type
230 230 .Ar file Cm ...
231 231 .Xc
232 232 Loads a kernel or file of opaque contents tagged as being of the type
233 233 .Ar type .
234 234 Kernel and modules can be either in a.out or ELF format.
235 235 Any arguments passed after the name of the file to be loaded
236 236 will be passed as arguments to that file.
237 237 .Pp
238 238 .It Ic ls Xo
239 239 .Op Fl l
240 240 .Op Ar path
241 241 .Xc
242 242 Displays a listing of files in the directory
243 243 .Ar path ,
244 244 or the root directory if
245 245 .Ar path
246 246 is not specified.
247 247 If
248 248 .Fl l
249 249 is specified, file sizes will be shown too.
250 250 .Pp
251 251 .It Ic lsdev Op Fl v
252 252 Lists all of the devices from which it may be possible to load modules.
253 253 If
254 254 .Fl v
|
↓ open down ↓ |
145 lines elided |
↑ open up ↑ |
255 255 is specified, more details are printed.
256 256 .Pp
257 257 .It Ic lsmod Op Fl v
258 258 Displays loaded modules.
259 259 If
260 260 .Fl v
261 261 is specified, more details are shown.
262 262 .Pp
263 263 .It Ic more Ar file Op Ar
264 264 Display the files specified, with a pause at each
265 -.Va LINES
265 +.Va screen-#rows
266 266 displayed.
267 267 .Pp
268 268 .It Ic read Xo
269 269 .Op Fl t Ar seconds
270 270 .Op Fl p Ar prompt
271 271 .Op Va variable
272 272 .Xc
273 273 Reads a line of input from the terminal, storing it in
274 274 .Va variable
275 275 if specified.
276 276 A timeout can be specified with
277 277 .Fl t ,
278 278 though it will be canceled at the first key pressed.
279 279 A prompt may also be displayed through the
280 280 .Fl p
281 281 flag.
282 282 .Pp
283 283 .It Ic reboot
284 284 Immediately reboots the system.
285 285 .Pp
286 286 .It Ic set Ar variable
287 287 .It Ic set Ar variable Ns = Ns Ar value
288 288 Set loader's environment variables.
289 289 .Pp
290 290 .It Ic show Op Va variable
291 291 Displays the specified variable's value, or all variables and their
292 292 values if
293 293 .Va variable
294 294 is not specified.
295 295 .Pp
296 296 .It Ic unload
297 297 Remove all modules from memory.
298 298 .Pp
299 299 .It Ic unset Va variable
300 300 Removes
301 301 .Va variable
302 302 from the environment.
303 303 .Pp
304 304 .It Ic \&?
305 305 Lists available commands.
306 306 .El
307 307 .Ss Builtin Environment Variables
308 308 The
309 309 .Nm
310 310 has actually two different kinds of
311 311 .Sq environment
312 312 variables.
313 313 There are ANS Forth's
314 314 .Em environmental queries ,
315 315 and a separate space of environment variables used by builtins, which
316 316 are not directly available to Forth words.
317 317 It is the latter type that this section covers.
318 318 .Pp
319 319 Environment variables can be set and unset through the
320 320 .Ic set
321 321 and
322 322 .Ic unset
323 323 builtins, and can have their values interactively examined through the
324 324 use of the
325 325 .Ic show
326 326 builtin.
327 327 Their values can also be accessed as described in
328 328 .Sx BUILTIN PARSER .
329 329 .Pp
330 330 Notice that these environment variables are not inherited by any shell
331 331 after the system has been booted.
332 332 .Pp
333 333 A few variables are set automatically by
334 334 .Nm .
335 335 Others can affect the behavior of either
336 336 .Nm
337 337 or the kernel at boot.
338 338 Some options may require a value,
339 339 while others define behavior just by being set.
340 340 Both types of builtin variables are described below.
341 341 .Bl -tag -width bootfile
342 342 .It Va autoboot_delay
343 343 Number of seconds
344 344 .Ic autoboot
345 345 will wait before booting.
346 346 If this variable is not defined,
347 347 .Ic autoboot
348 348 will default to 10 seconds.
349 349 .Pp
350 350 If set to
351 351 .Dq Li NO ,
352 352 no
353 353 .Ic autoboot
354 354 will be automatically attempted after processing
355 355 .Pa /boot/loader.rc ,
356 356 though explicit
357 357 .Ic autoboot Ns 's
358 358 will be processed normally, defaulting to 10 seconds delay.
359 359 .Pp
360 360 If set to
361 361 .Dq Li 0 ,
362 362 no delay will be inserted, but user still will be able to interrupt
363 363 .Ic autoboot
364 364 process and escape into the interactive mode by pressing some key
365 365 on the console while kernel and
366 366 modules are being loaded.
367 367 .Pp
368 368 If set to
369 369 .Dq Li -1 ,
370 370 no delay will be inserted and
371 371 .Nm
372 372 will engage interactive mode only if
373 373 .Ic autoboot
374 374 has failed for some reason.
375 375 .It Va boot_ask
376 376 Will set
377 377 .Xr kernel 1M
378 378 .Fl a
379 379 option.
380 380 .It Va boot_debug
381 381 Will set
382 382 .Xr kernel 1M
383 383 .Fl d
384 384 option.
385 385 .It Va boot_kmdb
386 386 Will set
387 387 .Xr kernel 1M
388 388 .Fl k
389 389 option.
390 390 .It Va boot_reconfigure
391 391 Will set
392 392 .Xr kernel 1M
393 393 .Fl r
394 394 option.
395 395 .It Va boot_single
396 396 Will set
397 397 .Xr kernel 1M
398 398 .Fl s
399 399 option.
400 400 .It Va boot_verbose
401 401 Will set
402 402 .Xr kernel 1M
403 403 .Fl v
404 404 option.
405 405 .It Va boot-args
406 406 Will set custom arguments for the kernel.
407 407 If set in
408 408 .Nm
409 409 configuration, the
410 410 .Nm
411 411 startup will parse the
412 412 .Va boot-args
413 413 value to set boot prefixed variables listed above, any unrecognized options
414 414 are added to kernel command line verbatim.
415 415 .It Va bootfile
416 416 The name of the kernel.
417 417 .It Va console
418 418 Defines the current console or consoles.
419 419 Multiple consoles may be specified.
|
↓ open down ↓ |
144 lines elided |
↑ open up ↑ |
420 420 In that case, the first listed console will become the default console for
421 421 the
422 422 .Xr kernel 1M .
423 423 .It Va currdev
424 424 Selects the default device.
425 425 Syntax for devices is odd.
426 426 .It Va interpret
427 427 Has the value
428 428 .Dq Li ok
429 429 if the Forth's current state is interpreting.
430 -.It Va LINES
430 +.It Va screen-#rows
431 431 Define the number of lines on the screen, to be used by the pager.
432 432 .It Va module_path
433 433 Sets the list of directories which will be searched for modules
434 434 named in a load command or implicitly required by a dependency.
435 435 The default value for this variable is
436 436 .Dq Li /platform/i86pc/${ISADIR}
437 437 .It Va prompt
438 438 Value of
439 439 .Nm Ns 's
440 440 prompt.
441 441 Defaults to
442 442 .Dq Li "${interpret}" .
443 443 If variable
444 444 .Va prompt
445 445 is unset, the default prompt is
446 446 .Ql > .
447 447 .It Va os_console
448 448 If set, the value is used to set
449 449 .Xr kernel 1M
450 450 .Va console
451 451 property.
452 452 .El
453 453 .Pp
454 454 Other variables are used for loader or to set kernel properties or for
455 455 informational purposes.
456 456 .Ss Builtin Parser
457 457 When a builtin command is executed, the rest of the line is taken
458 458 by it as arguments, and it is processed by a special parser which
459 459 is not used for regular Forth commands.
460 460 .Pp
461 461 This special parser applies the following rules to the parsed text:
462 462 .Bl -enum
463 463 .It
464 464 All backslash characters are preprocessed.
465 465 .Bl -bullet
466 466 .It
467 467 \eb , \ef , \er , \en and \et are processed as in C.
468 468 .It
469 469 \es is converted to a space.
470 470 .It
471 471 \ev is converted to
472 472 .Tn ASCII
473 473 11.
474 474 .It
475 475 \ez is just skipped.
476 476 Useful for things like
477 477 .Dq \e0xf\ez\e0xf .
478 478 .It
479 479 \e0xN and \e0xNN are replaced by the hex N or NN.
480 480 .It
481 481 \eNNN is replaced by the octal NNN
482 482 .Tn ASCII
483 483 character.
484 484 .It
485 485 \e" , \e' and \e$ will escape these characters, preventing them from
486 486 receiving special treatment in Step 2, described below.
487 487 .It
488 488 \e\e will be replaced with a single \e .
489 489 .It
490 490 In any other occurrence, backslash will just be removed.
491 491 .El
492 492 .It
493 493 Every string between non-escaped quotes or double-quotes will be treated
494 494 as a single word for the purposes of the remaining steps.
495 495 .It
496 496 Replace any
497 497 .Li $VARIABLE
498 498 or
499 499 .Li ${VARIABLE}
500 500 with the value of the environment variable
501 501 .Va VARIABLE .
502 502 .It
503 503 Space-delimited arguments are passed to the called builtin command.
504 504 Spaces can also be escaped through the use of \e\e .
505 505 .El
506 506 .Pp
507 507 An exception to this parsing rule exists, and is described in
508 508 .Sx Builtins And FORTH .
509 509 .Ss Builtins And FORTH
510 510 All builtin words are state-smart, immediate words.
511 511 If interpreted, they behave exactly as described previously.
512 512 If they are compiled, though,
513 513 they extract their arguments from the stack instead of the command line.
514 514 .Pp
515 515 If compiled, the builtin words expect to find, at execution time, the
516 516 following parameters on the stack:
517 517 .D1 Ar addrN lenN ... addr2 len2 addr1 len1 N
518 518 where
519 519 .Ar addrX lenX
520 520 are strings which will compose the command line that will be parsed
521 521 into the builtin's arguments.
522 522 Internally, these strings are concatenated in from 1 to N,
523 523 with a space put between each one.
524 524 .Pp
525 525 If no arguments are passed, a 0
526 526 .Em must
527 527 be passed, even if the builtin accepts no arguments.
528 528 .Pp
529 529 While this behavior has benefits, it has its trade-offs.
530 530 If the execution token of a builtin is acquired (through
531 531 .Ic '
532 532 or
533 533 .Ic ['] ) ,
534 534 and then passed to
535 535 .Ic catch
536 536 or
537 537 .Ic execute ,
538 538 the builtin behavior will depend on the system state
539 539 .Bf Em
540 540 at the time
541 541 .Ic catch
542 542 or
543 543 .Ic execute
544 544 is processed!
545 545 .Ef
546 546 This is particularly annoying for programs that want or need to
547 547 handle exceptions.
548 548 In this case, the use of a proxy is recommended.
549 549 For example:
550 550 .Dl : (boot) boot ;
551 551 .Ss FICL
552 552 .Tn FICL
553 553 is a Forth interpreter written in C, in the form of a forth
554 554 virtual machine library that can be called by C functions and vice
555 555 versa.
556 556 .Pp
557 557 In
558 558 .Nm ,
559 559 each line read interactively is then fed to
560 560 .Tn FICL ,
561 561 which may call
562 562 .Nm
563 563 back to execute the builtin words.
564 564 The builtin
565 565 .Ic include
566 566 will also feed
567 567 .Tn FICL ,
568 568 one line at a time.
569 569 .Pp
570 570 The words available to
571 571 .Tn FICL
572 572 can be classified into four groups.
573 573 The
574 574 .Tn ANS
575 575 Forth standard words, extra
576 576 .Tn FICL
577 577 words, extra
578 578 .Fx
579 579 words, and the builtin commands;
580 580 the latter were already described.
581 581 The
582 582 .Tn ANS
583 583 Forth standard words are listed in the
584 584 .Sx STANDARDS
585 585 section.
586 586 The words falling in the two other groups are described in the
587 587 following subsections.
588 588 .Ss FICL Extra Words
589 589 .Bl -tag -width wid-set-super
590 590 .It Ic .env
591 591 .It Ic .ver
592 592 .It Ic -roll
593 593 .It Ic 2constant
594 594 .It Ic >name
595 595 .It Ic body>
596 596 .It Ic compare
597 597 This is the STRING word set's
598 598 .Ic compare .
599 599 .It Ic compile-only
600 600 .It Ic endif
601 601 .It Ic forget-wid
602 602 .It Ic parse-word
603 603 .It Ic sliteral
604 604 This is the STRING word set's
605 605 .Ic sliteral .
606 606 .It Ic wid-set-super
607 607 .It Ic w@
608 608 .It Ic w!
609 609 .It Ic x.
610 610 .It Ic empty
611 611 .It Ic cell-
612 612 .It Ic -rot
613 613 .El
614 614 .Ss Loader Extra Words
615 615 .Bl -tag -width XXXXXXXX
616 616 .It Ic \&$ Pq --
617 617 Evaluates the remainder of the input buffer, after having printed it first.
618 618 .It Ic \&% Pq --
619 619 Evaluates the remainder of the input buffer under a
620 620 .Ic catch
621 621 exception guard.
622 622 .It Ic .#
623 623 Works like
624 624 .Ic \&.
625 625 but without outputting a trailing space.
626 626 .It Ic fclose Pq Ar fd --
627 627 Closes a file.
628 628 .It Ic fkey Pq Ar fd -- char
629 629 Reads a single character from a file.
630 630 .It Ic fload Pq Ar fd --
631 631 Processes a file
632 632 .Em fd .
633 633 .It Ic fopen Pq Ar addr len mode Li -- Ar fd
634 634 Opens a file.
635 635 Returns a file descriptor, or \-1 in case of failure.
636 636 The
637 637 .Ar mode
638 638 parameter selects whether the file is to be opened for read access, write
639 639 access, or both.
640 640 The constants
641 641 .Dv O_RDONLY , O_WRONLY ,
642 642 and
643 643 .Dv O_RDWR
644 644 are defined in
645 645 .Pa /boot/forth/support.4th ,
646 646 indicating read only, write only, and read-write access, respectively.
647 647 .It Xo
648 648 .Ic fread
649 649 .Pq Ar fd addr len -- len'
650 650 .Xc
651 651 Tries to read
652 652 .Em len
653 653 bytes from file
654 654 .Em fd
655 655 into buffer
656 656 .Em addr .
657 657 Returns the actual number of bytes read, or -1 in case of error or end of
658 658 file.
659 659 .It Ic heap? Pq -- Ar cells
660 660 Return the space remaining in the dictionary heap, in cells.
661 661 This is not related to the heap used by dynamic memory allocation words.
662 662 .It Ic inb Pq Ar port -- char
663 663 Reads a byte from a port.
664 664 .It Ic key Pq -- Ar char
665 665 Reads a single character from the console.
666 666 .It Ic key? Pq -- Ar flag
667 667 Returns
668 668 .Ic true
669 669 if there is a character available to be read from the console.
670 670 .It Ic ms Pq Ar u --
671 671 Waits
672 672 .Em u
673 673 microseconds.
674 674 .It Ic outb Pq Ar port char --
675 675 Writes a byte to a port.
676 676 .It Ic seconds Pq -- Ar u
677 677 Returns the number of seconds since midnight.
678 678 .It Ic tib> Pq -- Ar addr len
679 679 Returns the remainder of the input buffer as a string on the stack.
680 680 .El
681 681 .Ss Loader Defined Environmental Queries
682 682 .Bl -tag -width Ds
683 683 .It arch-i386
684 684 .Ic TRUE
685 685 if the architecture is IA32.
686 686 .It loader_version
687 687 .Nm
688 688 version.
689 689 .El
690 690 .Ss Errors
691 691 The following values are thrown by
692 692 .Nm :
693 693 .Bl -tag -width XXXXX -offset indent
694 694 .It 100
695 695 Any type of error in the processing of a builtin.
696 696 .It -1
697 697 .Ic Abort
698 698 executed.
699 699 .It -2
700 700 .Ic Abort"
701 701 executed.
702 702 .It -56
703 703 .Ic Quit
704 704 executed.
705 705 .It -256
706 706 Out of interpreting text.
707 707 .It -257
708 708 Need more text to succeed -- will finish on next run.
709 709 .It -258
710 710 .Ic Bye
711 711 executed.
712 712 .It -259
713 713 Unspecified error.
714 714 .El
715 715 .Sh FILES
716 716 .Bl -tag -width /boot/defaults/loader.conf -compact
717 717 .It Pa /boot/defaults/loader.conf
718 718 .It Pa /boot/conf.d/*
719 719 .It Pa /boot/loader.conf
720 720 .It Pa /boot/loader.conf.local
721 721 .Nm
722 722 configuration files, as described in
723 723 .Xr loader.conf 4 .
724 724 .It Pa /boot/loader.help
725 725 Loaded by
726 726 .Ic help .
727 727 Contains the help messages.
728 728 .It Pa /boot/loader.rc
729 729 .Nm
730 730 bootstrapping script.
731 731 .It Pa /boot/forth/loader.4th
732 732 Extra builtin-like words.
733 733 .It Pa /boot/forth/support.4th
734 734 .Pa loader.conf
735 735 processing words.
736 736 .It Pa /boot/zfsloader
737 737 .Nm
738 738 itself.
739 739 .El
740 740 .Sh EXAMPLES
741 741 Boot in single user mode:
742 742 .Pp
743 743 .Dl boot -s
744 744 .Pp
745 745 Load the kernel, a boot_archive, and then autoboot in five seconds.
746 746 Notice that a kernel must be loaded before any other
747 747 .Ic load
748 748 command is attempted.
749 749 .Bd -literal -offset indent
750 750 load /platform/i86pc/kernel/amd64/unix
751 751 load -t rootfs /platform/i86pc/amd64/boot_archive
752 752 autoboot 5
753 753 .Ed
754 754 .Sh SEE ALSO
755 755 .Xr boot 1M ,
756 756 .Xr btxld 1onbld ,
757 757 .Xr loader.conf 4
758 758 .Sh STANDARDS
759 759 For the purposes of ANS Forth compliance, loader is an
760 760 .Bf Em
761 761 ANS Forth System with Environmental Restrictions, Providing
762 762 .Ef
763 763 .Bf Li
764 764 .No .( ,
765 765 .No :noname ,
766 766 .No ?do ,
767 767 parse, pick, roll, refill, to, value, \e, false, true,
768 768 .No <> ,
769 769 .No 0<> ,
770 770 compile\&, , erase, nip, tuck
771 771 .Ef
772 772 .Em and
773 773 .Li marker
774 774 .Bf Em
775 775 from the Core Extensions word set, Providing the Exception Extensions
776 776 word set, Providing the Locals Extensions word set, Providing the
777 777 Memory-Allocation Extensions word set, Providing
778 778 .Ef
779 779 .Bf Li
780 780 \&.s,
781 781 bye, forget, see, words,
782 782 \&[if],
783 783 \&[else]
784 784 .Ef
785 785 .Em and
786 786 .Li [then]
787 787 .Bf Em
788 788 from the Programming-Tools extension word set, Providing the
789 789 Search-Order extensions word set.
790 790 .Ef
|
↓ open down ↓ |
350 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX