Annotation of sys/arch/zaurus/stand/zboot/boot.8, Revision 1.1
1.1 ! nbrk 1: .\" $OpenBSD: boot.8,v 1.8 2007/05/31 19:20:05 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 zaurus
! 30: .Os
! 31: .Sh NAME
! 32: .Nm boot ,
! 33: .Nm boot.conf
! 34: .Nd
! 35: zaurus-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 peculiarities of the zaurus machine.
! 39: .Pp
! 40: As described in
! 41: .Xr boot_zaurus 8 ,
! 42: this program is loaded by the primary bootstrap loader and provides a
! 43: convenient way to load the kernel.
! 44: This program acts as an enhanced boot monitor for zaurus systems, providing
! 45: a common interface for the kernel to start from.
! 46: .Pp
! 47: Basic operations include:
! 48: .Pp
! 49: .Bl -bullet -compact
! 50: .It
! 51: Detecting and switching between multiple consoles.
! 52: .It
! 53: Loading kernels from any device supported by the primary bootstrap loader.
! 54: .\" .It
! 55: .\" Loading kernels compressed by
! 56: .\" .Xr gzip 1 .
! 57: .It
! 58: Passing system parameters queried from the primary bootstrap loader to the
! 59: 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: Probe for console devices, which includes the (default) LCD+Keyboard
! 78: console
! 79: .Pq Li cn0
! 80: and up to three serial consoles
! 81: .Pf ( Li com0
! 82: through
! 83: .Li com2 )
! 84: connected to the serial ports.
! 85: Display messages to the default console about the devices found.
! 86: .\" .It
! 87: .\" Detect memory.
! 88: .\" Conventional memory is detected by querying the BIOS.
! 89: .\" Extended memory is detected by probing page-by-page through the address
! 90: .\" space, rather than asking the BIOS; many BIOS's cannot report larger than
! 91: .\" 64M of memory.
! 92: .\" All memory found is reported to the default console device.
! 93: .It
! 94: Probe for disk devices, and select the first disk with an i386-compatible
! 95: MBR and a valid
! 96: .Ox
! 97: primary partition.
! 98: .It
! 99: If the file
! 100: .Pa /etc/boot.conf
! 101: exists on the root filesystem on the selected disk, open and parse it.
! 102: This file may contain any commands
! 103: .Nm
! 104: accepts at the interactive prompt.
! 105: Though default settings usually suffice, they can be changed here.
! 106: .It
! 107: The header line
! 108: .Pp
! 109: .Dl >> OpenBSD/zaurus BOOT [x.xx]
! 110: .Pp
! 111: is displayed to the active console, where
! 112: .Ar x.xx
! 113: is the version number of the
! 114: .Nm
! 115: program, followed by the
! 116: .Pp
! 117: .Dl boot>
! 118: .Pp
! 119: prompt, which means you are in interactive mode and may enter commands.
! 120: If you do not,
! 121: .Nm
! 122: will proceed to load the kernel with the current parameters after the
! 123: timeout period has expired.
! 124: .El
! 125: .Pp
! 126: By default,
! 127: .Nm
! 128: attempts to load the kernel executable
! 129: .Pa /bsd .
! 130: If it fails to find the kernel and no alternative kernel image has
! 131: been specified, the system will be unable to boot.
! 132: .Sh COMMANDS
! 133: The following commands are accepted at the
! 134: .Nm
! 135: prompt:
! 136: .Bl -tag -width shorten
! 137: .It boot Op Ar image Op Fl acds
! 138: Boots the kernel image specified by
! 139: .Ar image
! 140: with any options given.
! 141: Image specification consists of a pair
! 142: .Ar device : Ns Ar filename ;
! 143: either or both can be omitted (`:' is not needed if both are omitted),
! 144: in which case values from
! 145: .Nm
! 146: variables will be used.
! 147: .Pp
! 148: When selecting the
! 149: .Ar device
! 150: to boot from,
! 151: .Nm
! 152: makes no distinction between SCSI and IDE type drives;
! 153: they are detected as
! 154: .Sq hd
! 155: devices.
! 156: Therefore, to boot kernel
! 157: .Pa /bsd
! 158: from slice
! 159: .Sq a
! 160: on the first hard drive
! 161: .Pq irrespective of device type ,
! 162: specify
! 163: .Dq boot hd0a:/bsd .
! 164: .Pp
! 165: .Em Note:
! 166: Normally, the internal hard disk is designated by the
! 167: .Ar device
! 168: name
! 169: .Sq hd0 .
! 170: If a CF hard disk is present in the socket when the system starts,
! 171: the internal hard disk is instead designated by the prefix
! 172: .Sq hd1 ,
! 173: and
! 174: .Sq hd0
! 175: will access the CF hard disk.
! 176: .Bl -tag -width _a_
! 177: .It Fl a
! 178: Causes the kernel to ask for the
! 179: .Nm root
! 180: device to use.
! 181: .It Fl c
! 182: Causes the kernel to go into
! 183: .Xr boot_config 8
! 184: before performing
! 185: .Xr autoconf 4
! 186: procedures.
! 187: .It Fl d
! 188: Causes the kernel to drop into
! 189: .Xr ddb 4
! 190: at the earliest convenient point.
! 191: .It Fl s
! 192: Causes the kernel to boot single-user.
! 193: .El
! 194: .It clear
! 195: Clears the console screen.
! 196: This is useful if your bootstrap console doesn't scroll the screen
! 197: automatically when the cursor is in the bottom line.
! 198: .It echo Op Ar args
! 199: Displays
! 200: .Ar args
! 201: on the console device.
! 202: .It help
! 203: Prints a list of available commands and machine dependent
! 204: commands, if any.
! 205: .It ls Op Ar directory
! 206: Prints contents of the specified
! 207: .Ar directory
! 208: in long format including: attributes and file type, owner, group,
! 209: size, filename.
! 210: .It reboot
! 211: .\" Reboots the machine by initiating a warm boot procedure.
! 212: Returns control to the primary bootstrap loader.
! 213: .It set Op Ar varname Op Ar value
! 214: If invoked without arguments, prints a list of variables and their values.
! 215: If only
! 216: .Ar varname
! 217: is specified, displays contents of that variable.
! 218: If
! 219: .Ar varname
! 220: and
! 221: .Ar value
! 222: are both specified, sets that variable to the given value.
! 223: Variables include:
! 224: .Pp
! 225: .Bl -tag -compact -width boothow
! 226: .It Nm addr
! 227: Address at which to load the kernel.
! 228: .It Nm debug
! 229: Debug flag if
! 230: .Nm
! 231: was compiled with DEBUG defined.
! 232: .It Nm device
! 233: Boot device name (e.g.,
! 234: .\" .Li fd0a ,
! 235: .Li hd0a ) .
! 236: .It Nm howto
! 237: Options to pass to the loaded kernel.
! 238: .It Nm image
! 239: File name containing the kernel image.
! 240: .It Nm timeout
! 241: Number of seconds boot will wait for human intervention before
! 242: booting the default kernel image.
! 243: .It Nm tty
! 244: Active console device name (e.g.,
! 245: .Li cn0 ,
! 246: .Li com0 ,
! 247: .Li com1 ) .
! 248: .El
! 249: .It stty Op Ar device Op Ar speed
! 250: Displays or sets the
! 251: .Ar speed
! 252: for a console
! 253: .Ar device .
! 254: If changing the baudrate for the currently active console,
! 255: .Nm
! 256: offers you five seconds of grace time before committing the change
! 257: to allow you to change your terminal's speed to match.
! 258: If changing speed
! 259: .Em not
! 260: for the active console, the baudrate is set for the
! 261: .Em next
! 262: time you switch to a serial console.
! 263: .Pp
! 264: The default baudrate is 9600bps.
! 265: .It time
! 266: Displays system time and date.
! 267: .El
! 268: .Sh UPDATING BOOTBLOCKS
! 269: Since the bootblocks actually live in a Linux flash filesystem, a
! 270: rather obtuse method must currently be used to upgrade them.
! 271: .Pp
! 272: .Bl -enum -offset indent -compact
! 273: .It
! 274: Place
! 275: .Pa zboot
! 276: and
! 277: .Pa zbsdmod.o
! 278: onto an MS-DOS filesystem on a CF card, and then insert into the Zaurus.
! 279: .It
! 280: Remove power from the Zaurus.
! 281: .It
! 282: Unplug the battery.
! 283: .It
! 284: Start holding down the
! 285: .Sq b
! 286: and
! 287: .Sq d
! 288: keys.
! 289: .It
! 290: Wait 30 seconds, then re-insert the battery and power up the Zaurus.
! 291: .It
! 292: When you see text start to appear on the Zaurus, release the
! 293: .Sq b
! 294: and
! 295: .Sq d
! 296: keys.
! 297: .It
! 298: Login as root and perform the following steps:
! 299: .Bd -literal -offset indent
! 300: # mount /dev/mtdblock2 /tmp
! 301: # cp /mnt/cf/z* /tmp/home/etc/rc.d
! 302: # reboot
! 303: .Ed
! 304: .Pp
! 305: An SD card with an MS-DOS filesystem may be used instead, in which case
! 306: the Linux pathname will be
! 307: .Pa /mnt/card
! 308: instead of
! 309: .Pa /mnt/cf .
! 310: .El
! 311: .Sh FILES
! 312: .Bl -tag -width /usr/mdec/zbsdmod.o -compact
! 313: .It Pa /usr/mdec/zbsdmod.o
! 314: kernel module for the primary bootstrap loader that must be
! 315: loaded before the system bootstrap
! 316: .It Pa /usr/mdec/zboot
! 317: system bootstrap
! 318: .It Pa /etc/boot.conf
! 319: system bootstrap's startup file
! 320: .It Pa /bsd
! 321: kernel image
! 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 boot_config 8 ,
! 366: .Xr boot_zaurus 8 ,
! 367: .Xr fdisk 8 ,
! 368: .\" .Xr installboot 8 ,
! 369: .Xr reboot 8
! 370: .\" .Pp
! 371: .\" RFC 1950 describes the zlib library interface.
! 372: .\" .Pp
! 373: .\" The official home page for the version of zlib used in this
! 374: .\" operating system is at http://www.gzip.org/zlib/.
! 375: .Sh HISTORY
! 376: This program was written by Michael Shalayeff for
! 377: .Ox 2.1 ,
! 378: and adapted to zaurus by Uwe Stuehler for
! 379: .Ox 3.7 .
! 380: .Sh BUGS
! 381: Non-IDE disks can not be used to load /etc/boot.conf or
! 382: the kernel from them.
CVSweb