NetBSD/distrib/notes/macppc/install

.\"	$NetBSD: install,v 1.15 2001/07/05 05:03:02 mbw Exp $
.
.Ss2 Booting the installer
.
The syntax of the Open Firmware
.Ic boot
command is:
.Pp
.Dl boot device[:partition][,filename] [kernel_location] [-as]
.Pp
where the
.Fl a
flag will ask you for the location of the next item to load (i.e.
.Pa ofwboot.xcf
will ask where the kernel is, or the kernel will ask where the root
file system is).
The
.Fl s
flag will boot into
.Sq single-user
mode.
.Pp
.Li kernel_location
is either a filename if the kernel is on the same partition as the
bootloader, or another complete
.Sq Li "device:partition,filename" .
And, there's no reason (other than Open Firmware bugginess) that you can't
specify an entirely different device for the kernel.
For instance, you could have a
.Tn MacOS
drive on your
.Em ultra1
(ATA) bus, and a
.Nx
drive on your
.Em ultra0
bus (since 
.Pa wd0 No Ns ,
the first drive recognized by 
.Nx*M
is usually found on the
.Em ultra0
bus).
.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.
.Pp
Open Firmware has device aliases which are simple names for the full
hardware path to a device.  You can find out
what device aliases Open Firmware has on your machine by typing:
.Pp
.Dl 0 > Ic devalias
.Pp
To get a complete listing of what hardware is recognized by Open
Firmware, type:
.Pp
.Dl 0 > Ic dev / ls
.Pp
To determine if a device is bootable, type:
.Pp
.Dl 0 > Ic dev /path/to/device words
.Pp
If
.Sq open
is in the list of words, then this device might be bootable.
.Pp
.(Note
SCSI disks are usually of the form:
.Pp
.Dl boot scsi_devalias/sd@i:p
.Pp
where
.Sq Li scsi_devalias
is the Open Firmware
.Sq Li devalias
for your SCSI interface,
.Sq Li i
is the SCSI ID, and
.Sq Li p
is the partition.
.Note)
.
.Ss2 Boot Commands
.
Here are some examples of the commands you might use to boot your system:
.(bullet
.Em "Floppy disk"
.br
(Open Firmware 1.0.5, Open Firmware 1.1.22, Open Firmware 2.0.x, Open 
Firmware 2.4)
.Pp
The floppy disk has a
.Sq "partition zero"
bootloader. 
.(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
.Dl 0 > Ic boot fd:0
.Pp
You can eject a floppy by typing:
.Pp
.Dl 0 > Ic eject fd
.It
.Em 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
.Dl 0 > Ic "boot enet"
.Pp
Or you may be more specific,
specifying the bootloader filename and the kernel name:
.Pp
.Dl 0 > Ic "boot enet:,ofwboot.xcf enet:,netbsd.ram.gz"
.(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 pre-Open Firmware 3 to boot NetBSD
to figure out your MAC address.
.Note)
.(Note
Some Open Firmware 1.0.5 machines do not retrieve the BOOTP information
correctly. These machines cannot netboot.
.Note)
.It
.Em Ethernet
.br
(Open Firmware 3)
.Pp
You can try the simple form (i.e. that you are booting from ethernet):
.Pp
.Dl 0 > Ic "boot enet:0"
.Pp
Or you may be more specific,
specifying the bootloader filename and the kernel name:
.Pp
.Dl 0 > Ic "boot enet:0,ofwboot.xcf enet:0,netbsd.ram.gz"
.It
.Em 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. 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
.Pp
The
.Ic mkisofs
and
.Ic mkhybrid
programs have a similar problem. For them,
.Pa netbsd.ram.gz
becomes
.Pa NETBSD_RAM.GZ
.Pp
Another thing to note is that you
.Em must
use capital letters when specifying the filename to load.
Also, keep in mind what format your CD-R has to be for your version of
Open Firmware (pure ISO versus hybrid ISO/HFS) before giving up.
.Pp
You may be able to get a directory listing of the files on your CD-ROM
disk with the following command (where
.Pa scsi/sd@3:0
is the device alias and path to your CD-ROM drive):
.Dl 0 > Ic "dir scsi/sd@3:0,\e\"
If you have subdirectories, you can examine them as well:
.Dl 0 > Ic "dir scsi/sd@3:0,\e\\&subdirectory\e\"
.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
.Dl 0 > Ic "boot scsi-int/sd@3:0,OFWBOOT.XCF NETBSD.RAM"
.Dl 0 > Ic "boot scsi/sd@3:0,OFWBOOT.XCF NETBSD.RAM"
.Dl 0 > Ic "boot scsi-ext/sd@3:0,OFWBOOT.XCF NETBSD.RAM"
.Dl 0 > Ic "boot ata/atapi-disk:0,OFWBOOT.XCF NETBSD.RAM"
.Dl 0 > Ic "boot ide1/disk@0:0,OFWBOOT.XCF NETBSD.RAM"
.Dl 0 > Ic "boot cd:0,OFWBOOT.XCF NETBSD.RAM"
.It
.Em "IDE or SCSI drive with a"
.Sq "partition zero"
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"
booloader knows what to do. You would boot such a system if you have dumped
the boot floppy 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
.Dl 0 > Ic "boot scsi-int/sd@0:0"
.Dl 0 > Ic "boot scsi/sd@0:0"
.Dl 0 > Ic "boot scsi-ext/sd@0:0"
.Dl 0 > Ic "boot ata/ata-disk@0:0"
.Dl 0 > Ic "boot ata/ATA-Disk@0:0"
.Dl 0 > Ic "boot ide0/disk@0:0"
.Dl 0 > Ic "boot zip:0"
.It
.Em "IDE or SCSI drive from 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.  If you're running 
.Tn MacOS X
you can run the following command to print out the partition table on your
drive:
.Dl % Ic "sudo pdisk /dev/disk0 -dump"
.Pp
You may be able to get a directory listing of the files on your hard
drive with the following command (where
.Pa hd-devalias
is the device alias and path to your hard drive):
.Dl 0 > Ic "dir hd-devalias:,\e\"
If you have subdirectories, you can examine them as well:
.Dl 0 > Ic "dir hd-devalias:,\e\\&subdirectory\e\"
.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 boot floppy image 
located on an HFS or HFS+ partition (note, you must use the path to the floppy
image):
.Pp
.Dl 0 > Ic "boot scsi/sd@0:9,ofwboot.xcf scsi/sd@0:9,boot.fs"
.Dl 0 > Ic "boot ide0/disk@0:10,ofwboot.xcf ide0/disk@0:9,boot.fs"
.Dl 0 > Ic "boot hd:9,ofwboot.xcf hd:9,boot.fs"
.Pp
Here are some examples of what you might use to boot a kernel located on the
same HFS or HFS+ partition as the bootloader (note, you do not specify a 
path to the kernel name):
.Pp
.Dl 0 > Ic "boot ultra1:9,ofwboot.xcf netbsd.ram.gz"
.Dl 0 > Ic "boot hd:10,ofwboot.xcf netbsd.GENERIC.gz"
.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 No Ns ).
.(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 > Ic "boot hd:ofwboot.xcf hd:boot.fs"
 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..
 
 >> NetBSD/macppc OpenFirmware Boot, Revision 1.3
 >> (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 in your
machine.  Some users have found this necessary.
.Note)
.Pp
.(bullet
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
Otherwise, you need a serial console. See the section entitled
.Sx Getting to the Open Firmware Prompt on Older Models
.It
Grey screen with flashing question mark
.Pp
You mistyped the path to a device or you didn't enter Open Firmware
correctly, and your system defaulted to booting into
.Tn MacOS .
The flashing question mark means that the
.Tn MacOS
ROM has loaded and is looking for a bootable
.Tn MacOS
file system.
.Pp
Remember, the boot floppy image must be booted from Open Firmware, it is
not a normal
.Tn MacOS
boot floppy.
.(Note
Don't forget to check your Open Firmware environment variables, as they
may have been changed by your brief excursion into
.Tn MacOS No Ns .
.Note)
.It
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 Getting to the Open Firmware Prompt on Older Models
.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
.Dq Li "DEFAULT CATCH!"
.Pp
If your machine is Open Firmware version 1.0.5 or 2.X, 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. 
.Pp
Otherwise, if you are not using a serial
console, there might be a conflict between the screen driver and Open
Firmware which prevents Open Firmware from loading
.Pa ofwboot.xcf
There are several models that cannot be booted while
using the screen and keyboard. The only known workaround is to use a serial
console (i.e. set your input and output devices to ttya or ttyb).
.Pp
.Dl 0 > Ic "setenv output-device ttya"
.Dl 0 > Ic "setenv input-device ttya"
.Dl 0 > Ic "reset-all"
.It
.Dq Li "CLAIM failed"
.Pp
This is a general message from Open Firmware to the effect that it failed
to allocate some memory. There are several known causes for this to happen.
.Pp
This often means that the memory is messed up. If you tried something and
it failed, then you tried another and got a
.Dq Li "CLAIM failed"
message, then this is an indication that you should reboot between attempts
.Pp
If your machine is Open Firmware version 1.0.5 or 2.X, this error does
sometimes appear randomly. You might try the boot command a second time (this
is known to work on some models). Otherwise, if you are not using a serial
console, there might be a conflict between the screen driver and Open
Firmware which prevents Open Firmware from loading
.Pa ofwboot.xcf
There are several models that cannot be booted while using the screen and
keyboard. The only known workaround is to use a serial console
(i.e. set your input and output devices to ttya or ttyb).
.Pp
.Dl 0 > Ic "setenv output-device ttya"
.Dl 0 > Ic "setenv input-device ttya"
.Dl 0 > Ic "reset-all"
.It
.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.
.It
.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
.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
filesystem on it (such as a hybrid CD-R or a hard drive with MacOS
partitions).
.It
.Dq Li "TFTP timeout"
.Pp
If you're trying to netboot an older system (such as a PowerMacintosh 7500), 
Open Firmware seems to have a netboot bug, we have found no workarounds 
yet.  If you're netbooting a newer system, then you may not have TFTP set
up properly on your tftpd server.
.It
.Pa ofwboot.xcf
hangs before the copyright notice and the kernel configuration
.Pp
You forgot to set
.Dq Li real-base
in Open Firmware or it got erased by your booting into
.Tn MacOS .
.Pp
.Dl 0 > Ic "setenv load-base 600000"
.Dl 0 > Ic "setenv real-base F00000"
.Dl 0 > Ic "reset-all"
.It
After the kernel loads, the first key you press repeats forever
.Pp
Press the
.Key SHIFT
key first.
.It
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).  
.Pp
This is also a known problem on some PowerMacintosh G3 (Blue and
White) and iMac (Bondi Blue) machines.  If you have a
PowerMacintosh G3 (Blue and White) with this problem, then you can try the
following procedure:
.(enum
Unplug the USB keyboard and plug in an ADB keyboard
.It
Boot 
.Nx
with the ADB keyboard 
.It
Enter root, swap and filesystem responses on the ADB keyboard 
.It
When the system gets to the shell prompt (or login if you went
multi-user), unplug the ADB and plug in the USB keyboard 
.enum)
.Pp
The USB will be usable at this point and you can use the system. You'll
notice that the ADB is dead even before you unplugged it. Also you MUST
boot without the USB installed or this won't work. 
.Pp
Alternatively, much as it pains us to say this, 
.Nx
1.4.3 works fine on both the iMac (Bondi Blue) and the PowerMacintosh G3
(Blue and White) models and does not have this USB keyboard problem. 
.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
.
Now, you can reboot to get to the Open Firmware prompt.  Once there, you
can set Open Firmware to always boot into 
.Nx
from the media of your choice.  First, make sure you know what command you
need to boot (see above).  If you are using a 
.Sq "partition zero"
style boot scheme, you would type something like the following:
.Pp
.Dl 0 > Ic "setenv auto-boot? true"
.Dl 0 > Ic "setenv boot-device scsi/sd@0:0"
.Dl 0 > Ic "setenv boot-file netbsd"
.Dl 0 > Ic "reset-all"
.Pp
The last command resets the system so that these settings are stored.
Replace
.Ic scsi/sd@0:0
with the actual device you will be booting from.  If you find that your
system tries booting before your hard drive has spun up, you may need to
also enter something like:
.Pp
.Dl 0 > Ic "setenv boot-command begin ['] boot catch 1000 ms cr again"
.Pp
If you are not using a
.Sq "partition zero"
style boot scheme, then you can still plug in all the information you
need:
.Pp
.Dl 0 > Ic "setenv auto-boot? true"
.Dl 0 > Ic "setenv boot-device ide0/disk@0:8,ofwboot.xcf"
.Dl 0 > Ic "setenv boot-file ide0/disk@0:13,/netbsd"
.Dl 0 > Ic "setenv boot-command boot"
.Dl 0 > Ic "reset-all"
.Pp