[src/trunk]: src/distrib/notes This is a complete refit of the mac68k documen...

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

details:   https://anonhg.NetBSD.org/src/rev/2b0ffd9ead3f
branches:  trunk
changeset: 534163:2b0ffd9ead3f
user:      scottr <scottr%NetBSD.org@localhost>
date:      Fri Jul 19 07:17:45 2002 +0000

description:
This is a complete refit of the mac68k documentation.

Of particular note is documentation on the new preferred method of
installation using sysinst, provided (and updated) by Bob Nestor.

diffstat:

 distrib/notes/common/contents    |  113 +++++++++-
 distrib/notes/common/donations   |    3 +-
 distrib/notes/common/main        |   19 +-
 distrib/notes/common/postinstall |   25 +-
 distrib/notes/common/sysinst     |  439 ++++++++++++++++++++++++++++++++++++--
 distrib/notes/common/upgrade     |    6 +-
 distrib/notes/common/xfer        |    4 +-
 distrib/notes/mac68k/contrib     |   18 +-
 distrib/notes/mac68k/hardware    |   92 ++++---
 distrib/notes/mac68k/install     |  221 +++++++++---------
 distrib/notes/mac68k/legal       |    6 +-
 distrib/notes/mac68k/prep        |  130 +++++++---
 distrib/notes/mac68k/upgrade     |  287 ++-----------------------
 distrib/notes/mac68k/whatis      |   11 +-
 distrib/notes/mac68k/xfer        |   81 ++++--
 15 files changed, 914 insertions(+), 541 deletions(-)

diffs (truncated from 2305 to 300 lines):

diff -r 7be5d91ddf88 -r 2b0ffd9ead3f distrib/notes/common/contents
--- a/distrib/notes/common/contents     Fri Jul 19 03:22:09 2002 +0000
+++ b/distrib/notes/common/contents     Fri Jul 19 07:17:45 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: contents,v 1.69 2002/07/19 02:28:09 lukem Exp $
+.\"    $NetBSD: contents,v 1.70 2002/07/19 07:17:45 scottr Exp $
 .\"
 .\" Copyright (c) 1999-2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -136,6 +136,14 @@
 .Li INSTALL
 that has MCA stuff enabled to allow installing on IBM PS/2 machines.
 .\}
+.if r_mac68k \{\
+.                      It Pa netbsd-GENERIC.gz
+A kernel containing code for everything supported in this release using
+the standard SCSI driver.
+.                      It Pa netbsd-GENERICSBC.gz
+A kernel containing code for everything supported in this release using
+the SBC variant of the SCSI driver.
+.\}
 .if r_macppc \{\
 .                      It Pa netbsd.GENERIC_MD.gz
 A gzipped
@@ -232,6 +240,11 @@
 this image.
 .\}
 .
+.if r_mac68k \{\
+.              It Pa instkernel/
+\*M boot and installation kernels; see installation section (Sysinst
+Method), below.
+.\}
 .if \n[amiga]:\n[atari]:\n[hp300]:\n[mvme68k]:\n[sparc]:\n[sparc64]:\n[sun2]:\n[sun3] \{\
 .              It Pa miniroot/
 \*M miniroot file system image; see below.
@@ -257,6 +270,9 @@
 .\}
 .el \{\
 Miscellaneous \*M installation utilities; see
+.if r_mac68k \{\
+the Traditional method
+.\}
 installation section, below.
 \}
 .\}
@@ -477,7 +493,7 @@
 .el .ie r_hpcsh .setsize 17 55
 .el .ie r_i386 .setsize 15 54
 .el .ie r_luna68k .setsize 14 52
-.el .ie r_mac68k .setsize 14 52
+.el .ie r_mac68k .setsize 14 53
 .el .ie r_macppc .setsize 17 64
 .el .ie r_mipsco .setsize 17 73
 .el .ie r_mvme68k .setsize 14 52
@@ -529,7 +545,7 @@
 .el .ie r_vax .setsize 3 7
 .el .setsize ??? ???
 .
