[src/trunk]: src/distrib/notes/macppc Medium-scale overhaul.

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

details:   https://anonhg.NetBSD.org/src/rev/70a13fdcd36d
branches:  trunk
changeset: 520114:70a13fdcd36d
user:      mbw <mbw%NetBSD.org@localhost>
date:      Thu Jan 03 03:52:14 2002 +0000

description:
Medium-scale overhaul.

macppc/hardware
Forgot to put PowerComputing PowerCenter in list of models that can't use
 on-board video

macppc/prep
Reword four-key-combo c-o-O-F to imply you need to hold all four down
 until the 0 > prompt appears, also a better description of the keys
shuffle System Disk instructions around a little to make more sense
Fix BootVars instruction to "uncheck auto-boot?"
Change '.Dl 0 \*> Ic "..."' to '.No 0 \*> Ic "..."' surrounded by .(disp
Link to new FAQ entries (such as how to use the Open Firmware environment
 and instruction for people unfamiliar with MacOS)
Describe how to prepare an MS-DOS filesystem for booting
Be more consistent about "ISO9660"
The NetBSD/macppc boot CD-R image has "partition zero" bootloader and
 XCOFF bootloader to work on all models -- this is described better now
Better info on how to netboot OF 1.0.5 systems
Mention that UFS is not currently supported by NetBSD and MacOS < 10
Detab the dhcpd.conf example
Add .To 2 tags for preparation of bootable media subsections

macppc/install
Change '.Dl 0 \*> Ic "..."' to '.No 0 \*> Ic "..."' surrounded by .(disp
Added new and very very useful "Open Firmware boot syntax" section
 describing how to determine the OF boot-device and boot-file
Clean up examples of boot commands
Update descriptions of booting problems (some were incorrect)
Add .To 2 tags for OF boot command subsections and common problems

diffstat:

 distrib/notes/macppc/hardware |   11 +-
 distrib/notes/macppc/install  |  676 ++++++++++++++++++++++++++++++-----------
 distrib/notes/macppc/prep     |  665 +++++++++++++++++++++++++----------------
 3 files changed, 898 insertions(+), 454 deletions(-)

diffs (truncated from 2181 to 300 lines):

diff -r 12f976368607 -r 70a13fdcd36d distrib/notes/macppc/hardware
--- a/distrib/notes/macppc/hardware     Thu Jan 03 03:32:10 2002 +0000
+++ b/distrib/notes/macppc/hardware     Thu Jan 03 03:52:14 2002 +0000
@@ -1,4 +1,4 @@
-.\"$NetBSD: hardware,v 1.20 2001/08/17 07:04:42 mbw Exp $
+.\"$NetBSD: hardware,v 1.21 2002/01/03 03:52:14 mbw Exp $
 .
 Currently,
 .Nx*M
@@ -192,7 +192,7 @@
 .Pq Em gm0
 .It
 Apple PCI Ethernet Card (option for Apple Network Server)
-.Pq Em tlp
+.Pq Em de
 .It
 Asante Mac 10/100 PCI Rev A, part number 09-00169-01
 .Pq Em de
@@ -325,7 +325,8 @@
 Several models have been reported to not work with
 .Nx
 if the on-board video is in use, such as the Performa 54xx, 6360, 6400,
-PowerComputing PowerTower, and UMAX C600 and Apus 3000.  Also, the video
+PowerComputing PowerCenter and PowerTower, and UMAX C600 and Apus 3000.  
+Also, the video
 card that shipped with the PowerMacintosh 9500/150, 9500/180, and 9500/200
 systems is reported to have the same problem.
 .Note)
@@ -468,8 +469,8 @@
 Each version of Open Firmware supports different devices and media that you
 may boot from.  We define the terms
 .Dq "bootable media"
-as the media (hard drive, CD-R, ethernet) that will be used to bootstrap
-your \*M system into
+as the media (hard drive, floppy, CD-R, ethernet) that will be used to
+bootstrap your \*M system into
 .Nx No Ns ,
 and
 .Dq "distribution sets"
diff -r 12f976368607 -r 70a13fdcd36d distrib/notes/macppc/install
--- a/distrib/notes/macppc/install      Thu Jan 03 03:32:10 2002 +0000
+++ b/distrib/notes/macppc/install      Thu Jan 03 03:52:14 2002 +0000
@@ -1,92 +1,323 @@
-.\"    $NetBSD: install,v 1.17 2002/01/02 21:12:17 he Exp $
+.\"    $NetBSD: install,v 1.18 2002/01/03 03:52:15 mbw Exp $
 .
-.Ss2 Booting the installer
+.Ss2 Open Firmware boot syntax
 .
 The syntax of the Open Firmware
 .Ic boot
 command is:
 .Pp
-.Dl boot device[:partition][,filename] [kernel_location] [-as]
+.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
-where the
+You use the
+.Li boot-device
+to tell Open Firmware where to find
+.Xr ofwboot 7 
+by listing the device, the partition (if it's a disk), and the filename 
+of the bootloader (if using
+.Pa ofwboot.xcf No Ns ).
+.Pp
+If the
+.Li boot-file
+is on the same device and (if it's a disk) partition 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.
-.Pa ofwboot.xcf
-will ask where the kernel is, or the kernel will ask where the root
-file system is).
+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
-.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.
+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 No 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 filesystem).
+.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 \*> Ic "dev /"
+.No 0 \*> Ic "ls"
+.disp)
 .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:
+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
-.Dl 0 \*> Ic devalias
+.(disp
+.No 0 \*> 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 Dl hd Ta No "internal hard drive"
+.It Ta Dl cd Ta No "CD-ROM drive"
+.It Ta Dl zip Ta No "internal Zip drive"
+.It Ta Dl enet Ta No ethernet
+.It Ta Dl fd Ta No "floppy drive"
+.It Ta Dl scsi Ta No "SCSI bus"
+.It Ta Dl scsi-int Ta No "internal SCSI bus (on systems with multiple SCSI busses)"
+.It Ta Dl scsi-ext Ta No "external SCSI bus (on systems with multiple SCSI busses)"
+.It Ta Dl ata Ta No "ATA/IDE bus"
+.It Ta Dl ideN Ta No "ATA/IDE bus number N"
+.It Ta Dl ultraN Ta No "Ultra/66 or Ultra/100 IDE bus number N"
+.El
 .Pp
-To get a complete listing of what hardware is recognized by Open
-Firmware, type:
+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 \*> Ic "dev scsi-int"
+.No 0 \*> 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
-.Dl 0 \*> Ic dev / ls
+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 \*> Ic "dev scsi-int"
+.No 0 \*> 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
-.Dl 0 \*> Ic dev /path/to/device words
+.(disp
+.No 0 \*> Ic dev scsi-int/sd@3
+.No 0 \*> 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 Li Dq open
+is present in the list, then the device is almost certainly bootable.
 .Pp
-If
-.Sq open
-is in the list of words, then this device might be bootable.
+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
-.(Note
-SCSI disks are usually of the form:
+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.x and earlier.  See the FAQ for an explanation: