Annotation of sys/arch/i386/stand/boot/boot.8, Revision 1.1
1.1 ! nbrk 1: .\" $OpenBSD: boot.8,v 1.47 2007/05/31 19:20:03 jmc Exp $
! 2: .\"
! 3: .\" Copyright (c) 1997-2001 Michael Shalayeff
! 4: .\" All rights reserved.
! 5: .\"
! 6: .\" Redistribution and use in source and binary forms, with or without
! 7: .\" modification, are permitted provided that the following conditions
! 8: .\" are met:
! 9: .\" 1. Redistributions of source code must retain the above copyright
! 10: .\" notice, this list of conditions and the following disclaimer.
! 11: .\" 2. Redistributions in binary form must reproduce the above copyright
! 12: .\" notice, this list of conditions and the following disclaimer in the
! 13: .\" documentation and/or other materials provided with the distribution.
! 14: .\"
! 15: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
! 16: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
! 17: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
! 18: .\" IN NO EVENT SHALL THE AUTHOR OR HIS RELATIVES BE LIABLE FOR ANY DIRECT,
! 19: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
! 20: .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
! 21: .\" SERVICES; LOSS OF MIND, USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 22: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
! 23: .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
! 24: .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
! 25: .\" THE POSSIBILITY OF SUCH DAMAGE.
! 26: .\"
! 27: .\"
! 28: .Dd $Mdocdate: May 31 2007 $
! 29: .Dt BOOT 8 i386
! 30: .Os
! 31: .Sh NAME
! 32: .Nm boot ,
! 33: .Nm boot.conf
! 34: .Nd
! 35: i386-specific second-stage bootstrap
! 36: .Sh DESCRIPTION
! 37: The main purpose of this program is to load the system kernel while dealing
! 38: with the downfalls of the PC BIOS architecture.
! 39: .Pp
! 40: As described in
! 41: .Xr boot_i386 8 ,
! 42: this program is loaded by the
! 43: .Xr biosboot 8
! 44: primary bootstrap loader and provides a convenient way to load the kernel.
! 45: This program acts as an enhanced boot monitor for PC systems, providing
! 46: a common interface for the kernel to start from.
! 47: .Pp
! 48: Basic operations include:
! 49: .Pp
! 50: .Bl -bullet -compact
! 51: .It
! 52: Detecting and switching between multiple consoles.
! 53: .It
! 54: Loading kernels from any device supported by your system BIOS.
! 55: .It
! 56: Loading kernels compressed by
! 57: .Xr gzip 1 .
! 58: .It
! 59: Passing system parameters queried from the BIOS to the kernel.
! 60: .It
! 61: Providing an interactive command line.
! 62: .El
! 63: .Pp
! 64: The sequence of its operation is as follows: initialization,
! 65: parsing the configuration file, then an interactive command line.
! 66: While at the command line you have 5 seconds to type any commands, if needed.
! 67: If time expires, the kernel will be loaded according to
! 68: the current variable settings (see the
! 69: .Nm set
! 70: command).
! 71: Each time a kernel load fails, the timeout is increased by one second.
! 72: The sequence of
! 73: .Nm
! 74: operations is as follows:
! 75: .Bl -enum
! 76: .It
! 77: Set up a protected mode environment which catches and reports processor
! 78: exceptions and provides a simple protected-mode BIOS interface.
! 79: .It
! 80: Probe for console devices, which includes the (default) PC VGA+Keyboard
! 81: console
! 82: .Pq Li pc0
! 83: and up to four serial consoles
! 84: .Pf ( Li com0
! 85: through
! 86: .Li com3 )
! 87: connected to the serial ports.
! 88: Display messages to the default console about the devices found.
! 89: .It
! 90: Detect memory.
! 91: Conventional memory is detected by querying the BIOS.
! 92: Extended memory is detected by probing page-by-page through the address
! 93: space, rather than asking the BIOS; many BIOS's cannot report larger than
! 94: 64M of memory.
! 95: All memory found is reported to the default console device.
! 96: .It
! 97: Probe for APM support in the BIOS.
! 98: Display a message if support is present.
! 99: .It
! 100: If the file
! 101: .Pa /etc/boot.conf
! 102: exists on the filesystem
! 103: .Nm
! 104: was loaded from, open and parse it.
! 105: This file may contain any commands
! 106: .Nm
! 107: accepts at the interactive prompt.
! 108: Though default settings usually suffice, they can be changed here.
! 109: .Pp
! 110: .Pa boot.conf
! 111: processing can be skipped by holding down either Control key as
! 112: .Nm
! 113: starts.
! 114: .It
! 115: The header line
! 116: .Pp
! 117: .Dl >> OpenBSD/i386 BOOT [x.xx]
! 118: .Pp
! 119: is displayed to the active console, where
! 120: .Ar x.xx
! 121: is the version number of the
! 122: .Nm
! 123: program, followed by the
! 124: .Pp
! 125: .Dl boot>
! 126: .Pp
! 127: prompt, which means you are in interactive mode and may enter commands.
! 128: If you do not,
! 129: .Nm
! 130: will proceed to load the kernel with the current parameters after the
! 131: timeout period has expired.
! 132: .El
! 133: .Pp
! 134: By default,
! 135: .Nm
! 136: attempts to load the kernel executable
! 137: .Pa /bsd .
! 138: If it fails to find the kernel and no alternative kernel image has
! 139: been specified, the system will be unable to boot.
! 140: .Sh COMMANDS
! 141: The following commands are accepted at the
! 142: .Nm
! 143: prompt:
! 144: .Bl -tag -width shorten
! 145: .It boot Op Ar image Op Fl acds
! 146: Boots the kernel image specified by
! 147: .Ar image
! 148: with any options given.
! 149: Image specification consists of a pair
! 150: .Ar device : Ns Ar filename ;
! 151: either or both can be omitted (`:' is not needed if both are omitted),
! 152: in which case values from
! 153: .Nm
! 154: variables will be used.
! 155: .Pp
! 156: When selecting the
! 157: .Ar device
! 158: to boot from,
! 159: .Nm
! 160: makes no distinction between SCSI and IDE type drives;
! 161: they are detected as
! 162: .Sq hd
! 163: devices.
! 164: Therefore, to boot kernel
! 165: .Pa /bsd
! 166: from slice
! 167: .Sq a
! 168: on the first hard drive
! 169: .Pq irrespective of device type ,
! 170: specify
! 171: .Dq boot hd0a:/bsd .
! 172: .Bl -tag -width _a_
! 173: .It Fl a
! 174: Causes the kernel to ask for the
! 175: .Nm root
! 176: device to use.
! 177: .It Fl c
! 178: Causes the kernel to go into
! 179: .Xr boot_config 8
! 180: before performing
! 181: .Xr autoconf 4
! 182: procedures.
! 183: .It Fl d
! 184: Causes the kernel to drop into
! 185: .Xr ddb 4
! 186: at the earliest convenient point.
! 187: .It Fl s
! 188: Causes the kernel to boot single-user.
! 189: .El
! 190: .It echo Op Ar args
! 191: Displays
! 192: .Ar args
! 193: on the console device.
! 194: .It help
! 195: Prints a list of available commands and machine dependent
! 196: commands, if any.
! 197: .It machine Op Ar command
! 198: Issues machine-dependent commands.
! 199: These are defined for i386 architecture:
! 200: .Bl -tag -width diskinfo
! 201: .It Nm diskinfo
! 202: Prints a list of hard disks installed on your system including:
! 203: BIOS device number, and the BIOS geometry.
! 204: .It Nm memory
! 205: If used without any arguments, this command will print out
! 206: the memory configuration as determined through BIOS routines.
! 207: Otherwise the arguments specify how to modify the
! 208: memory configuration.
! 209: They take the form of:
! 210: .Pp
! 211: .Dl [+-]<size>@<address>
! 212: .Pp
! 213: Meaning to add(+) or exempt(-) the amount of memory specified by
! 214: .Ar <size>
! 215: at the location specified by
! 216: .Ar <address> .
! 217: Both size and base address can be specified as octal,
! 218: decimal, or hexadecimal numbers, as accepted by the
! 219: .Xr strtoul 3
! 220: routine.
! 221: .Pp
! 222: Memory segments are not required to be adjacent to each other;
! 223: the only requirement is that there is real physical memory under
! 224: the range added.
! 225: The following example
! 226: adds 32M of memory right after the first 16M:
! 227: .Bd -unfilled -offset indent
! 228: machine mem +0x2000000@0x1000000
! 229: .Ed
! 230: .Pp
! 231: Another useful command is to withdraw a range
! 232: of memory from OS usage (it may have been wrongfully reported as
! 233: useful by the BIOS).
! 234: This example
! 235: effectively excludes the 15\(en16M range from the map of useful memory:
! 236: .Bd -unfilled -offset indent
! 237: machine mem -0x100000@0xf00000
! 238: .Ed
! 239: .It Nm regs
! 240: Prints contents of processor registers if compiled with
! 241: .Em DEBUG .
! 242: .El
! 243: .It ls Op Ar directory
! 244: Prints contents of the specified
! 245: .Ar directory
! 246: in long format including: attributes and file type, owner, group,
! 247: size, filename.
! 248: .It reboot
! 249: Reboots the machine by initiating a warm boot procedure.
! 250: .It set Op Ar varname Op Ar value
! 251: If invoked without arguments, prints a list of variables and their values.
! 252: If only
! 253: .Ar varname
! 254: is specified, displays contents of that variable.
! 255: If
! 256: .Ar varname
! 257: and
! 258: .Ar value
! 259: are both specified, sets that variable to the given value.
! 260: Variables include:
! 261: .Pp
! 262: .Bl -tag -compact -width boothow
! 263: .It Nm addr
! 264: Address at which to load the kernel.
! 265: .It Nm debug
! 266: Debug flag if
! 267: .Nm
! 268: was compiled with DEBUG defined.
! 269: .It Nm device
! 270: Boot device name (e.g.,
! 271: .Li fd0a ,
! 272: .Li hd0a ) .
! 273: .It Nm howto
! 274: Options to pass to the loaded kernel.
! 275: .It Nm image
! 276: File name containing the kernel image.
! 277: .It Nm timeout
! 278: Number of seconds boot will wait for human intervention before
! 279: booting the default kernel image.
! 280: .It Nm tty
! 281: Active console device name (e.g.,
! 282: .Li com0 ,
! 283: .Li com1 ,
! 284: .Li pc0 ) .
! 285: .El
! 286: .It stty Op Ar device Op Ar speed
! 287: Displays or sets the
! 288: .Ar speed
! 289: for a console
! 290: .Ar device .
! 291: If changing the baudrate for the currently active console,
! 292: .Nm
! 293: offers you five seconds of grace time before committing the change
! 294: to allow you to change your terminal's speed to match.
! 295: If changing speed
! 296: .Em not
! 297: for the active console, the baudrate is set for the
! 298: .Em next
! 299: time you switch to a serial console.
! 300: The baudrate value is not used for the
! 301: .Li pc0
! 302: console.
! 303: .Pp
! 304: The default baudrate is 9600bps.
! 305: .It time
! 306: Displays system time and date.
! 307: .El
! 308: .Sh FILES
! 309: .Bl -tag -width /usr/mdec/biosbootxx -compact
! 310: .It Pa /usr/mdec/biosboot
! 311: first stage bootstrap
! 312: .It Pa /usr/mdec/pxeboot
! 313: PXE bootstrap
! 314: .It Pa /boot
! 315: system bootstrap
! 316: .It Pa /etc/boot.conf
! 317: system bootstrap's startup file
! 318: .It Pa /bsd
! 319: kernel image
! 320: .It Pa /bsd.mp
! 321: kernel image for multiprocessor machines
! 322: .It Pa /bsd.rd
! 323: kernel image for installation/recovery
! 324: .El
! 325: .Sh EXAMPLES
! 326: Boot the default kernel:
! 327: .Pp
! 328: .Dl boot> boot
! 329: .Pp
! 330: Remove the 5 second pause at boot-time permanently, causing
! 331: .Nm
! 332: to load the kernel immediately without prompting:
! 333: .Pp
! 334: .Dl # echo \&"boot\&" > /etc/boot.conf
! 335: .Pp
! 336: Use serial console.
! 337: A null modem cable should connect the specified serial port to a terminal.
! 338: Useful for debugging.
! 339: .Pp
! 340: .Dl boot> set tty com0
! 341: .Pp
! 342: Invoke the serial console at every boot:
! 343: .Pp
! 344: .Dl # echo \&"set tty com0\&" > /etc/boot.conf
! 345: .Pp
! 346: Boot the kernel named
! 347: .Pa /bsd
! 348: from the second hard disk in
! 349: .Dq User Kernel Configuration
! 350: mode (see
! 351: .Xr boot_config 8 ) .
! 352: This mechanism allows for the explicit enabling and disabling of devices
! 353: during the current boot sequence, as well as the modification
! 354: of device parameters.
! 355: Once booted, such changes can be made permanent by using
! 356: .Xr config 8 Ns 's
! 357: .Fl e
! 358: option.
! 359: .Pp
! 360: .Dl boot> boot hd1a:/bsd -c
! 361: .Sh SEE ALSO
! 362: .Xr gzip 1 ,
! 363: .Xr autoconf 4 ,
! 364: .Xr ddb 4 ,
! 365: .Xr biosboot 8 ,
! 366: .Xr boot_config 8 ,
! 367: .Xr boot_i386 8 ,
! 368: .Xr fdisk 8 ,
! 369: .Xr installboot 8 ,
! 370: .Xr pxeboot 8 ,
! 371: .Xr reboot 8
! 372: .Pp
! 373: RFC 1950 describes the zlib library interface.
! 374: .Pp
! 375: The official home page for the version of zlib used in this
! 376: operating system is at http://www.gzip.org/zlib/.
! 377: .Sh HISTORY
! 378: This program was written by Michael Shalayeff for
! 379: .Ox 2.1 .
CVSweb