-.if !\n[atari]:\n[walnut]:\n[sgimips] \{\
+.if !\n[atari]:\n[mac68k]:\n[sgimips]:\n[walnut] \{\
 .It Sy kern-GENERIC
 This set contains a
 .Nx*M
@@ -556,7 +572,6 @@
 .el .ie r_hpcsh .setsize 1 2
 .el .ie r_i386 .setsize 3 6
 .el .ie r_luna68k .setsize 1 2
-.el .ie r_mac68k .setsize 2 3
 .el .ie r_macppc .setsize 2 5
 .el .ie r_mvme68k .setsize 1 2
 .el .ie r_netwinder .setsize 2 3
@@ -600,6 +615,28 @@
 install this distribution set.
 .setsize 3 7
 .\}
+.if r_mac68k \{\
+.It Sy kern-GENERIC
+This set contains a
+.Nx*M
+\*V
+.Li GENERIC
+kernel, named
+.Pa /netbsd .
+.No You Em must
+install either this distribution set or kern-GENERICSBC.
+.setsize 1 3
+.It Sy kern-GENERICSBC
+This set contains a
+.Nx*M
+\*V
+.Li GENERICSBC
+kernel, named
+.Pa /netbsd .
+.No You Em must
+install either this distribution set or kern-GENERIC.
+.setsize 1 3
+.\}
 .if r_walnut \{\
 .It Sy kern-WALNUT
 This set contains a
@@ -768,9 +805,10 @@
 .
 .if r_mac68k \{\
 .It Sy xserver
-The Xmac68k Em monochrome
+The Xmac68k
+.Em monochrome
 server with man pages.
-.setsize ??? ???
+.setsize 1 3
 .\}
 .
 .if r_macppc \{\
@@ -1165,7 +1203,7 @@
 .
 .if r_mac68k \{\
 .Pp
-Additional kernels to those included in the distribution sets may be found
+Kernels suitable for booting from an AppleShare server may be found
 in the
 .Pa mac68k/binary/kernels
 subdirectory of the
@@ -1173,11 +1211,13 @@
 distribution tree.
 These kernels are generally named something like
 .Pa netbsd-GENERIC.gz
-or some other suitable name.
+and can be booted as-is by the
+.Nx*M
+Booter utility, if desired.
 Please note that these kernels are simply gzipped and are not in tar archives.
 .Pp
 The
-.Tn MacOS
+.Tn Mac OS
 based utilities necessary for installing and running
 .Nx
 can
@@ -1196,7 +1236,7 @@
 This program is used to boot the
 .Nx
 kernel from within
-.Tn MacOS .
+.Tn Mac OS .
 .br
 .Em 141 KB archived
 .It Pa Installer.sea.hqx
@@ -1206,6 +1246,11 @@
 This program is used to install the distribution sets onto your
 .Nx
 partition(s).
+This utility is used only in a Traditional method
+installation; it is not used or required for an installation using
+the
+.Ic sysinst
+method.
 .br
 .Em 147 KB archived
 .It Pa Mkfs.sea.hqx
@@ -1213,15 +1258,21 @@
 This program is used to format your chosen partitions so that they
 can be used with
 .Nx .
+This utility is used only in a Traditional method
+installation; it is not used or required for an installation using
+the
+.Ic sysinst
+method.
 .br
 .Em 76 KB archived
 .tag)
 .Pp
-These files are all binhexed, self-extracting archives.
+These files are all BinHexed, self-extracting archives.
 If you need them, the sources for these utilities are in the
 .Pa src
 subdirectory.
 .\}
+This utility is used only in a Traditional method installation.
 .
 .if r_mvme68k \{\
 .Pp
@@ -1230,6 +1281,46 @@
 .
 .(tag miniroot/
 .It Pa miniroot/
+.(Note
+The
+.Ic sysinst
+method of installation is the preferred method for installing
+.Nx*M .
+.Em The Traditional method of installation is deprecated
+.Em and will be removed in a future release.
+Some other important differences between the two installation methods are:
+.(bullet
+The Installer and Mkfs utilities are not used if the installation is done
+using the
+.Ic sysinst
+method via booting an Installation Kernel.
+.It
+Mkfs creates a 4.3BSD "old" format file system.  This is the only
+file system format understood by the Installer. The
+.Ic sysinst
+process creates "new" file systems which can't be processed by Mkfs
+or the Installer.
+.It
+The Installer (and probably Mkfs) is known to have problems with
+BSD file systems that are larger than 1 GB or extend beyond the 1 GB
+physical limit.  Keep this in mind if doing a Traditional method
+installation with these utilities.
+.It
+The Booter is known to have problems booting from a NetBSD file system
+if the inode of the kernel file is to large.  For large disks it is
+advisable to have a small root partition and one or more usr-type partitions
+for other files.  This ensures the inode of the kernel in the root file system
+will be small.
+.It
+The Booter is designed to work with 4.3BSD "old" file systems, but there
+are enough similarities between the "old" and "new" file system formats in the
+first few hundred blocks that the Booter can usually boot a Kernel from a
+4.3BSD new file system.  If you choose to use "new" file system formats,
+it is advisable to use a small root partition and one or more usr-type
+partitions for other files.  This is the default layout used by
+.Ic sysinst .
+.bullet)
+.Note)
 .      (tag miniroot.gz
 .      It Pa miniroot.gz
 A copy of the miniroot file system.
diff -r 7be5d91ddf88 -r 2b0ffd9ead3f distrib/notes/common/donations
--- a/distrib/notes/common/donations    Fri Jul 19 03:22:09 2002 +0000
+++ b/distrib/notes/common/donations    Fri Jul 19 07:17:45 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: donations,v 1.23 2002/06/27 15:05:42 lukem Exp $
+.\"    $NetBSD: donations,v 1.24 2002/07/19 07:17:46 scottr Exp $
 .\"
 .\" Copyright (c) 1999-2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -88,6 +88,7 @@
 Jason R. Thorpe
 Steve Wadlow
 Krister Walfridsson
+Rob Windsor
 Jim Wise
 Reinoud Zandijk
 Christos Zoulas
diff -r 7be5d91ddf88 -r 2b0ffd9ead3f distrib/notes/common/main
--- a/distrib/notes/common/main Fri Jul 19 03:22:09 2002 +0000
+++ b/distrib/notes/common/main Fri Jul 19 07:17:45 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: main,v 1.199 2002/07/16 00:31:44 lha Exp $
+.\"    $NetBSD: main,v 1.200 2002/07/19 07:17:46 scottr Exp $
 .\"
 .\" Copyright (c) 1999-2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -235,9 +235,9 @@
 At present,
 .Nx*M
 cannot exist on the same hard drive as
-.Tn MacOS
+.Tn Mac OS
 unless you partition your disk using a
-.Tn MacOS
+.Tn Mac OS
 partitioning utility.
 Open Firmware versions prior to 3 cannot boot into
 .Nx
@@ -246,7 +246,7 @@
 Open Firmware version 3 cannot boot into
 .Nx
 on a drive partitioned with the installation tools, you must use a
-.Tn MacOS
+.Tn Mac OS
 partitioning utility and the
 .Dq Me "Re-install sets or install additional sets"
 option in the installer (selecting the
@@ -463,7 +463,7 @@
 buffer cache to use all available RAM (if not otherwise used!) and
 improves overall system performance.
 .It
-Road-robin page colouring implemented for various ports for better
+Round-robin page colouring implemented for various ports for better
 cache utilisation, more deterministic run-time behaviour, and faster
 program execution.
 .It
@@ -475,8 +475,9 @@
 .It
 A new pipe implementation with significantly higher performance
 due to lower overheads, which uses the UVM Page Loan facility.
+.if !\n[mac68k] \{\
 .It
-New boot flags
+New boot loader flags
 .Fl v
 .Pq Em bootverbose
 and
@@ -489,6 +490,7 @@
 activated with the
 .Fl c