.\"	$NetBSD: ofwboot.8,v 1.18 2024/06/09 05:42:59 tsutsui 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 June 9, 2024
.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:
.Bd -literal -offset indent
.Ic boot Oo Ar boot-device Oo Ar boot-file Oc Oc Op Ar options
.Ed
.Pp
where
.Pp
.Bl -tag -width ".Ar boot-device" -offset indent -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:
.Bd -literal -offset indent
.Sm off
.Ar device Ic \&: Oo Ar partition-num Oc Op \&, \e Ar bootloader-filename
.Sm on
.Ed
.Pp
A typical example, from a PowerBook (FireWire), is
.Pp
.Dl /pci@f2000000/mac-io@17/ata-4@1f000/@0:9,\eofwboot.xcf
.Pp
Note that colon
.Pq Ql \&:
delimits the device to the left, and comma
.Pq Ql \&,
separates the bootloader 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
.Ar bootloader-filename .
For Open Firmware version 3, you must specify the bootloader filename.
.Pp
Open Firmware stores aliases to common devices in
.Tn NVRAM .
In the example the above,
.Pa /pci@f2000000/mac-io@17/ata-4@1f000/@0
is the path on a PowerBook
(FireWire) to the built-in
.Tn ATA Ns /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
.Ar boot-device
above could then be simplified to:
.Pp
.Dl hd:9,\eofwboot.xcf
.Pp
.Ar bootloader-filename
is usually
.Nm ofwboot.xcf .
See also the
.Sx FILES
section for further discussion.
.Pp
If
.Ar boot-device
is omitted from the
.Ic boot
command, the Open Firmware variable
.Ev 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
.Pa 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:
.Bd -literal -offset indent
.Sm off
.Oo Ar boot-file-device Ic \&: Ar partition-num\^ Ic \&/ Oc Op Ar kernel-name
.Sm on
.Ed
.Pp
This is a little different, since a kernel-name may be specified without
listing a
.Ar boot-file-device
and
.Ar partition-num .
Additionally, a
.Ar boot-file-device
and
.Ar partition-num
may need to be specified, while using the default
.Ar kernel-name .
.Pp
If no
.Ar kernel-name
is specified, the primary bootloader will try to find kernels named either
.Pa netbsd
or
.Pa netbsd.gz
on the boot-device or (if specified) boot-file-device.
.Ss options
Possible options are:
.Bl -tag -width Fl
.It Fl a
ask for the boot device
.It Fl s
single-user mode boot
.It Fl d
debug mode
.It Cm 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 Ev
.It Ev boot-device
used as the first argument
.It Ev boot-file
used as the second argument
.It Ev auto-boot?
setting this variable to
.Ic false
will present the user with an Open Firmware command prompt after power-on
reset.
A value of
.Ic true
will automatically boot the system using the variables
.Ev boot-device
and
.Ev boot-file .
(This is not really related to the boot command, but is included for
completeness.)
.El
.Pp
To restore these variables to their default values, use the
.Ic set-default
Open Firmware command:
.Pp
.Dl set-default 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 ".Pa ofwboot.xcf"
.
.It Pa 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 on the Open Firmware
.Ic boot
command, as it is stored in a special location in the
.Nx
partition that is marked
.Dq bootable
in the Apple partition map entry.
The bootable partition can be specified as 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 Pa 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 Pa 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 Pa 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 Pa netbsd
production kernel, using the GENERIC set of devices which supports almost all
hardware available for this platform.
.
.It Pa netbsd_GENERIC_MD.gz
GENERIC kernel (the same as
.Ar netbsd ) ,
with RAM disk and
.Ic sysinst
included.
.
.It Pa NetBSD-{RELEASE}-macppc.iso
bootable CD-ROM image for all supported systems.
Usually located at
.Pa https://cdn.NetBSD.org/pub/NetBSD/images/{RELEASE}/
.El
.Sh EXAMPLES
.Pp
In the following examples
.Ql "0\~>\~"
is the Open Firmware prompt.
.Bl -item
.
.It
Boot the default installation into single user mode.
.Dl 0 > boot -s
.
.It
Boot an Open Firmware 3 system, with
.Ar netbsd
installed on partition
.Dq Pa a :
.Dl 0 > boot hd:,\eofwboot.xcf
.
.It
Boot the kernel named
.Pa netbsd.new
from partition
.Dq Pa a
of the hard disk into
.Xr ddb 4
using
.Tn ELF
version of
.Nm
from the USB flash drive:
.Dl 0 > boot usb0/disk:,\eofwboot.elf hd/netbsd.new -d
or
.Dl 0 > boot usb1/disk:,\eofwboot.elf hd/netbsd.new -d
Note: You can check which usb device name should be used by
.Dq Ic devalias
and
.Dq Ic dev usb0 ls
commands etc.
.
.It
Boot from bootable CD-ROM of
.Nx
release with Open Firmware 3 or higher:
.Dl 0 > boot cd:,\eofwboot.xcf
.
.It
Boot from bootable CD-ROM (internal SCSI, id=3) of
.Nx
release with Open Firmware versions prior to 3:
.Dl 0 > boot scsi/sd@3:0
.
.It
Boot from a USB flash drive containing a bootable CD-ROM ISO image of
.Nx
release with Open Firmware 3 or higher:
.Dl 0 > boot usb0/disk@1:3,\eofwboot.xcf
or
.Dl 0 > boot usb1/disk@1:3,\eofwboot.xcf
Note: The partition number
.Dq Pa 3
is an ISO9660/HFS hybrid partition specified by the Apple partition map
in the macppc CD ISO image of
.Nx
release.
.
.It
Boot from floppy disk:
.Dl 0 > boot fd:0
.
.It
Boot from network, with bootps,
.Xr bootptab 5 ,
.Xr tftpd 8 ,
and
.Xr nfsd 8
server available:
.Dl 0 > boot enet:0
.
.It
Boot from network, but use internal root partition of second drive:
.Dl 0 > boot enet:0 ultra1:0
.
.It
Boot MacOS, looking for the first available bootable disk:
.Dl 0 > boot hd:,\e\e:tbxi
.
.It
Boot MacOS X residing on partition 10:
.Dl 0 > boot hd:10,\e\e:tbxi
.
.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.
If the error is caused by I/O errors (especially on CD boot),
retrying the same command after restarting Open Firmware by
.Ic reset-all
command might help.
.Bd -unfilled
CLAIM failed
.Ed
Open Firmware got errors on memory allocation ops etc.
This could also happen by buggy Open Firmware implementation, or improper
.Ev real-base
variable settings.
.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.
.Pp
Note: It is recommended to restart Open Firmware by
.Ic reset-all
command if you get these Open Firmware errors,
to avoid further unexpected random errors.
.Sh SEE ALSO
.Xr installboot 8
.Pp
.Pa INSTALL.html
.Pp
.Lk https://www.NetBSD.org/ports/macppc/faq.html "NetBSD/macppc Frequently Asked Questions"
.Pp
.Lk https://www.NetBSD.org/ports/macppc/partitioning.html "NetBSD/macppc Partitioning HOW-TO"
.Pp
.Lk https://www.NetBSD.org/ports/macppc/models.html "NetBSD/macppc Model Support"
.Pp
.Lk https://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
.Pp
.Dl arp -s booting-host-name its-ethernet-address
.Pp
may resolve this problem (see
.Xr arp 8 ) .
.Pp
Once boot failed,
.Bd -literal -offset indent
0 > boot CLAIM failed
 ok
.Ed
.Pp
successive boots may not be possible.
You need to type
.Ic reset-all
or power-cycle to re-initialize Open Firmware.