describe the zaurus boot(8) program; review/suggestions by jmc@

2 files changed, 368 insertions, 2 deletions

diff --git a/sys/arch/zaurus/stand/zboot/Makefile b/sys/arch/zaurus/stand/zboot/Makefile
index b2bc0487cad..c90bd093265 100644
--- a/sys/arch/zaurus/stand/zboot/Makefile
+++ b/sys/arch/zaurus/stand/zboot/Makefile
@@ -1,5 +1,7 @@
-#MAN=	zboot.8
-NOMAN=
+#	$OpenBSD: Makefile,v 1.3 2005/04/19 23:09:40 uwe Exp $
+
+MAN=	boot.8
+MLINKS=	boot.8 boot.conf.8
 
 .if ${MACHINE} == "zaurus"
 PROG=	zboot
diff --git a/sys/arch/zaurus/stand/zboot/boot.8 b/sys/arch/zaurus/stand/zboot/boot.8
new file mode 100644
index 00000000000..b8f9fefeb02
--- /dev/null
+++ b/sys/arch/zaurus/stand/zboot/boot.8
@@ -0,0 +1,364 @@
+.\"	$OpenBSD: boot.8,v 1.1 2005/04/19 23:09:40 uwe Exp $
+.\"
+.\" Copyright (c) 1997-2001 Michael Shalayeff
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR OR HIS RELATIVES BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF MIND, USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\"
+.Dd September 1, 1997
+.Dt BOOT 8 zaurus
+.Os
+.Sh NAME
+.Nm boot ,
+.Nm boot.conf
+.Nd
+zaurus-specific second-stage bootstrap
+.Sh DESCRIPTION
+The main purpose of this program is to load the system kernel while dealing
+with the peculiarities of the zaurus machine.
+.Pp
+As described in
+.Xr boot_zaurus 8 ,
+this program is loaded by the primary bootstrap loader and provides a
+convenient way to load the kernel.
+This program acts as an enhanced boot monitor for zaurus systems, providing
+a common interface for the kernel to start from.
+.Pp
+Basic operations include:
+.Pp
+.Bl -bullet -compact
+.It
+Detecting and switching between multiple consoles.
+.It
+Loading kernels from any device supported by the primary bootstrap loader.
+.\" .It
+.\" Loading kernels compressed by
+.\" .Xr gzip 1 .
+.It
+Passing system parameters queried from the primary bootstrap loader to the
+kernel.
+.It
+Providing an interactive command line.
+.El
+.Pp
+The sequence of its operation is as follows: initialization,
+parsing the configuration file, then an interactive command line.
+While at the command line you have 5 seconds to type any commands, if needed.
+If time expires, the kernel will be loaded according to
+the current variable settings (see the
+.Nm set
+command).
+Each time a kernel load fails, the timeout is increased by one second.
+The sequence of
+.Nm
+operations is as follows:
+.Bl -enum
+.\" .It
+.\" Probe for console devices, which includes the (default) PC VGA+Keyboard
+.\" console
+.\" .Pq Li pc0
+.\" and up to four serial consoles
+.\" .Pf ( Li com0
+.\" through
+.\" .Li com3 )
+.\" connected to the serial ports.
+.\" Display messages to the default console about the devices found.
+.\" .It
+.\" Detect memory.
+.\" Conventional memory is detected by querying the BIOS.
+.\" Extended memory is detected by probing page-by-page through the address
+.\" space, rather than asking the BIOS; many BIOS's cannot report larger than
+.\" 64M of memory.
+.\" All memory found is reported to the default console device.
+.It
+Probe for disk devices, and select the first disk with an i386-compatible
+MBR and a valid
+.Ox
+primary partition.
+.It
+If the file
+.Pa /etc/boot.conf
+exists on the root filesystem on the selected disk, open and parse it.
+This file may contain any commands
+.Nm
+accepts at the interactive prompt.
+Though default settings usually suffice, they can be changed here.
+.It
+The header line
+.Pp
+.Dl >> OpenBSD/zaurus BOOT [x.xx]
+.Pp
+is displayed to the active console, where
+.Ar x.xx
+is the version number of the
+.Nm
+program, followed by the
+.Pp
+.Dl boot>
+.Pp
+prompt, which means you are in interactive mode and may enter commands.
+If you do not,
+.Nm
+will proceed to load the kernel with the current parameters after the
+timeout period has expired.
+.El
+.Pp
+By default,
+.Nm
+attempts to load the kernel executable
+.Pa /bsd .
+If that fails, it will attempt to load
+.Pa /obsd
+and then
+.Pa /bsd.old .
+If it fails to find any of these files,
+and no alternative kernel image has been specified,
+the system will be unable to boot.
+.Sh COMMANDS
+The following commands are accepted at the
+.Nm
+prompt:
+.Bl -tag -width shorten
+.It boot Op Ar image Op Fl acds
+Boots the kernel image specified by
+.Ar image
+with any options given.
+Image specification consists of a pair
+.Ar device : Ns Ar filename ;
+either or both can be omitted (`:' is not needed if both are omitted),
+in which case values from
+.Nm
+variables will be used.
+.Pp
+When selecting the
+.Ar device
+to boot from,
+.Nm
+.\" makes no distinction between SCSI and IDE type drives;
+.\" they are detected as
+.\" .Sq hd
+.\" devices.
+.\" Therefore, to boot kernel
+.\" .Pa /bsd
+.\" from slice
+.\" .Sq a
+.\" on the first hard drive
+.\" .Pq irrespective of device type ,
+.\" specify
+.\" .Dq boot hd0a:/bsd .
+makes no distinction between the type of drives;
+the device name is passed directly to the primary bootstrap loader.
+Therefore, to boot kernel
+.Pa /bsd
+from slice
+.Sq a
+in the fourth primary partition on the first hard drive, specify
+.Dq boot /dev/hda4:/bsd .
+.Pp
+.Em Note:
+Normally, the internal hard disk is designated by the
+.Ar device
+prefix
+.Sq /dev/hda .
+If a CF hard disk is present in the socket when the system starts,
+the internal hard disk is instead designated by the prefix
+.Sq /dev/hdc ,
+and
+.Sq /dev/hda
+will access the CF hard disk.
+See also
+.Sx BUGS ,
+below.
+.Bl -tag -width _a_
+.It Fl a
+Causes the kernel to ask for the
+.Nm root
+device to use.
+.It Fl c
+Causes the kernel to go into
+.Xr boot_config 8
+before performing
+.Xr autoconf 4
+procedures.
+.It Fl d
+Causes the kernel to drop into
+.Xr ddb 4
+at the earliest convenient point.
+.It Fl s
+Causes the kernel to boot single-user.
+.El
+.It clear
+Clears the console screen.
+This is useful if your bootstrap console doesn't scroll the screen
+automatically when the cursor is in the bottom line.
+.It echo Op Ar args
+Displays
+.Ar args
+on the console device.
+.It help
+Prints a list of available commands and machine dependent
+commands, if any.
+.It ls Op Ar directory
+Prints contents of the specified
+.Ar directory
+in long format including: attributes and file type, owner, group,
+size, filename.
+.It reboot
+.\" Reboots the machine by initiating a warm boot procedure.
+Returns control to the primary bootstrap loader.
+.It set Op Ar varname Op Ar value
+If invoked without arguments, prints a list of variables and their values.
+If only
+.Ar varname
+is specified, displays contents of that variable.
+If
+.Ar varname
+and
+.Ar value
+are both specified, sets that variable to the given value.
+Variables include:
+.Pp
+.Bl -tag -compact -width boothow
+.It Nm addr
+Address at which to load the kernel.
+.It Nm debug
+Debug flag if
+.Nm
+was compiled with DEBUG defined.
+.It Nm device
+Boot device name (e.g.,
+.\" .Li fd0a ,
+.\" .Li hd0a ) .
+.Li /dev/hda4 ,
+.Li /dev/hdc1 ) .
+.It Nm howto
+Options to pass to the loaded kernel.
+.It Nm image
+File name containing the kernel image.
+.It Nm timeout
+Number of seconds boot will wait for human intervention before
+booting the default kernel image.
+.It Nm tty
+Active console device name (e.g.,
+.Li cn0 ,
+.Li com0 ,
+.Li com1 ) .
+.El
+.It stty Op Ar device Op Ar speed
+Displays or sets the
+.Ar speed
+for a console
+.Ar device .
+If changing the baudrate for the currently active console,
+.Nm
+offers you five seconds of grace time before committing the change
+to allow you to change your terminal's speed to match.
+If changing speed
+.Em not
+for the active console, the baudrate is set for the
+.Em next
+time you switch to a serial console.
+.Pp
+The default baudrate is 9600bps.
+.It time
+Displays system time and date.
+.El
+.Sh FILES
+.Bl -tag -width /usr/mdec/zbsdmod.o -compact
+.It Pa /usr/mdec/zbsdmod.o
+kernel module for the primary bootstrap loader that must be
+loaded before the system bootstrap
+.It Pa /usr/mdec/zboot
+system bootstrap
+.It Pa /etc/boot.conf
+system bootstrap's startup file
+.It Pa /bsd
+kernel image
+.El
+.Sh EXAMPLES
+Boot the default kernel:
+.Pp
+.Dl boot> boot
+.Pp
+Remove the 5 second pause at boot-time permanently, causing
+.Nm
+to load the kernel immediately without prompting:
+.Pp
+.Dl # echo \&"boot\&" > /etc/boot.conf
+.Pp
+Use serial console.
+A null modem cable should connect the specified serial port to a terminal.
+Useful for debugging.
+.Pp
+.Dl boot> set tty com0
+.Pp
+Invoke the serial console at every boot:
+.Pp
+.Dl # echo \&"set tty com0\&" > /etc/boot.conf
+.Pp
+Boot the kernel named
+.Pa /bsd
+from the fourth primary partition on the first hard disk in
+.Dq User Kernel Configuration
+mode (see
+.Xr boot_config 8 ) .
+This mechanism allows for the explicit enabling and disabling of devices
+during the current boot sequence, as well as the modification
+of device parameters.
+Once booted, such changes can be made permanent by using
+.Xr config 8 Ns 's
+.Fl e
+option.
+.Pp
+.\" .Dl boot> boot hd1a:/bsd -c
+.Dl boot> boot /dev/hda4:/bsd -c
+.Sh SEE ALSO
+.\" .Xr gzip 1 ,
+.Xr autoconf 4 ,
+.Xr ddb 4 ,
+.Xr boot_config 8 ,
+.Xr boot_zaurus 8 ,
+.Xr fdisk 8 ,
+.\" .Xr installboot 8 ,
+.Xr reboot 8
+.\" .Pp
+.\" RFC 1950 describes the zlib library interface.
+.\" .Pp
+.\" The official home page for the version of zlib used in this
+.\" operating system is at http://www.gzip.org/zlib/.
+.Sh HISTORY
+This program was written by Michael Shalayeff for
+.Ox 2.1 ,
+and adapted to zaurus by Uwe Stuehler for
+.Ox 3.7 .
+.Sh BUGS
+Alternative console devices are not probed for and can not be
+selected.
+.Pp
+Non-IDE disks do not get selected for loading /etc/boot.conf or
+the kernel from them.
+.Pp
+The
+.Nm boot
+command should accept abstract disk device names instead of
+just forwarding the device name to the primary bootstrap.