[src/trunk]: src/share/man/man8/man8.macppc Add ofwboot man page.

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/6b714e27f53a
branches:  trunk
changeset: 513936:6b714e27f53a
user:      wiz <wiz%NetBSD.org@localhost>
date:      Sat Aug 18 00:00:34 2001 +0000

description:
Add ofwboot man page.
Written by Makoto Fujiwara, and improved upon by Michael Wolfson and myself.

diffstat:

 share/man/man8/man8.macppc/Makefile  |    5 +-
 share/man/man8/man8.macppc/ofwboot.8 |  386 +++++++++++++++++++++++++++++++++++
 2 files changed, 389 insertions(+), 2 deletions(-)

diffs (truncated from 404 to 300 lines):

diff -r e7c7f70172c5 -r 6b714e27f53a share/man/man8/man8.macppc/Makefile
--- a/share/man/man8/man8.macppc/Makefile       Fri Aug 17 23:30:32 2001 +0000
+++ b/share/man/man8/man8.macppc/Makefile       Sat Aug 18 00:00:34 2001 +0000
@@ -1,7 +1,8 @@
-#      $NetBSD: Makefile,v 1.2 2001/04/16 08:24:31 wiz Exp $
+#      $NetBSD: Makefile,v 1.3 2001/08/18 00:00:34 wiz Exp $
 
-MAN=   MAKEDEV.8
+MAN=   MAKEDEV.8 ofwboot.8
 MLINKS=        MAKEDEV.8 makedev.8
+MLINKS+=       ofwboot.8 ofwboot.elf.8 ofwboot.8 ofwboot.xcf.8
 MANSUBDIR=/macppc
 
 .include <bsd.man.mk>
