From 6e3114911c65641046d2bda1c2fda8239ab7c8a1 Mon Sep 17 00:00:00 2001 From: Uwe Stuehler Date: Tue, 19 Apr 2005 23:09:41 +0000 Subject: describe the zaurus boot(8) program; review/suggestions by jmc@ --- sys/arch/zaurus/stand/zboot/Makefile | 6 +- sys/arch/zaurus/stand/zboot/boot.8 | 364 +++++++++++++++++++++++++++++++++++ 2 files changed, 368 insertions(+), 2 deletions(-) create mode 100644 sys/arch/zaurus/stand/zboot/boot.8 (limited to 'sys/arch/zaurus') 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. -- cgit v1.2.3