BSD/mac68k Booter Manual
|
|
Version 8, 30th June 1998. For Booter 1.11.3
Index of Topics
The BSD/mac68k Booter is a Mac OS application which boots the NetBSD/mac68k
(and OpenBSD/mac68k) operating system.
NetBSD/mac68k, also known as MacBSD, is a port of the UNIX-like operating
system NetBSD to the Motorola 680x0 processor-based family of Macintosh
computers. For more general information on NetBSD/mac68k, point your web
browser at any of the following sites...
Some NetBSD/mac68k Web Sites
-
http://www.NetBSD.org/ports/mac68k
The area of the main NetBSD web site dedicated to the mac68k port.
http://www.MacBSD.com/macbsd
The MacBSD web site, including more mac68k port-specific information.
The 'port-mac68k' mailing list
-
If you like NetBSD/mac68k and/or use it, you should subscribe to the mac68k
port mailing list,
port-mac68k@NetBSD.org.
You can subscribe the port-mac68k list on the NetBSD Mailing Lists
web page, or by sending mail to
majordomo@NetBSD.org
with no subject and the single-line message:
subscribe port-mac68k
and send back the authentication mail you'll get.
The minimum hardware configuration includes a 68020 with a 68851 PMMU chip
or a 68030 or better processor, without which the Booter will refuse to
start. The Booter has been tested recently under System 7.1 and 7.5 (both
minimal and full installs), but it should work under any System 7 setup.
System 6.0.x is not supported because the Booter requires the machine to be
booted in 32-Bit Addressing mode. The Booter also will certainly fail if
Virtual Memory is enabled, so turn that off too while you're snooping around
in the Memory control panel.
The Macintosh models that are supported to some extent by NetBSD/mac68k vary
on what seems to be a daily basis sometimes. Check the web sites, and especially the user survey
contained therein, for more information.
First and foremost you must have formatted and partitioned a drive for A/UX,
and run Mkfs, and downloaded and installed at least the base package and a
kernel. If you haven't done this, you should visit the above Web sites for more information.
Assuming you have enough of Unix (and Mac OS!) installed, here is how to boot
it:
- Open the BSD/mac68k Booter from the Mac OS. A window will appear
entitled 'BSD/mac68k Launch'. The default Booter settings should work
for most Macs, although if your A/UX partitioned drive is not at SCSI
ID 0, then you will need to configure the Booter.
- Choose 'Booting...' from the Options menu to open the main 'Boot
Options' configuration dialog. Configure the boot options in accordance
with your system (the most commonly changed ones will be 'Root SCSI ID'
and 'Kernel Name'). When you have finished, click OK
- You may wish to edit some of the options under 'Serial ports...' if you
want to use the serial console or boot echo features, or if you are
having trouble booting on a machine with interesting serial port
hardware (e.g. PowerBooks). If you want to log debugging
information, you should look in 'Startup...'. All the boot options
available are documented below in
'Boot Options Ad Nauseam'
- After you have configured all the boot options you want, you may wish
to save them for future boots, using the 'Save Options' command under
the File menu
- Now choose 'Boot Now' from the Options menu
First off, the Booter must attempt to open the kernel you've specified. If
you've specified a kernel in your BSD partition, it will take a second to
search for it. Then the Booter will (hopefully) identify the kernel as a
68K executable and print its entry address, which will look similar to this:
MID_M68K executable: entry 0x3356.
(Here, as in the rest of the boot process, the numbers you get may not be
the same as the numbers I get. They are highly kernel-dependent.) Then it
will proceed to load the kernel. As the different sections of the kernel are
loaded, numbers will appear in the status window, which look something like
this:
768400+57532+99064+45588+48244
These numbers correspond to the sizes of the text (executable machine code)
section, the static data section, the bss (uninitialized data) section, the
symbol table, and the string table, respectively. The final message displayed
before the jump to kernel space should be as follows:
Bye-bye...
So I sez to him... The real way
that it should be done is to...
Then the system will act as if it is restarting, and when the restart would
normally happen, the screen will go blank and a short list of memory mappings
will appear, followed by a copyright notice and autoconfiguration information,
which signals that you've booted.
The boot process is not completely machine- and installation-independent.
Therefore, the Booter allows you to set certain options and flags in order
to communicate to the kernel important facts about your machine. Most of
these options are set in the 'Booting' dialog
window, though some are set in the 'Serial
ports...', 'Monitors' and the 'Preferences' dialog windows.
-
Described below are the options that can be set from the 'Booting' dialog
window. In most cases you should be able to boot after modifying only these
options.
Kernel Location: Mac OS file or BSD device
-
The chief purpose of the Booter is to load the BSD operating system
code into memory. This code is called the kernel and is normally
contained in a file called
netbsd. This file is normally in
the root directory of the root partition of your BSD file system. However,
it is also possible to load kernels from the Mac OS file system, such as
when testing new systems, or on systems where SCSI is not yet supported.
This boot option lets you select the location of your kernel; if you
select Mac OS the Booter will look in its own folder for the kernel (or
another folder selected by pressing the 'Set' button). This option should,
as stated above, normally be set to BSD device.
Kernel Name
-
Normally, the kernel is named
netbsd, and that is what you
should enter for the Kernel Name. However, if you are testing a
recently-installed kernel, or simply want to boot an alternate kernel, you
can enter that name here too. Note well, however, that much BSD software
assumes that the kernel is named netbsd and is in the root
directory, so if you have a kernel that works well, you should probably name
it as that.
Partition and Root SCSI ID
-
The Booter needs to know which partition contains your kernel, if you are
booting from the BSD/mac68k file system. You should enter the SCSI ID of
the drive which contains your root partition. If there is no SCSI ID
entered, zero is assumed. By default, the Booter should locate your root
partition. If you have more than one such partition at the selected SCSI
ID, you may want to force it to use one of them by entering the name of
the partition in the Partition Name field (This would be the name which
your disk formatting software gave the partition when you created it
e.g. 'UNIX Root&Usr slice 0', 'NetBSD Root & Usr' or 'A/UX Root').
If you do not enter a name, the Booter tries to guess the correct
partition. The first Unix (i.e. type="Apple_UNIX_SVR2") partition
with 'Root' in the name is its best guess, and if there isn't one of
those, then the first Unix partition which doesn't have 'Swap' in it's
name is its next best.
Enabled?
-
This option will allow systems to boot without a root SCSI ID specified,
e.g. using NFS filesystems. For normal usage you will probably want
to leave this on.
Ask for alternate root/swap?
-
This option allows the user to specify an alternate root or swap device
right before the root partition is mounted. This allows you to, for
example, boot off a kernel on the first SCSI disk (sd0) and specify that
root is on cd0 (a CD-ROM) or sd1 (et cetera). For normal usage you
will probably want to leave this blank.
RAM size and Auto-size RAM
-
You should click Auto-size RAM to have the Booter automatically calculate
the amount of RAM installed in your computer. This will not be an option
in future releases. The paranoid can type in the amount of RAM (in
megabytes) in the appropriate box as well.
GMT Bias and Auto-set GMT Bias
-
This should be a number of minutes which are added to UTC (Coordinated
Universal Time, also known as Greenwich Mean Time or GMT) to get to your
time zone. If you have the Mac OS Map control panel set with your location,
you can enable the 'Auto-set GMT Bias' option to set this information.
Single User
-
This option tells the kernel to boot the system in single-user
(administrative) mode, as opposed to your normal everyday multi-user
boot. This can be necessary when you're having trouble booting into
multi-user, or if you need to edit some files before the system finishes
booting.
Extra kernel debugging messages
-
This option tells the kernel to display some extra debugging information.
Jump into debugger after booting
-
This flag tells the kernel to go into the debugger (either kgdb or ddb)
shortly after initialization.
Don't disable VBL interrupts on video cards
-
Booter versions after version 1.8 attempt to disable vertical blanking
(VBL) interrupts on all active video cards found, because current
implementations of the grf_mv (Macintosh QuickDraw-compatible NuBus video
card) driver do not handle VBL interrupts reliably. If this process fails
(and it should be obvious if it fails; an error code is printed and the
boot stops) then you should check this box and try booting again.
Video address hack (for LC575 & LC475)
-
This option should allow the internal video to be used as the console on
these two Macs with almost any kernel. These machines use the MMU to remap
the video address under Mac OS, and this mapping is lost when BSD/mac68k
kernel execution begins. Do not use this option for any machine other than
the LC/Performa 475, 575 & 630 series, as it may cause undesired kernel
crashes.
The options in this dialog window, described below, pertain chiefly to the
initial settings of the new zsc/zstty serial driver:
-
Serial Boot Echo
-
Output from the kernel will be echoed to the printer port at 9600 baud,
no parity, 8 data bits, 1 stop bit, if this option is checked. (See also
the 'Default Serial Speed' boxes)
Serial Console (Modem or Printer)
-
The selected serial line will be used as the console, with the same
communications settings as with Serial Boot Echo (above), if this option
is checked. Be careful that you do not have a getty process running on the
same serial line you are using as the console (i.e. do not run getty on
both ttye0 and tty00 if Modem port is serial console) because this could
panic the kernel. Note that you can select a port for the serial console,
but the serial boot echo is always on the Printer port.
LocalTalk connected to Printer port
-
In some instances the kernel will freeze if it is connected to a
high-traffic LocalTalk network. Although LocalTalk is not supported in the
kernel, if this box is checked it will keep the kernel from panicking if
it encounters this situation.
Open port before booting (for PowerBook)
-
In order for PowerBooks to use the serial port(s), they must be turned on
before booting in order to get the Power Manager to turn the power on to
the chip and the ports. Setting this option should only be necessary if
you are booting NetBSD/mac68k on a PowerBook.
Default Serial Speed
-
With NetBSD/mac68k kernels later than 20th October 1997 (i.e. 1.3),
the port speed can be set by typing the new speed in here. This might be
useful if you want to log boot messages to a HP DeskJet printer, for
example.
Set Modem (or Printer) port to 'stty raw' defaults
-
This option instructs the kernel to set the defaults for the serial port
in question to those from the 'stty raw' command. BSD assumes serial ports
are hooked up to terminals by default, and the default behavior for
terminals is for the kernel to echo back characters that the user types
into the terminal. In 'raw' mode, no assumptions are made about what's on
the other end of the serial port. Among other changes, no characters are
echoed back out the port.
The difference is important if your BSD/mac68k machine is connected to the
serial interface of an HP DeskWriter printer. They (and possibly other
printers) report status by sending a character to the host computer.
Without this boot option, BSD would think that a person was typing these
characters and echo them back. But then the printer thinks it is supposed
to print these characters. On the DeskWriter, these characters can come
out as ugly white-on-black block letters (garbage). This printing will
happen seemingly spontaneously, with no intervention from the user.
Setting this boot option should cure the problem.
This option is probably not appropriate for a serial port hooked to a
terminal, as the normal terminal defaults are the best in this case.
External clock sources
-
The new zsc/zstty driver (introduced in NetBSD/mac68k 1.2) tries to
support more of the options Apple originally foresaw for the Mac's serial
ports. One feature is support for feeding the Mac a clock from which it
will generate the baud rate used to send and receive data. Potential uses
include talking to certain Personal LaserWriters and driving MIDI adapter
units.
Each serial port has two input pins, so there are four possible clock rate
values. When a clock rate is entered, two things happen. First, the
associated pin is flagged as reserved for a clock, and second, the clock
rate is considered when NetBSD requests a particular baud rate.
The first action happens as these pins (which have different names under
BSD and Mac OS) are usually considered as modem signal pins by BSD. The
kernel must respond accordingly whenever the modem thinks a data carrier
has been detected, something which would normally happen less than once a
second. Clock rates, on the other hand, are usually in the millions of
cycles per second, so the clock reservation acts as a protection for the
NetBSD kernel.
Note that one of the pins on the printer port (GPi/DCD) isn't actually
usable by the baud rate hardware; it corresponds to the fully-featured
clock input on the modem port. Thus it is included to protect the kernel
from a device intended for the modem port yet connected to the printer
port.
Current kernels and X Window servers cannot change video modes very well.
The BSD/mac68k console will work with almost any depth or resolution, but
the X Window system (and maybe the DT multi-window console) cannot.
For those of you whose use your Macs for Mac OS as well as BSD/mac68k, these
options allow you to keep you Mac OS screen the way you like them, and then
change the settings just before booting the BSD/mac68k kernel:
-
Change Monitor Colourmap to GreyScale
-
Support for colour is not currently in all X servers, but some of them
do support 256 greys. This option should make the X Window system a
little more usable on those systems
Change Monitor Depth
-
A set of common depths, some of which your Mac may not support. If the
requested depth isn't supported, no depth change should occur
Change Monitor Resolution
-
Common Mac OS screen sizes, which both your monitor and your Mac may
not support. If your Mac doesn't support the requested size, the screen
may flash, but no change should happen. If you monitor doesn't support
the requested resolution and scan rate, behaviour depends on the monitor
and cable. Usually, there will be no resolution change. If you have a Mac
to PC style cable which is set differently to your monitor's capabilities,
the monitor may lose sync, and in rare situations, damage may occur
Note that these options only affect the main monitor. They don't currently do
anything with multiple monitor setups.
A few more miscellaneous options pertaining to the operation of the Booter
itself are in the Preferences dialog window:
-
Auto boot on startup / Timeout before boot
-
If you have saved your normal boot preferences, you might want to just
boot right into BSD as soon as you open the Booter. Checking 'Auto boot on
startup' will make the Booter start booting a specified number of seconds
after it starts.
Show dialog & wait for OK before booting
-
If the above option is checked, then a dialog window will appear before
booting that asks you whether you want to Boot or Cancel. This was
implemented so you might read the messages in the window before they are
blanked out by the appearance of the console.
Debugging level
-
Setting the debug level to 1 or greater values gets you lots of debugging
spew in the status window that can help you diagnose what's going wrong in
the boot process. But normally you will want to leave this at 0.
Log debugging to file / Set...
-
If you want to keep a log of the messages in the status window, so that
you can dump it into a mail message or just look at it later, check this
box and click on 'Set...' to choose where you want the log file created.
Note that the Booter will not replace an already-existing log file, but
will append to it, even though it says "Replace existing 'bootlog'?" when
you save it. Note also that when people ask for a bootlog they usually
want you to turn debugging on (to level 1 or 2) and use this option.
Normally, of course, you won't need to keep the bootlog turned on.
No env dumps
-
If this option is not checked, the Booter will dump the boot
environment, a list of variables not unlike the UNIX process environment,
into the status window before booting. If this option is checked,
the booter will not spew this entire list of strings into the window before
booting. They are nice for bug reports, but they do slow down the boot
process. This option disabled goes well with 'Show dialog & wait for OK
before booting' being enabled & a nice, big boot window. :)
Halt on non-fatal errors
-
A few errors (mostly concerning such recondite things as video board
interrupt errors) are considered non-fatal. If you are having trouble with
BSD/mac68k video, you might want to try turning this on, so that you can
read the error messages as they scroll by. Mostly, though, you'll not need
to worry about this; leave it unchecked
Some of the following errors are practically FAQs on the port-mac68k list.
Some are not. Any of these could possibly happen to you. This guide can help
you understand what is going wrong. Don't leave Mac OS without it!
Couldn't locate any partitions on SCSI ID (0). Cannot open kernel
(0,?)netbsd.
-
This error occurs when the Booter cannot open the partition you specified
for the kernel. Check for typos in the SCSI ID and/or Partition Name boxes
in the 'Booting' dialog window.
File 'foobar' is nonexistent. Cannot open kernel (0,?)foobar.
-
This error occurs when the Booter found the partition, but couldn't open
the kernel you specified. Make sure you specified the right partition, and
make sure you didn't mistype the name of the kernel (in the 'Booting'
dialog window.)
Cannot malloc()...
malloc() failed...
Not enough free memory to load this kernel.
(et cetera)
-
These all mean that the Booter has run out of memory. Increase the Booter's
memory partition using the 'Get Info' command in the Finder, and try
booting again.
Magic numbers do not match -- Improper UFS partition.
-
This means that the Booter went to read the NetBSD partition you specified,
and it didn't find a valid BSD filesystem there. Did you remember to run
Mkfs on the partition?
Error -nnn turning off interrupts for slot SS
Error -nnn {getting name of,trying to open} slot 0xSS video driver
(et cetera)
-
Though these shouldn't happen, if a video card error stops your booting,
you might want to try booting again with "Don't disable VBL interrupts on
video cards" checked in the 'Booting' dialog window.
Error #-nnn locking kernel memory.
-
The Booter is trying to boot with virtual memory enabled, and it couldn't
lock the kernel buffer in real RAM. Booting with virtual memory enabled is
not supported at all, and on top of that, it is extremely unlikely to work.
You should turn off VM in the Memory control panel, restart, and try
booting again.
Failed to read executable header from kernel image.
This kernel is not in a format which the Booter can execute.
The kernel does not appear to be a 68k kernel.
Short boot_read. Kernel file corrupt?
-
These messages all indicate that the Booter can't imagine that the file you
have designated as a kernel is really a NetBSD 680x0 executable. It may
have become corrupted in transfer - you did use binary mode when FTPing,
didn't you? - or you may have forgotten to untar the kernel.
The Booter src code package contains a file ChangeLog.txt which has a detailed log of different
Booter versions. Here is a summary of the ones you will probably need to
know about:
Version: 1.9.4
Author: Brian Gaeke
-
- First Booter to support any 68040 (i.e. Quadra-class)
machines. Known to boot kernels from NetBSD/mac68k versions 1.1 and
later. For kernels older than 1.1, your mileage may vary -- in theory
the support is still there, but it's not been tried in quite a
while
Version: 1.9.6
Author: Allen Briggs
-
- Allows booting with larger kernels (many post 1.2 kernels require
this Booter)
- Known to have problems booting the Mac IIvx
Version: 1.9.7
Author: Steve Brown
-
- New 'Auto Set GMT bias' checkbox which uses the 'Map' Mac OS Control
panel to set Unix's time zone information
- Known to have problems booting the Mac IIvx
Version: 1.10.0
Author: Allen Briggs
-
- New ability to boot from gzip-ed kernel files
- Known to have problems booting the Mac IIvx
Version: 1.10.3b1
Author: Nigel Pearson
-
- Some user interface improvements and new functionality
- Fixes the recent problems with booting the Mac IIvx
- New serial fields to set different default serial port speeds
- New Monitors options which allow changing of the main screen depth
before booting
Version: 1.11.1
Authors: Scott Reynolds, Nigel Pearson
-
- More user interface improvements
- If boot is aborted, resets monitor depth
- Saves preferences in a file in the System Folder
- Added video address hack for LC475/LC575 Macs to allow console on
internal video
- Mac OS kernel file can be selected using a file requestor, allowing
selection of a kernel file which is an alias, is not in the current
directory, et cetera
- Better debugging/error output for low-level SCSI stuff
Version: 1.11.2
Authors: Eugenio Macia Vivo, Nigel Pearson
-
- Booter now checks for Virtual Memory, and pops up an alert and
exits if used
- Monitors options now allow changing of main screen's resolution and
colour mode (to greys) before booting. The latter is for some of the
new Xservers which don't work with colour yet
- Now correctly kills running applications (checks for AppleScript
beforehand)
Version: 1.11.3
Author: Nigel Pearson
-
- Booter can now request that the kernel jumps into a debugger after
startup
- Some flags moved around in (and between) dialogs
- Low-level SCSI error-handling bugfixes
- Bugfix of monitor depth change stuff (Booter 1.11.2 used to try
change resolution whenever depth change was requested)
The Booter is currently being maintained by Nigel Pearson.
<nigel@ind.tansu.com.au or
nigel@socs.uts.edu.au>
There are a list of Booter improvement suggestions in the file
TO-DO.txt (in the src code package). Feel free to
email any new suggestions to Nigel after glancing through that file. Also
feel free to contact Nigel about implementing any of them yourself!
If you have a bug report for the Booter, please send him a complete record
of your system configuration, including NuBus cards, along with a detailed
description of the erroneous behavior and how to repeat it. If you broke
into MacsBug, you should include the contents of the Standard Log (type
StdLog into the MacsBug command buffer and hit return; with luck it will
end up in the Desktop Folder of your boot disk.) Note: If you got past
the NetBSD copyright message, the error is probably not the fault of the
Booter.
The long list of people have worked on the Booter: Allen Briggs, Steve
Brown, Chris Caputo, Michael Finch, Brian Gaeke, Brad Grantham, Markus
Hitter, Dan Jacobowitz, Lawrence Kesteloot, Nigel Pearson, Scott Reynolds,
Bill Studenmund and Eugenio Macia Vivo.
This manual was written originally for NetBSD/mac68k Booter version 1.9.4
by Brian Gaeke. Thanks to Bill Studenmund for descriptions of the new serial
port options.
Apple, Macintosh, LocalTalk, System 7, and Mac OS are all registered
trademarks of Apple Computer Corporation. UNIX is a registered trademark
of SCO. Other trademarks mentioned herein are property of their respective
companies.
Copyright (C) 1996 Brian R. Gaeke
Copyright (C) 1997-8 Nigel Pearson
All rights reserved.
Redistribution and use of this document, with or without
modification, are permitted provided that the following conditions
are met:
- Redistributions of this document must retain the above copyright
notice, this list of conditions and the following disclaimer.
- The name of the author may not be used to endorse or promote products
including this document without specific prior written permission.
THIS DOCUMENT IS PROVIDED BY THE AUTHORS 'AS IS' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS DOCUMENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.