diff -r e7c7f70172c5 -r 6b714e27f53a share/man/man8/man8.macppc/ofwboot.8
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man8/man8.macppc/ofwboot.8      Sat Aug 18 00:00:34 2001 +0000
@@ -0,0 +1,386 @@
+.\"    $NetBSD: ofwboot.8,v 1.1 2001/08/18 00:00:34 wiz Exp $
+.\"
+.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Makoto Fujiwara, Thomas Klausner, and Michael Wolfson.
+.\"
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``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 FOUNDATION OR CONTRIBUTORS
+.\" 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 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 August 18, 2001
+.Dt OFWBOOT 8 macppc
+.Os
+.Sh NAME
+.Nm ofwboot ,
+.Nm ofwboot.elf ,
+.Nm ofwboot.xcf
+.Nd Open Firmware boot command
+.Sh SYNOPSIS
+.Nm ofwboot
+.Sh DESCRIPTION
+Open Firmware is a FORTH-like command interpreter started by the BootROM after
+the power-on self test (POST).
+This command interpreter allows the user flexibility in choosing how their
+machine boots an operating system.
+.Nx
+uses Open Firmware to initialize
+many of the devices in a system and uses it to load the primary bootloader,
+.Nm ofwboot .
+.Pp
+The information in this man page should only serve as a guideline for users.
+.Tn Apple
+has made many revisions to Open Firmware, and the earlier versions
+had many problems and inconsistencies.  You may find that a boot command
+that works on one model will not work on another.
+.Pp
+In this man page, only one Open Firmware command will be described,
+.Ic boot ,
+because it is used to pass arguments to
+.Nm ofwboot .
+The Open Firmware
+.Ic boot
+command takes up to three arguments:
+.Pp
+.Ic boot
+.Op Ar boot-device Op Ar boot-file
+.Op Ar options
+.Bl -tag -width boot-device -compact
+.It Ar boot-device
+primary bootloader location
+.It Ar boot-file
+kernel location
+.It Ar options
+flags passed to the kernel (see below)
+.El
+.Ss boot-device
+The first argument,
+.Ar boot-device ,
+actually designates the primary bootloader location and its name in the
+form:
+.Dl boot-device:[partition-num],[bootloader-filename]
+A typical example, from a PowerBook (FireWire), is
+.Dl /pci@f2000000/mac-io@17/ata-4@1f000/@0:9,ofwboot.xcf
+.\" XXX: can't use Dq or Pq with : or ,
+Note that colon (`:') delimits the device to the left, and comma (`,')
+separates the boot loader filename from the first part.  For Open Firmware
+versions before 3, the primary bootloader is installed in partition
+.Dq zero ,
+and it is not necessary to specify the bootloader-filename.  For Open Firmware
+version 3, you must specify the bootloader-filename.
+.Pp
+Open Firmware stores aliases to common devices in NVRAM.  In the example
+above,
+.Pa /pci@f2000000/mac-io@17/ata-4@1f000/@0
+is the path on a PowerBook
+(FireWire) to the built-in ATA/100 hard drive.  Use the
+.Ic devalias
+command in Open Firmware to print out a list of common device names on a
+particular model.
+The command above could then be simplified to:
+.Dl hd:9,ofwboot.xcf
+.Pp
+.Ar boot-loader-file-name
+is usually
+.Nm ofwboot.xcf .
+(See also the
+.Sx FILES
+section for further discussion.)
+.Pp
+If omitted, the Open Firmware variable
+.Va boot-device
+is used.
+.Ss boot-file
+It may be necessary to specify the
+.Ar boot-file
+if Open Firmware does not know where to find the kernel.  The default is to
+load the file named
+.Nm netbsd
+on partition
+.Pa Dq a
+from the device used to load the primary bootloader.
+.Pp
+For systems with
+Open Firmware versions less than 3 which are set up using
+.Ic sysinst ,
+the
+.Ar boot-file
+argument is not necessary.  Systems with Open Firmware version 3 may need
+to specify the
+.Ar boot-file .
+.Pp
+The syntax is similar to the
+.Ar boot-device
+argument:
+.Dl [boot-file-device:partition-num/][kernel-name]
+This is a little different, since a kernel-name may be specified without
+listing a boot-file-device and partition-num.  Additionally, a boot-file-device
+and partition-num may need to be specified, while using the default
+kernel-name.
+.Pp
+If no kernel-name is specified, the primary bootloader will try to find
+kernels named either
+.Ar netbsd
+or
+.Ar netbsd.gz
+on the boot-device or (if specified) boot-file-device.
+.Ss options
+Possible options are:
+.Bl -tag -width xxxxx -compact
+.It Fl a
+ask for the boot device
+.It Fl s
+single-user mode boot
+.It Fl d
+debug mode
+.It Ar exit
+exit to Open Firmware after processing arguments
+.El
+.Sh ENVIRONMENT
+If set, the following Open Firmware variables will be used to determine which
+.Ar boot-device
+and
+.Ar boot-file
+Open Firmware should use when booting a system.  If the user specifies
+arguments on the command line, these values are overridden.
+.Bl -tag -width boot-device -compact
+.It Va boot-device
+used as the first argument
+.It Va boot-file
+used as the second argument
+.It Va auto-boot?
+setting this variable to
+.Ar false
+will present the user with an Open Firmware command prompt after power-on
+reset.  A value of
+.Ar true
+will automatically boot the system using the variables
+.Va boot-device
+and
+.Va boot-file .
+(This is not really related to the boot command, but is included for
+completeness.)
+.El
+To restore these variables to their default values, use the
+.Ic set-default
+Open Firmware command:
+.Ic set-default Ar boot-device
+.Sh FILES
+The three files
+.Nm ofwboot ,
+.Nm ofwboot.elf ,
+and
+.Nm ofwboot.xcf
+are the same program, in different executable formats.
+.Bl -tag -width ofwboot.xcf
+.It ofwboot
+.Nm
+is installed via
+.Xr installboot 8
+on systems with Open Firmware versions less than 3.
+It is not necessary to specify this file name, as it is stored in a special
+location on the disk, partition
+.Dq zero .
+For example, the following command might be used to boot from a SCSI device
+with ID 2:
+.Ic "0 >boot Ar scsi-int/sd@2:0" .
+.It ofwboot.xcf
+.Nm ofwboot.xcf
+is in XCOFF format.  This file is used on all Open Firmware 3 systems, and on
+Open Firmware systems prior to 3 when the bootloader is not installed in
+partition
+.Dq zero ,
+such as from an ISO-9660 format CD-ROM.
+.It ofwboot.elf
+.Nm ofwboot.elf
+is in
+.Xr ELF 5
+format and only functions on systems with Open Firmware version 3.  To avoid
+confusion, all users should be using
+.Nm ofwboot.xcf ,
+as
+.Nm ofwboot.elf
+offers no additional functionality.  It is only included for historical
+reasons.
+.It boot.fs
+This 1.44 MB disk image contains everything necessary to boot and install
+.Nx .
+It includes the partition
+.Dq zero
+bootloader
+.Nm ( ofwboot ) ,
+an INSTALL kernel (with limited device drivers), and the
+.Ic sysinst
+utility in a RAM disk.  Since Open Firmware does not care what media
+files are loaded from, only whether they are supported and in the correct
+format, this disk image may be placed on media other than floppy disks, such
+as hard drives or Zip disks.  Use
+.Xr dd 1
+on Unix, or
+.Ic DiskCopy
+on MacOS 9.1 or later, or
+.Ic suntar
+on any MacOS version to copy this image onto the media.
+.It netbsd
+production kernel, using the GENERIC set of devices which supports almost all
+hardware available for this platform.
+.It netbsd_GENERIC_MD.gz
+GENERIC kernel (the same as
+.Ar netbsd ) ,
+with RAM disk and
+.Ic sysinst
+included.
+.It macppcd.iso
+bootable CDROM image for all supported systems.  Usually located at
+.Pa ftp://ftp.netbsd.org/pub/NetBSD/iso/{RELEASE}/macppccd.iso
+.El
+.Sh EXAMPLES
+.Bl -item
+.It
+Boot an Open Firmware 3 system, with
+.Ar netbsd
+installed on partition
+.Pa Dq a :
+.Bd -unfilled
+0 > boot hd:,ofwboot.xcf
+.Ed
+.It
+Boot into single user mode:
+.Bd -unfilled
+0 > boot hd:,ofwboot.xcf netbsd -s
+.Ed
+.It
+Boot from bootable CDROM with Open Firmware 3 or higher:
+.Bd -unfilled
+0 > boot cd:,\eofwboot.xcf netbsd.macppc
+.Ed