.\"	$NetBSD: ofwboot.8,v 1.13.8.1 2019/09/02 16:39:22 martin 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.
.\"
.\" 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
.Dq Pa 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 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 NetBSD-{RELEASE}-macppc.iso
bootable CDROM image for all supported systems.
Usually located at
.Pa ftp://ftp.NetBSD.org/pub/NetBSD/images/{RELEASE}/NetBSD-{RELEASE}-macppc.iso
.El
.Sh EXAMPLES
.Bl -item
.It
Boot an Open Firmware 3 system, with
.Ar netbsd
installed on partition
.Dq Pa 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
.It
Boot from bootable CDROM (internal SCSI, id=3) of
.Nx 1.5
release with Open Firmware versions prior to 3:
.Bd -unfilled
0 > boot scsi/sd@3:0,OFWBOOT.XCF NETBSD.MACPPC
.Ed
.It
Boot from floppy disk:
.Bd -unfilled
0 > boot fd:0
.Ed
.It
Boot from network, with bootps,
.Xr bootptab 5 ,
.Xr tftpd 8 ,
and
.Xr nfsd 8
server available:
.Bd -unfilled
0 > boot enet:0
.Ed
.It
Boot from network, but use internal root partition of second drive:
.Bd -unfilled
0 > boot enet:0 ultra1:0
.Ed
.It
Boot MacOS, looking for the first available bootable disk:
.Bd -unfilled
0 > boot hd:,\e\e:tbxi
.Ed
.It
Boot MacOS X residing on partition 10:
.Bd -unfilled
0 > boot hd:10,\e\e:tbxi
.Ed
.El
.Sh ERRORS
.Bd -unfilled
DEFAULT CATCH!, code=FF00300 at %SRR0: FF80AD38 %SRR1: 00001070
.Ed
Could be
.Dq device not found
or I/O errors on the device.
The numbers are just for example.
.Bd -unfilled
Can't LOAD from this device
.Ed
Open Firmware found the device, but it is not supported by
.Ic load .
.Bd -unfilled
0 > boot yy:0/netbsd
RESETing to change Configuration!
.Ed
.Ar yy:0
doesn't exist, so Open Firmware ignores the string and uses the
default parameters to boot MacOS; the MacOS boot routine then clears
some of the Open Firmware variables.
.Bd -unfilled
0 > boot ata/ata-disk@0:9 specified partition is not bootable
 ok
.Ed
As it says.
.Bd -unfilled
0 > boot ata/ata-disk@0:0
>> NetBSD/macppc OpenFirmware Boot, Revision 1.3
>> (root@nazuha, Fri Jun  8 22:21:55 JST 2001)
no active package3337696/
.Ed
and hangs: See the real-base part in the FAQ.
.\" .Bd -unfilled
.\" 0 > boot yy
.\" >> NetBSD/macppc OpenFirmware Boot, Revision 1.3
.\" >> (root@nazuha, Fri Jun  8 22:21:55 JST 2001)
.\" no active packageopen yy: Device not configured
.\" open ata/ata-disk@0/yy: Device not configured
.\" Boot:
.\" .Ed
.Sh SEE ALSO
.Xr installboot 8
.Pp
.Pa INSTALL.html
.Pp
.Lk http://www.NetBSD.org/ports/macppc/faq.html "NetBSD/macppc Frequently Asked Questions"
.Pp
.Lk http://www.NetBSD.org/docs/network/netboot/ "Diskless NetBSD HOW-TO"
.Sh STANDARDS
.St -ieee1275-94
.Sh BUGS
.Nm
can only boot from devices recognized by Open Firmware.
.Pp
Early PowerMacintosh systems (particularly the 7500) seem to have problems
with netbooting.
Adding an arp entry at the tftp server with
.Dl arp -s booting-host-name its-ethernet-address
may resolve this problem (see
.Xr arp 8 ) .
.Pp
.Bd -unfilled
0 > boot CLAIM failed
 ok
.Ed
Once boot failed, successive boots may not be possible.
You need to type
.Ic reset-all
or power-cycle to initialize Open Firmware.