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

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

details:   https://anonhg.NetBSD.org/src/rev/b61be8ca3041
branches:  netbsd-1-5
changeset: 492917:b61be8ca3041
user:      he <he%NetBSD.org@localhost>
date:      Wed Mar 06 21:30:02 2002 +0000

description:
Pull up revision 1.18 (requested by mbw):
  Various fixes:
   o Significant fixes/rework for macppc section:
     - Tweak ``Quick install'' section for macppc
     - OpenFirmware boot syntax section
     - Update/correct description of boot problems
     - Mention de0 as macppc possible interface
     - Other improvements and fixes
   o Add recently added developers
   o Formatting and spelling fixes

diffstat:

 distrib/notes/macppc/install |  676 ++++++++++++++++++++++++++++++------------
 1 files changed, 486 insertions(+), 190 deletions(-)

diffs (truncated from 922 to 300 lines):

diff -r f13e20e8a8ea -r b61be8ca3041 distrib/notes/macppc/install
--- a/distrib/notes/macppc/install      Wed Mar 06 21:29:42 2002 +0000
+++ b/distrib/notes/macppc/install      Wed Mar 06 21:30:02 2002 +0000
@@ -1,92 +1,323 @@
-.\"    $NetBSD: install,v 1.2.10.12 2002/01/05 18:30:48 he Exp $
+.\"    $NetBSD: install,v 1.2.10.13 2002/03/06 21:30:02 he 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:
+.Lk http://www.netbsd.org/Ports/macppc/faq.html#partitions
 .Pp
-.Dl boot scsi_devalias/sd@i:p
+Typically, MS-DOS and ISO9660 formatted disks have their filesystems at
+partition 1.  Typically, Drive Setup formatted disks have their
+filesystems starting at partition number 9.  Often, if you omit the
+partition number, Open Firmware looks in the first partition it
+understands holding a valid filesystem.
+.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
+filesystem on a CD-ROM in the example PowerMacintosh 7300 system, you'd
+use:
+.Li scsi-int/sd@3:,\e
 .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)
+Now, to confirm that you and Open Firmware are looking at the same files,
+you can get a directory listing of the filesystem on your device with the
+.Ic dir
+command.  This command is only useful with filesystems 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 filesystems.  On Open Firmware 2.4, you