.\"	$NetBSD: install,v 1.42.8.1 2024/09/12 19:57:48 martin Exp $
.
.Ss2 Open Firmware boot syntax
.
The syntax of the Open Firmware
.Ic boot
command is:
.Pp
.Dl boot boot-device [boot-file] [-as]
.Pp
where the
.Li boot-device
describes where to find the bootloader,
.Li boot-file
describes where to find the
.Nx
kernel, and the options specify how you want to boot.
.Pp
You use the
.Li boot-device
to tell Open Firmware where to find
.Xr ofwboot 8
by listing the device, the partition (if it's a disk), and the filename
of the bootloader (if using
.Pa ofwboot.xcf ) .
.Pp
If the
.Li boot-file
is on the same device and partition (if it's a disk) as the
.Li boot-device
then you can just specify the kernel filename.
Otherwise, you need to specify the full Open Firmware path to the kernel.
.Pp
The
.Fl a
flag will ask you for the location of the next item to load
(i.e. the bootloader will ask where the kernel is (if unspecified),
or the kernel will ask where the root file system is).
The
.Fl s
flag will boot into
.Sq single-user
mode.
.Pp
The exact command you will be using depends on which version of Open Firmware
your machine has and which device you will be booting from.
Sometimes you may have to guess as we don't know all of the combinations
of models, device names, and file names.
In general the format is:
.Li "device:[partition][,\efilename]" .
Keep in mind for the future that you may be able to have your
.Li boot-device
and
.Li boot-file
on entirely different devices (such as the bootloader netbooted from
.Li enet
and the kernel loaded from a hard drive on the
.Li ultra0
ATA/IDE bus).
.Pp
We'll try to walk you through the process of figuring out what Open
Firmware calls your device, partition, and file names.
To start with, Open Firmware keeps a
.Dq device tree
with all of the devices it finds in your system.
You can get a listing of the nodes in this device tree with the
.Ic dev
and
.Ic ls
commands.
.Ic dev
is similar to the unix
.Ic cd
command and is used to change between the nodes in the Open Firmware
device tree (similar to a file system).
.Ic ls
of course is similar to the unix
.Ic ls
command and is used to list the contents of the current device node.
To get a listing of all the devices available in your system, use the
following commands:
.(disp
.No 0 \*[Gt] Ic "dev /"
.No 0 \*[Gt] Ic "ls"
.disp)
.Pp
Open Firmware has device aliases which are simple names for the full
hardware path to a device (similar to
.Ic alias
in
.Xr csh 1 ).
You can find out
what device aliases Apple created on your machine with the
.Ic devalias
command.
For example, here are the devaliases on a PowerMacintosh 7300:
.Pp
.(disp
.No 0 \*[Gt] Ic devalias
vci0                /chaos@F0000000
pci1                /bandit@F2000000
pci2                /bandit@F4000000
fd                  /bandit/gc/swim3
kbd                 /bandit/gc/via-cuda/adb/keyboard
ttya                /bandit/gc/escc/ch-a
ttyb                /bandit/gc/escc/ch-b
enet                /bandit/gc/mace
scsi                /bandit/gc/53c94
scsi-int            /bandit/gc/mesh
 ok
.disp)
.Pp
On most systems, you'll find the devices you're looking for.
Typical aliases are:
.Bl -column xxx "scsi-intxxxxxx" "internal scsi bus (on system with multiple SCSI busses)"
.It Ta Li hd Ta No "internal hard drive"
.It Ta Li cd Ta No "CD-ROM drive"
.It Ta Li zip Ta No "internal Zip drive"
.It Ta Li enet Ta No ethernet
.It Ta Li fd Ta No "floppy drive"
.It Ta Li scsi Ta No "SCSI bus"
.It Ta Li scsi-int Ta No "internal SCSI bus (on systems with multiple SCSI busses)"
.It Ta Li ata Ta No "ATA/IDE bus"
.It Ta Li ideN Ta No "ATA/IDE bus number N"
.It Ta Li ultraN Ta No "Ultra/66 or Ultra/100 IDE bus number N"
.El
.Pp
Note that some of these items are the device itself, and some are a bus.
When you only have the devalias to a bus, you need to specify which
device on that bus you want to use.
You can use the Open Firmware
.Ic dev No and Ic ls
commands.
For example, here are the devices on the internal SCSI bus of a
PowerMacintosh 7300:
.(disp
.No 0 \*[Gt] Ic "dev scsi-int"
.No 0 \*[Gt] Ic "ls"
FF83C850: /sd@0,0
FF83D480: /st@0,0
 ok
.disp)
.Pp
In this case, Open Firmware seems to be saying there are two devices, both
at address zero (one is a SCSI disk
.Sq sd@0,0
and the other is a SCSI tape
.Sq st@0,0 ).
Unfortunately, older systems will only list the naming convention and not
the actual devices currently connected, but that's OK -- we've got more
tricks up our sleeve.
.Pp
If you've got ATA/IDE drives, you have all the device information you need
(since Apple only ever ships drives as
.Dq master
which is typically something like
.Li ata-disk@0 , Li ATA-Disk@0 , Li atapi-disk , or Li disk@0 ).
.Pp
You can find out the devices on your SCSI bus with the
.Ic show-children
command:
.(disp
.No 0 \*[Gt] Ic "dev scsi-int"
.No 0 \*[Gt] Ic "show-children"
Target 0
  Unit 0  Disk     IBM     DCAS-32160      S65A
Target 3
  Unit 0  Removable Read Only device    SONY    CD-ROM CDU-8005 1.0j
 ok
.disp)
.Pp
Open Firmware calls SCSI IDs
.Dq Li Target .
The
.Dq Li Unit
number is the Logical Unit Number (LUN).
This is almost always zero.
Thus, this PowerMacintosh system has an IBM hard drive (DCAS-32160) at
SCSI ID 0, and a Sony CD-ROM drive (CDU-8005) at SCSI ID 3.
.Pp
Now, we've got enough information to construct the device name for
Open Firmware.
Just stick everything together to describe to Open Firmware what you want.
For example, Open Firmware calls the CD-ROM drive
in this system
.Li scsi-int/sd@3 .
.Pp
To determine if a device is bootable, type:
.Pp
.(disp
.No 0 \*[Gt] Ic dev scsi-int/sd@3
.No 0 \*[Gt] Ic words
load          write        read          seek        close     open
write-blocks  read-blocks  max-transfer  block-size  dma-sync  dma-map-out
dma-map-in    dma-free     dma-alloc
 ok
.disp)
.Pp
If the
.Ic word Dq Li open
is present in the list, then the device is almost certainly bootable.
.Pp
Next, you need to figure out what partition Open Firmware thinks your
bootloader is located on if you're going to boot from a disk.
If you're using a
.Dq "partition zero"
bootloader, the answer is obvious: 0.
Thus, your
.Li boot-device
for the
.Nx*M
CD-R image on an Open Firmware 1.0.5 system would be
.Li scsi-int/sd@3:0
since the image has a
.Sq "partition zero"
bootloader.
.Pp
Other situations get a little
trickier, as we know of no way to get a partition map from
within Open Firmware, and it uses a different numbering scheme than either
.Nx
or MacOS 9 (or earlier).  You can use
.Ic pdisk
to get a listing of the partitions on a disk.
See the Partitioning HOW-TO for help:
.Lk http://www.NetBSD.org/ports/macppc/partitioning.html#pdisk
.Pp
Typically, MS-DOS and ISO9660 formatted disks have their file systems at
partition 1.
Typically, Drive Setup formatted disks have their
file systems starting at partition number 9.
Often, if you omit the partition number, Open Firmware
looks in the first partition it understands holding a valid file system.
.Pp
Open Firmware uses a comma (,) to separate the partition number from the
filename.
It uses a backslash (the
.Pa \e
character) to separate directories.
The bootloader uses forward slashes (the
.Pa /
character) to separate directories when specifying the
.Li boot-file .
Thus, to specify the top of the
file system on a CD-ROM in the example PowerMacintosh 7300 system, you'd
use:
.Li scsi-int/sd@3:,\e
.Pp
Now, to confirm that you and Open Firmware are looking at the same files,
you can get a directory listing of the file system on your device with the
.Ic dir
command.
This command is only useful with file systems that Open Firmware
understands and is able to boot from.
On Open Firmware 1.0.5, 1.1.22, and 2.0.x systems, you can use
.Ic dir
on ISO9660 (not hybrid) and MS-DOS file systems.
On Open Firmware 2.4, you can use it on HFS, HFS+, hybrid, ISO9960,
and MS-DOS file systems.
On Open Firmware 3, you can use it on HFS, HFS+, hybrid (not pure ISO9660),
and MS-DOS file systems.  The one exception to this rule is that Open 
Firmware cannot list files on a disk with a 
.Sq "partition zero"
bootloader (including the 
.Nx*M
CD-R image and installation floppies).
.(disp
.No 0 \*[Gt] Ic "dir fd:,\e"
FINDER  .DAT 022 2 2B8
DESKTOP .    022 0 0
RESOURCE.FRK 012 3 0
NETBSD~1.GZ  020 5 1FDFCA
TRASH   .    010 B00 0
OFWBOOT .XCF 020 A75 D8F4
 ok
.disp)
You can see that this MS-DOS
formatted disk has a bunch of stuff, as well as the two important files:
.Pa NETBSD~1.GZ No and Pa OFWBOOT.XCF .
Note that
.Tn MacOS
shortened
.Pa netbsd-GENERIC_MD.gz No to Pa NETBSD~1.GZ
since MS-DOS file systems can only natively hold 8 characters for the
filename.
.(Note
Keep in mind that Open Firmware is often case-sensitive when it
comes to filenames.
.Note)
.(Note
You may need to append a 
.Pa ;1
to the filename when using a ISO 9660 file system.  This
.Dq "version number"
is part of the ISO 9660 specification and will show up in the directory 
listing if it is present on the disk.  For example:
.(disp
.No 0 \*[Gt] Ic "boot cd:,\eOFWBOOT.XCF;1 NETBSD.MACPPC;1"
.disp)
.Note)
.(Note
PowerPC 601 machines need to specify the
.Pa NETBSD.601
kernel when booting from the install CD, and use the
.Pa kern-GENERIC_601.\*[setsuffix]
and
.Pa netbsd-INSTALL_601.gz
kernels.
.Note)
.Pp
If the
.Ic dir
command showed you the files you're looking for, then you've figure out
how to tell Open Firmware to look for your bootloader!
In this case, your
.Sq Li boot-device
is
.Sq Li fd:,\eOFWBOOT.XCF
and your
.Sq Li boot-file
is
.Sq Li fd:,/NETBSD~1.GZ .
.Pp
For additional help, see
.Xr ofwboot 8
and the FAQ on topics like how to use the
Open Firmware command environment and how to boot from a device attached
to a PCI card which has Open Firmware support:
.Lk http://www.NetBSD.org/ports/macppc/faq.html#ofw-use
.Lk http://www.NetBSD.org/ports/macppc/faq.html#boot-pci
.
.Ss2 Examples of Open Firmware boot commands
.
Here are some examples of the commands you might use to boot your system:
.(bullet
.To 2 "Booting the NetBSD/macppc install CD-R"
.Em "Booting the NetBSD/\*M install CD-R"
.br
(Open Firmware 1.0.5, Open Firmware 1.1.22, Open Firmware 2.0.x, Open
Firmware 2.4)
.Pp
Here are some examples of what you might use to boot from CD-ROM (Apple
usually sets their CD-ROM drives to SCSI ID 3):
.Pp
.(disp
.No 0 \*[Gt] Ic "boot cd:0 NETBSD.MACPPC"
.No 0 \*[Gt] Ic "boot cd:0 NETBSD.601"
.No 0 \*[Gt] Ic "boot scsi-int/sd@3:0 NETBSD.MACPPC"
.No 0 \*[Gt] Ic "boot scsi/sd@3:0 NETBSD.MACPPC"
.No 0 \*[Gt] Ic "boot ata/atapi-disk:0 NETBSD.MACPPC"
.No 0 \*[Gt] Ic "boot ide1/disk@0:0 NETBSD.MACPPC"
.disp)
.Pp
.It
.Em "Booting the NetBSD/\*M install CD-R"
.br
(Open Firmware 3)
.Pp
.(disp
.No 0 \*[Gt] Ic "boot cd:,\eofwboot.xcf netbsd.macppc"
.disp)
.It
.To 2 "Booting the NetBSD install floppies"
.Em "Booting the NetBSD install floppies"
.br
(Open Firmware 1.0.5, Open Firmware 1.1.22, Open Firmware 2.0.x, Open
Firmware 2.4)
.Pp
The first floppy disk has a
.Sq "partition zero"
bootloader.  When it has loaded the kernel, it will ask you to insert the
second floppy disk.
.(Note
This is not a normal
.Tn MacOS
boot floppy -- you must enter Open Firmware and type a boot command.
.Note)
All you need to do is:
.Pp
.(disp
.No 0 \*[Gt] Ic boot fd:0
.disp)
.Pp
It is common to see
.Dq "READ TIMEOUT@"
from the floppy.  This means that Open
Firmware is having difficulty reading the media.  See the section below on
.Sx "Common Problems and Error Messages"
for more information about this and what you can do to get a successful boot.
.Pp
You can eject a floppy by typing:
.Pp
.(disp
.No 0 \*[Gt] Ic eject fd
.disp)
.It
.To 2 "Booting an IDE or SCSI drive with an HFS partition"
.Em "Booting an IDE or SCSI drive with an HFS or HFS+ partition"
.br
(Open Firmware 2.4, Open Firmware 3)
.Pp
.Tn MacOS
drives have several system-level partitions reserved for
.Tn MacOS
drivers.
You may find that your first HFS or HFS+ partition might be as high as
partition 9.
You may need to keep trying higher partition numbers until you find the one
that has your bootloader.  You can use
.Ic pdisk
to print out your partition map:
.Lk http://www.NetBSD.org/ports/macppc/partitioning.html#pdisk
.Pp
You should use the Open Firmware
.Ic dir
command to get a directory listing of the files on your hard drive.
.Pp
If bootloader is on a different partition from the
.Nx
kernel, you will need to specify where to find the kernel.
.Pp
Remember, that SCSI Zip disks are usually ID 5 or 6.
Internal hard drives are usually SCSI ID 0.
.Pp
Here are some examples of what you might use to boot the installer kernel
located on an HFS or HFS+ partition:
.Pp
.(disp
.No 0 \*[Gt] Ic "boot hd:9,\eofwboot.xcf netbsd-GENERIC_MD.gz"
.No 0 \*[Gt] Ic "boot scsi/sd@0:9,\eofwboot.xcf netbsd-GENERIC_MD.gz"
.No 0 \*[Gt] Ic "boot ide0/disk@0:10,\eofwboot.xcf netbsd-GENERIC_MD.gz"
.No 0 \*[Gt] Ic "boot ultra1:9,ofwboot.xcf netbsd-GENERIC_MD.gz"
.disp)
.Pp
.It
.To 2 "Booting a custom CD-ROM"
.Em "Booting a custom CD-ROM"
.br
(All Open Firmware versions)
.Pp
Open Firmware doesn't understand long filenames (created with the RockRidge
and Joliet extensions), so you may need to figure out what your file is
called.  You should use the Open Firmware
.Ic dir
command to get a listing of the files on your CD.
.Pp
For instance,
.Ic Toast
for
.Tn MacOS
creates CDs with long filenames, but uses
.Tn MS-DOS
style short names
as well.
Instead of referencing
.Pa netbsd-GENERIC
you would need to open
.Pa NETBSD-G.ENE
The
.Ic mkisofs
program has a similar problem,
.Pa netbsd-GENERIC_MD.gz
becomes
.Pa NETBSD-GENERIC_MD.GZ .
.Pp
Another thing to note is that you
.Em must
use the same case when specifying the filename to load that Open Firmware
uses.
Also, keep in mind what format your CD-R has to be for your version of
Open Firmware (pure ISO versus hybrid ISO/HFS).
.Pp
We'll assume that you've wisely renamed your kernel to
.Pa netbsd.gz
to avoid many of these name issues.
Here are some examples of what you might use to boot from CD-ROM
(Apple usually sets their CD-ROM drives to SCSI ID 3):
.Pp
.(disp
.No 0 \*[Gt] Ic "boot cd:,\eofwboot.xcf netbsd.gz"
.No 0 \*[Gt] Ic "boot scsi-int/sd@3:,\eOFWBOOT.XCF NETBSD.GZ"
.No 0 \*[Gt] Ic "boot scsi/sd@3:,\eOFWBOOT.XCF NETBSD.GZ"
.No 0 \*[Gt] Ic "boot ata/atapi-disk:,\eOFWBOOT.XCF NETBSD.GZ"
.No 0 \*[Gt] Ic "boot ide1/disk@0:,\eOFWBOOT.XCF NETBSD.GZ"
.disp)
.It
.To 2 "Booting an MS-DOS floppy"
.Em "Booting an MS-DOS floppy"
.br
(Open Firmware 1.0.5, Open Firmware 1.1.22, Open Firmware 2.0.x, Open
Firmware 2.4)
.(Note
This is not a normal
.Tn MacOS
boot floppy -- you must enter Open Firmware and type a boot command.
.Note)
.Pp
Use the Open Firmware
.Ic dir
command to get a listing of the files on the floppy.
Typically you'll find filenames like
.Li OFWBOOT.XCF No and Li NETBSD~1.GZ .
.(disp
.No 0 \*[Gt] Ic "boot fd:,\eOFWBOOT.XCF NETBSD~1.GZ"
.disp)
.Pp
You can eject a floppy by typing:
.Pp
.(disp
.No 0 \*[Gt] Ic eject fd
.disp)
.It
.To 2 "Booting over the ethernet"
.Em "Booting over the ethernet"
.br
(Open Firmware 1.0.5, Open Firmware 1.1.22, Open Firmware 2.0.x, Open
Firmware 2.4)
.Pp
You can try the simple form (i.e. that you are booting from ethernet):
.Pp
.(disp
.No 0 \*[Gt] Ic "boot enet:,ofwboot.xcf"
.disp)
.Pp
Or you may be more specific,
specifying the bootloader filename and the kernel name:
.Pp
.(disp
.No 0 \*[Gt] Ic "boot enet:,ofwboot.xcf enet:,/netbsd-GENERIC_MD.gz"
.disp)
.(Note
Some Open Firmware 1.0.5 machines have their MAC address stored
incorrectly.
Make sure that your netboot server is using the same MAC
address that your \*M client is using.
See the section on
.Sx "Setting up Open Firmware 1 and 2 to boot NetBSD"
to figure out your MAC address.
.Note)
.(Note
Some machines cannot load compressed kernels over ethernet.
Uncompress them first.
.Note)
.It
.Em "Booting over the ethernet"
.br
(Open Firmware 3)
.Pp
You can try the simple form (i.e. that you are booting from ethernet):
.Pp
.(disp
.No 0 \*[Gt] Ic "boot enet:0"
.disp)
.Pp
Or you may be more specific,
specifying the bootloader filename and the kernel name:
.Pp
.(disp
.No 0 \*[Gt] Ic "boot enet:0,ofwboot.xcf enet:0,/netbsd-GENERIC_MD.gz"
.disp)
.It
.To 2 "Booting an IDE or SCSI drive with 'partition zero'"
.Em "Booting an IDE or SCSI drive with a"
.Sq Em "partition zero"
.Em bootloader
.br
(Open Firmware 1.0.5, Open Firmware 1.1.22, Open Firmware 2.0.x, Open
Firmware 2.4)
.Pp
You do not specify a file to load, since the
.Sq "partition zero"
bootloader knows what to do.
You would boot such a system if you have dumped
the CD-R image to your drive, or if you have an already-installed
.Nx*M
system
.Pp
Remember, that SCSI Zip disks are usually ID 5 or 6.
Internal hard drives are usually SCSI ID 0.
.Pp
Here are some examples of what you might use to boot from such a drive:
.Pp
.(disp
.No 0 \*[Gt] Ic "boot zip:0"
.No 0 \*[Gt] Ic "boot scsi-int/sd@0:0"
.No 0 \*[Gt] Ic "boot scsi/sd@0:0"
.No 0 \*[Gt] Ic "boot ata/ata-disk@0:0"
.No 0 \*[Gt] Ic "boot ata/ATA-Disk@0:0"
.No 0 \*[Gt] Ic "boot ide0/disk@0:0"
.disp)
.bullet)
.
.Ss2 Example of a normal boot
.
Of course, a lot of the information in this example depends on your model
and what your boot method is, but we'll include this anyways just so you
get an idea of what to expect (user-typed commands are in
.Ic bold ) .
.(disp
 Apple PowerBook3,1 2.1f1 BootROM built on 01/29/00 at 22:38:07
 Copyright 1994-2000 Apple Computer, Inc.
 All Rights Reserved

 Welcome to Open Firmware.
 To continue booting, type "mac-boot" and press return.
 To shut down, type "shut-down" and press return.
  ok
.No  0 \*[Gt] Ic "boot enet:,ofwboot.xcf netbsd-GENERIC_MD.gz"
 loading XCOFF
 tsize=C280 dsize=14AC bsize=2620 entry=600000
 SECTIONS:
 .text    00600000 00600000 0000C280 000000E0
 .data    0060D000 0060D000 000014AC 0000C360
 .bss     0060E4B0 0060E4B0 00002620 00000000
 loading .text, done..
 loading .data, done..
 clearing .bss, done..

 \*[Gt]\*[Gt] NetBSD/macppc OpenFirmware Boot, Revision 1.3
 \*[Gt]\*[Gt] (tsubai@mint.iri.co.jp, Sun Nov 26 01:41:27 JST 2000)
 1701508+177748 [100+68176+55886]=0x1e9468

  start=0x100000
 Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001
     The NetBSD Foundation, Inc.  All rights reserved.
 Copyright (c) 1982, 1986, 1989, 1991, 1993
     The Regents of the University of California.  All rights reserved.

 NetBSD 1.5.1 (INSTALL) #0: Thu Mar 15 00:52:56 PST 2001
     mw@al:/usr/src/sys/arch/macppc/compile/INSTALL
 total memory = 192 MB
 avail memory = 172 MB
 using 2483 buffers containing 9932 KB of memory
 [...]
 erase ^H, werase ^W, kill ^U, intr ^C, status ^T
 Terminal type? [vt100]
 Erase is backspace.
 (I)nstall, (S)hell or (H)alt ?
.disp)
.
.Ss2 Common Problems and Error Messages
.
This is a brief list of some of the Open Firmware problems you may run into.
See the
.Nx*M
FAQ for a thorough list.
.Lk http://www.NetBSD.org/ports/macppc/faq.html#boot-trouble
.(Note
You may find it necessary to remove all non-Apple devices from your
machine.
Some users have found this necessary.
.Note)
.Pp
.(bullet
.To 2 "Black screen"
Black screen
.Pp
If your system is a PowerBook,
.Nx
may have turned down the brightness of the backlight.
Use the buttons to turn your brightness back up.
.Pp
Open Firmware 3.x and newer often won't setup the console if you don't
drop to a prompt, and
.Nx
doesn't know how to setup the console itself.
To get the system to boot when you have auto-boot? set to true, you
can try this workaround.
First, try one of the following commands:
.sp
.Dl setenv boot-command \*[q] screen\*[q] output boot
.Dl setenv boot-command ." screen" output boot
.Dl setenv boot-command ." Booting NetBSD..." cr \*[q] screen\*[q] output boot
.sp
You should follow the command with:
.sp
.Dl reset-all
.sp
This will cause Open Firmware to output some text to the screen prior
to booting, thus forcing it to setup the console.
.Pp
Otherwise, you need a serial console.
See the section entitled
.Sx "Open Firmware 1 and 2 System Preparation"
.It
.To 2 "Grey screen with flashing question mark"
Grey screen with flashing question mark
.Pp
This means that your system is trying to boot
.Tn MacOS .
You might get to this state if you didn't properly enter Open Firmware, or if
your Open Firmware boot command has bad syntax.
.Pp
If you typed a bad boot command, Open Firmware tries to boot from the
value stored in the
.Li boot-device
 variable, whose default value is the MacOS ROM.
.Pp
The grey screen with the icon is generated by the MacOS ROM.
A flashing question-mark or broken folder means that your machine
is looking for a bootable MacOS file system, but can't find one.
A globe icon means that your machine is looking for a netboot server.
A happy face or spinning disc means it's starting to boot MacOS.
.Pp
The boot floppy does not have a bootable MacOS file system, it has a
bootable NetBSD file system.
.Pp
Reboot, re-enter Open Firmware and check your syntax carefully.
.Pp
.(Note
Don't forget to check your Open Firmware environment variables, as they
may have been changed by your brief excursion into
.Tn MacOS .
.Note)
.It
.To 2 "Information on your screen seems garbled or out of sync"
Information on your screen seems garbled or out of sync
.Pp
If you have a PowerMacintosh 7300 through 8600, then you need to read the
section on System Disk and the patches it applies.
See the section entitled
.Sx "Open Firmware 1 and 2 System Preparation"
.Pp
If you have a Twentieth Anniversary Macintosh, Open Firmware does not work
with the internal display, you will need to set up a serial console.
.Pp
.It
.To 2 "DEFAULT CATCH!"
.Dq Li "DEFAULT CATCH!"
.Pp
This is a general message from Open Firmware to the effect that it had
trouble loading a file.
.Pp
If your machine is Open Firmware version 1.0.5, 2.0.x, or 2.4, this error
does sometimes appear randomly.
You might try the boot command a second time
(this is known to work on some models).
It's also an indication that either your floppy disk is bad,
or the floppy drive is bad.
Try doing a low-level format on the floppy, re-copy the files, and try again.
.Pp
There are several models that cannot be booted while using the on-board
video and keyboard.
Try using a serial console.
.It
.To 2 "CLAIM failed"
.Dq Li "CLAIM failed"
.Pp
This is a general message from Open Firmware to the effect that it failed
to allocate some memory or memory is messed up.
.Pp
First, make sure you have the Open Firmware variable
.Li load-base
set correctly.
If your system is Open Firmware version 1.0.5, 1.1.22,
2.0.x, or 2.4, see the section above on
.Sx "Setting up Open Firmware 1 and 2 to boot NetBSD"
.Pp
Do not change
.Li load-base
on an Open Firmware 3 system.
.Pp
Reset your system and try using a different boot command (this is the 
only way some people have gotten their Open Firmware 2.4 systems to work):
.(disp
.No 0 \*[Gt] Ic "0 bootr boot-device boot-file"
.disp)
.Pp
If you tried one boot command and it failed, then you tried a second and
got the
.Li CLAIM failed
message, then this is an indication that you should reboot between attempts.
Use the Open Firmware
.Ic reset-all
command.
.Pp
Contradictorily, if your machine is Open Firmware version 1.0.5, 2.0.x or
2.4, this error does sometimes appear randomly.
You might try the boot command a second time
(this is known to work on some models).
.Pp
There are several models that cannot be booted while using the on-board
video and keyboard.
Try using a serial console.
.It
.To 2 "can't OPEN"
.Dq Li "can't OPEN"
.Pp
Open Firmware either can't open the device you specified (because it is not
present or the device path is mistyped) or the file you specified.
Check your typing and check to make sure that the media has the
files you think it has.
.Pp
Use the NetBSD
.Ic pdisk
command to list the partition map and the Open Firmware
.Ic dir
command to verify that the file(s) you tried accessing are really there.
.It
.To 2 "unrecognized Client Program formatstate not valid"
.Dq Li "unrecognized Client Program formatstate not valid"
.Pp
This is a general Open Firmware error message indicating that the filename
you tried to open either doesn't exist or is in the wrong format.
For Open Firmware 1 and 2 machines, it must be an XCOFF file (such as
.Pa ofwboot.xcf )
and for Open Firmware 3 machines, it must be either XCOFF or ELF (such as
a kernel).
Make sure that you have use binary mode to FTP the files, and
that they are properly uncompressed.
.It
.To 2 "bad partition number, using 0no bootable HFS partition"
.Dq Li "bad partition number, using 0no bootable HFS partition"
.Pp
If you're trying to boot an Open Firmware 1.0.5, 1.1.22, or 2.0.x system,
this probably means that your media (i.e. hard drive or CD-ROM) has an HFS
file system on it (such as a hybrid CD-R or a hard drive with MacOS
partitions).
.It
.To 2 "READ TIMEOUT@"
.Dq Li "READ TIMEOUT@"
.Pp
Open Firmware is having trouble reading your floppy disk.  Things to try:
.(bullet -compact
Try booting from the floppy again
.It
Try a different floppy disk
.It
Try writing the floppy on the same machine you're trying to boot
.It
Clean the floppy drive
.It
Use another boot method
.bullet)
.Pp
As disk drives get older, especially with portables, they can get a
little bit out of alignment so that they do not consistently read disks
written on other floppy drives.  Strongly consider writing the floppies
on the same machine that will be reading them.
.It
.To 2 "TFTP timeout"
.Dq Li "TFTP timeout"
.Pp
Either the server's TFTP server isn't running, or you're using a model
with Open Firmware 1.0.5 and not specifying the location of the bootloader.
Unfortunately, on the early models,
.Pa ofwboot.xcf
gets confused and doesn't work right unless you load it explicitly from the
.Li boot-device ,
even if the bootp or DHCP server provides the correct information.
You need to boot with a command like:
.(disp
.No 0 \*[Gt] Ic "boot enet:,ofwboot.xcf"
.disp)
.It
.To 2 "enet:,/netbsd.ram.gz: Inappropriate file type or format"
.Dq Li "enet:,/netbsd.ram.gz: Inappropriate file type or format"
.Pp
Some systems booting over ethernet can't load compressed 
kernels.  Use 
.Xr gunzip 1
to uncompress the kernel before attempting to netboot.
.It
.To 2 "Bootloader hangs before the copyright notice"
Bootloader hangs before the copyright notice and the kernel configuration
.Pp
You forgot to set
.Li real-base
in Open Firmware or it got erased by your booting into
.Tn MacOS .
.Pp
Make sure you have the Open Firmware variable
.Li real-base
set correctly.
If your system is Open Firmware version 1.0.5, 1.1.22,
2.0.x, or 2.4, see the section above on
.Sx "Setting up Open Firmware 1 and 2 to boot NetBSD"
.Pp
Do not set
.Li real-base
on an Open Firmware 3 system.
.It
.To 2 "Hang after configuring devices"
Hang after configuring devices, but before doing anything else
.Pp
Actually, this can have many causes.
The most likely is a keyboard problem.
First, try plugging the USB keyboard directly into the computer
(i.e. not through a hub) and unplugging the mouse.
.Pp
If you're trying a model that's not on the supported list (such as a new 
laptop model), they keyboard may not be supported yet.
.bullet)
.
.Ss2 Milestone
.
If you've reached this point, then you must've gotten the
.Nx
installer to boot.
Congratulations!
That was the hard part.
From now through the rest of this document,
there should be no more Open Firmware
specific problems, so read everything because it applies to all models.
.
.so ../common/sysinst
.
.Ss2 "Finalizing Open Firmware settings"
.
Now, you can reboot to get to the Open Firmware prompt.  You still need 
to figure out how to get Open Firmware to boot the operating system(s) of 
your choice.  First, try to get 
.Nx*M
running.  Using the methods described in the section 
.Sx "Examples of Open Firmware boot commands"
figure out the boot command for your installation of
.Nx .
Try booting.  Once you've got the syntax worked out, decide which operating 
systems you'll be using regularly.
.(bullet
.To 2 "Booting NetBSD exclusively"
.Em "Booting NetBSD exclusively"
.br
If you'll only be using
.Nx
on your \*M system, then simply set the Open Firmware
.Sq Li boot-device
and
.Sq Li boot-file
variables to the values you just determined.  Also, you might want to 
enable the system to always boot
.Nx
when powered on or reset.  Once you set up auto-booting you can get to 
the Open Firmware prompt again by using the
.Xr shutdown 8
command to halt the system.
.Pp
If you are not using a
.Sq "partition zero"
style boot scheme (e.g. Open Firmware 3 models), then you would type 
something like the following:
.Pp
.(disp
.No 0 \*[Gt] Ic "setenv auto-boot? true"
.No 0 \*[Gt] Ic "setenv boot-device ide0/disk@0:8,\eofwboot.xcf"
.No 0 \*[Gt] Ic "setenv boot-file ide0/disk@0:13,/netbsd"
.No 0 \*[Gt] Ic "reset-all"
.disp)
.Pp
The last command resets the system so that these settings are stored.
.Pp
If you are using a
.Sq "partition zero"
style boot scheme, you would type something like the following:
.Pp
.(disp
.No 0 \*[Gt] Ic "setenv auto-boot? true"
.No 0 \*[Gt] Ic "setenv boot-device scsi/sd@0:0"
.No 0 \*[Gt] Ic "setenv boot-file netbsd"
.No 0 \*[Gt] Ic "reset-all"
.disp)
.Pp
Replace
.Ic scsi/sd@0:0
with the actual device you will be booting from.
.It
.To 2 "Additional Open Firmware tips"
.Em "Additional Open Firmware tips"
.br
If you find that your system tries booting before your hard drive has
spun up, try one of the two following
.Sq Li boot-command
settings:
.Pp
.(disp
.No 0 \*[Gt] Ic "setenv boot-command catch 5000 ms boot"
.No 0 \*[Gt] Ic "setenv boot-command begin ['] boot catch 1000 ms cr again"
.disp)
.Pp
Also, you may be able to pause a system at the Open Firmware prompt
if you have 
.Sq Li auto-boot?
set to
.Sq Li true
by holding down any key while the system is resetting.  Set the 
following
.Sq Li boot-command
(this may not work on system with Open Firmware 1.0.5) (this method should
interrupt booting, even when holding down any key while using a serial 
console):
.Pp
.(disp
.No 0 \*[Gt] Ic "setenv boot-command key? invert if boot then"
.disp)
.It
.To 2 "Booting NetBSD and MacOS X or Darwin"
.Em "Booting NetBSD and MacOS X or Darwin"
.br
Alas, this takes a little more work.  Usually, when you select a system 
to boot in the
.Dq "Startup Disk"
panel of the 
.Dq "System Preferences"
application, it stores the Open Firmware path to that device in the
.Sq Li boot-device
variable.  So, instead of writing the 
.Nx
device path to Open Firmware, you'll store the paths to your operating 
systems in NVRAM.  Open Firmware cannot deal with nested
.Ic devalias
entries.  You must, therefore, enter the 
.Em entire
path to your device.  See the
.Nx*M 
.Ic nvedit
HOW-TO for more help:
.Lk http://www.NetBSD.org/ports/macppc/nvedit.html
.Pp
.(disp
.No 0 \*[Gt] Ic "printenv boot-device"
boot-device /pci@f2000000/mac-io@17/ata-4@1f000/@0:10,\e\e:tbxi
 ok
.No 0 \*[Gt] Ic "nvalias osx /pci@f2000000/mac-io@17/ata-4@1f000/@0:10,\e\e:tbxi"
.No 0 \*[Gt] Ic "nvalias bsd /pci@f2000000/mac-io@17/ata-4@1f000/@0:9,ofwboot.xcf"
.No 0 \*[Gt] Ic "nvstore"
.No 0 \*[Gt] Ic "setenv use-nvramrc? true"
.No 0 \*[Gt] Ic "reset-all"
.disp)
.Pp
Now, when the system is reset, it will stop at the Open Firmware prompt 
and you can type one of the following to boot an operating system:
.(disp
.No 0 \*[Gt] Ic "boot osx"
.No 0 \*[Gt] Ic "boot bsd"
.disp)
.It
.To 2 "Booting NetBSD and MacOS 9 or earlier"
.Em "Booting NetBSD and MacOS 9 or earlier"
.br
For Open Firmware 3 systems, the procedure is identical to the section 
above on
.Sx "Booting NetBSD and MacOS X or Darwin"
.Pp
For older systems, you're in for more hassle.  Booting an Open Firmware 
1.0.5, 2.0.x, or 2.4 system into 
.Tn MacOS
9 or earlier will erase some or all of your Open Firmware settings.  Try 
it and see which Open Firmware variables survive.  
.Pp
If only 
.Sq Li real-base
is lost, you can compile a kernel that does not require changing the
.Sq Li real-base .
Just build a kernel that is less than 4 MB uncompressed.  This is easy if
you remove all of the USB devices from the config file.  Once you've got 
a smaller kernel, just follow the procedure in the section above on
.Sx "Booting NetBSD and MacOS X or Darwin"
.Pp
If everything is lost when you boot into 
.Tn MacOS
9 or earlier, you will need to make a custom BootVars 
configuration that you run before trying to boot
.Nx*M 
since System Disk does not preserve enough information when it saves a 
configuration.
.(enum
If your system supports System Disk, run it and click 
.Dq Save
to install the NVRAMRC patches.
.It
Run BootVars, click the 
.Dq "All Variables"
button.
.It
Fill in 
.Sq Li real-base , 
.Sq Li boot-device , 
.Sq Li boot-file , 
.Sq Li input-device , 
and
.Sq Li output-device .
.It
From the 
.Dq File
menu, pick 
.Dq Save .
When you run this file, it will load BootVars with all your settings.  To 
boot
.Nx
click the
.Dq "Write&reboot"
button.
.It
Now your system will always boot
.Nx .
To boot
.Tn MacOS ,
use the
.Xr shutdown 8
command to halt the system at the Open Firmware prompt and use the
Open Firmware
.Dq Li bye
or
.Dq Li mac-boot
command to boot
.Tn MacOS .
.enum)
.It
.To 2 "Other boot techniques"
.Em "Other boot techniques"
.br
See the FAQ for some vague information on how to use the Linux
.Ic yaboot
system to boot
.Nx .
.Lk http://www.NetBSD.org/ports/macppc/faq.html#yaboot
.bullet)