[src/netbsd-1-5]: src/distrib/notes/macppc Pull up revision 1.11 (requested b...

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

details:   https://anonhg.NetBSD.org/src/rev/8292b65e3895
branches:  netbsd-1-5
changeset: 491331:8292b65e3895
user:      he <he%NetBSD.org@localhost>
date:      Mon Apr 23 22:22:20 2001 +0000

description:
Pull up revision 1.11 (requested by mbw):
  Update to the macppc install documentation; OpenFirmware parts
  reorganized and other changes.

diffstat:

 distrib/notes/macppc/prep |  590 +++++++++++++++++++++++++++++++++------------
 1 files changed, 432 insertions(+), 158 deletions(-)

diffs (truncated from 842 to 300 lines):

diff -r 03a07ef00624 -r 8292b65e3895 distrib/notes/macppc/prep
--- a/distrib/notes/macppc/prep Mon Apr 23 22:22:07 2001 +0000
+++ b/distrib/notes/macppc/prep Mon Apr 23 22:22:20 2001 +0000
@@ -1,8 +1,38 @@
-.\"    $NetBSD: prep,v 1.2.8.5 2000/11/05 01:25:12 tv Exp $
+.\"    $NetBSD: prep,v 1.2.8.6 2001/04/23 22:22:20 he Exp $
+.
+.Ss2 Gather Information
+.
+Go to the
+.Nx*M
+Model Support webpage and look up your system. Take note of the comments
+about your model and keep these in mind during the rest of this 
+installation
+procedure.
+.Lk http://www.netbsd.org/Ports/macppc/models.html
+.Pp
+Also, you 
+.Em must
+know what version of Open Firmware is in the machine you will be 
+installing
+.Nx*M
+onto.  The instructions that follow will make absolutely no sense
+if you follow directions for a version of Open Firmware other than
+the one on your machine.
+.Pp
+If the instructions in a subsection below do not apply to 
+.Em all
+versions of Open Firmware, there will be a line listing which versions of
+Open Firmware they apply to, such as:
+.br
+(Open Firmware 1.0.5, Open Firmware 1.1.22, Open Firmware 2.0.x, Open 
+Firmware 2.4, Open Firmware 3)
 .
 .Ss2 Open Firmware System Preparation
 .
-Most \*M systems have Open Firmware bugs. Luckily, Open Firmware has a small
+(Open Firmware 1.0.5, Open Firmware 2.0.x, Open Firmware 2.4)
+.Pp
+All pre-Open Firmware 3 \*M systems have Open Firmware bugs. Luckily, Open 
+Firmware has a small
 Non-Volatile RAM variable (NVRAM) which is reserved for FORTH commands which
 will be run before booting an operating system. Apple has released a freeware
 .Tn MacOS
@@ -10,7 +40,10 @@
 most of these bugs. We
 .Em strongly
 recommend that you use this tool to patch your Open Firmware,
-as several systems cannot boot without these patches.
+as several systems cannot boot without these patches.  If you read
+the Model Support page, you'd also know that some models are broken by
+or are unsupported by System Disk.  If you are trying to install on such
+a model, then skip the rest of this section.
 .Pp
 Download System Disk from Apple's site:
 .Lk ftp://ftp.apple.com/developer/macosxserver/utilities/SystemDisk2.3.1.smi.bin
@@ -32,6 +65,8 @@
 .
 .Ss2 Updating your firmware
 .
+(Open Firmware 3)
+.Pp
 Open Firmware 3 systems have a rewritable firmware. Go to the
 .Sq Apple Software Updates
 web site at
@@ -39,29 +74,127 @@
 and search for
 .Sq firmware
 and install the most recent version for your model.
+.Pp
+.(Note
+The most recent versions available (4.1.7 and 4.1.8) as of April 2001 are
+known to have some problems.  Some PowerBook G4 users find they are
+unable to boot 
+.Nx
+after upgrading, and some PowerMacintosh users find that their third-party 
+RAM has been disabled.  See the discussion at
+.Lk http://www.macfixit.com/archives/april.01.a.shtml#firm-04-07
+.Note)
+.Pp
 .
-.Ss2 Getting to the Open Firmware Prompt
+.Ss2 Getting to the Open Firmware Prompt on Newer Models
+.
+(Open Firmware 3)
+.Pp
+Hold down a special key combination when your system boots.
+.Pp
+After the chime starts, but before it stops, hold down the
+.Key COMMAND-OPTION-O-F
+keys (the
+.Key COMMAND
+key looks like a four-leaf clover or an open apple, and the
+.Key OPTION
+key may look like a two-way switch with four straight line segments).
+.Pp
+You should now see the Open Firmware command prompt:
+.Pp
+.Dl 0 >
+.Pp
+Now, set your system to always stop at the Open Firmware prompt.
+.Pp
+.Dl 0 > Ic "setenv auto-boot? false
+.Pp
+To undo this, and allow Open Firmware to automatically boot the specified 
+operating system when the system is rebooted, type:
+.Pp
+.Dl 0 > Ic "setenv auto-boot? true
+.Pp
+Skip down to the section on
+.Sx Setting up Open Firmware 3 to boot NetBSD
+since the next several pages are instructions for older models.
+.Pp
 .
-There are various methods to get to the Open Firmware prompt. They may
-or may not work, depending on which system model you have.  Most models
-can use the on-board video and an ADB or USB keyboard to access Open
-Firmware.  Those that cannot must use a serial console.  Likewise, most
-systems can be set up to use a serial console if you do not wish to use
-the on-board video.
+.Ss2 Getting to the Open Firmware Prompt on Apple Network Servers
+.
+(Open Firmware 1.1.22)
+.Pp
+Hold down a special key combination when your system boots.
+.Pp
+After the chime starts, but before it stops, hold down the
+.Key COMMAND-OPTION-O-F
+keys (the
+.Key COMMAND
+key looks like a four-leaf clover or an open apple, and the
+.Key OPTION
+key may look like a two-way switch with four straight line segments).
+.Pp
+You should now see the Open Firmware command prompt:
+.Pp
+.Dl 0 >
+.Pp
+Your screen remains black, since the version of Open Firmware in the
+Apple Network Servers can only use a serial console.
+You must hook up a serial console
+(38400 bps, 8 bits, no parity, 1 stop bit, no handshaking) to 
+.Sq Port 2
+(the
+.Sq Li ttya
+device in Open Firmware).
+.Pp
+Now, set your system to always stop at the Open Firmware prompt.
+.Pp
+.Dl 0 > Ic "setenv auto-boot? false
+.Pp
+To undo this, and allow Open Firmware to automatically boot the specified 
+operating system when the system is rebooted, type:
+.Pp
+.Dl 0 > Ic "setenv auto-boot? true
+.Pp
+Skip down to the section on
+.Sx Setting up pre-Open Firmware 3 to boot NetBSD
+since the next several pages are instructions for MacOS models.
+.Pp
+.
+.Ss2 Getting to the Open Firmware Prompt on Older Models
+.
+(Open Firmware 1.0.5, Open Firmware 2.0.x, Open Firmware 2.4)
+.Pp
+These models are significantly trickier than the newer machines.
 .Pp
 Open Firmware has two variables,
 .Sq input-device
 and
 .Sq output-device No Ns ,
-which specify which devices to use for input and output.  Most early models
-(Open Firmware versions 1.x and 2.0.x) will default to using a serial
-console.  The later models (Open Firmware versions 2.4 and 3) will default
-to using the on-board video and keyboard.  The instructions below describe
-how to set your system up to access Open Firmware from the on-board video 
-and keyboard.
+which specify which devices to use for input and output.  
+.Pp
+All Open Firmware 1.0.5 and most Open Firmware 2.0.x systems will default 
+to using the 
+.Sq Modem
+serial port for the console instead of the ADB keyboard and the monitor
+attached to the on-board video.
+Unless you use a MacOS-based utility to set 
+these variables correctly, you 
+.Em will
+need to hook up a serial console temporarily to set them before you 
+can use your keyboard and screen.
 .Pp
-If, for some reason, you need to use a serial console, you can use a
-normal 
+Now would be a good time to look at the 
+.Nx*M
+Model Support webpage to determine the issues with your model.
+.Lk http://www.netbsd.org/Ports/macppc/models.html
+.Pp
+In particular, some models 
+.Em must
+use a serial console, or they will be unable to boot
+.Nx
+at all.  All models can be set to use a serial console, if you desire
+to bypass the keyboard and screen.
+.Pp
+If you need to use a serial console, you can use a normal 
 .Sq printer
 cable (mini-DIN 8 to mini-DIN 8) and a 
 .Tn MacOS
@@ -73,8 +206,10 @@
 system.
 .Lk http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/comm/term/zterm-101.hqx
 .
-.Ss2 Getting to the Open Firmware Prompt (Easy method using MacOS)
+.Ss2 Getting to the Open Firmware Prompt (Recommended method using MacOS)
 .
+(Open Firmware 1.0.5, Open Firmware 2.0.x, Open Firmware 2.4)
+.Pp
 Launch the
 .Tn MacOS
 System Disk tool. Click on
@@ -123,21 +258,23 @@
 .
 .Ss2 Getting to the Open Firmware Prompt (Harder method using MacOS)
 .
-If System Disk doesn't work because your version of
+(Open Firmware 1.0.5, Open Firmware 2.0.x, Open Firmware 2.4)
+.Pp
+If System 
+Disk doesn't work because your version of
 .Tn MacOS
 is too old or because
 System Disk says that it doesn't support your model, then you may try using
 the 
 .Tn MacOS
-BootVars tool on your Open Firmware 1 or 2 system (it will crash 
-Open Firmware 3 systems).
+BootVars tool.
 .Pp
 .Lk ftp://ftp.netbsd.org/pub/NetBSD/arch/macppc/macos-utils/bootvars/bootvars.sit.hqx
 .(Note
 BootVars does
 .Em not
 apply the (possibly critical) NVRAM patches that System Disk does.
-Expect devices to not work.
+Expect some devices to not work.
 .Note)
 .Pp
 Look up the proper
@@ -172,7 +309,7 @@
 box. 
 Click on the
 .Dq write
-button, and restart.
+button, and then reboot your system.
 .Pp
 If your
 .Sq output-device
@@ -201,14 +338,17 @@
 .
 .Ss2 Getting to the Open Firmware Prompt (Without using MacOS)
 .
-If you don't have
+(Open Firmware 1.0.5, Open Firmware 2.0.x, Open Firmware 2.4)
+.Pp
+If you don't 
+have
 .Tn MacOS ,
 then you need to hold down a special key combination when your system boots.
 .(Note
-Your Open Firmware 1 or 2 system will
+Your system will
 .Em not
 have the (possibly critical) NVRAM patches that System Disk applies.
-Expect devices to not work.
+Expect some devices to not work.
 .Note)
 .Pp
 After the chime starts, but before it stops, hold down the
@@ -229,18 +369,12 @@
 Disk tool to set up Open Firmware. You must hook up a serial console
 (38400 bps, 8 bits, no parity, 1 stop bit, no handshaking).
 .Pp
-The Apple Network Server uses
-.Sq Port 2
-(the
-.Sq Li ttya
-device in Open Firmware) as the console port.
-.Pp
 Now, set your system to always stop at the Open Firmware prompt.
 .Pp
 .Dl 0 > Ic "setenv auto-boot? false
 .Pp
-To allow Open Firmware to automatically boot the specified operating
-system when the system is booted, type:
+To undo this, and allow Open Firmware to automatically boot the specified 
+operating system when the system is rebooted, type:
 .Pp
 .Dl 0 > Ic "setenv auto-boot? true
 .Pp
@@ -272,10 +406,12 @@