BSD/Mac68k Booter Manual

# BSD/Mac68k Booter Manual (HTML version)

Version 8, 30th June 1998. For Booter 1.11.3

## Index of Topics

- What is the BSD/Mac68k Booter?
- What the heck is NetBSD/Mac68k?
  - Some NetBSD/Mac68k Web Sites
  - The 'port-mac68k' mailing list

- Hardware Prerequisites
- How do I boot this silly thing!?
- A Quick Overview of the Boot Process

- Boot Options, Ad Nauseam
  - Booting dialog window
  - Serial Ports dialog window
  - Monitors dialog window
  - Preferences dialog window

- Common Boot Errors

- Booter Versions
- Who's responsible for this?
- Copyrights, Trademarks, et cetera

## What is the BSD/Mac68k Booter?

The BSD/Mac68k Booter is a MacOS application which boots the NetBSD/Mac68k (and OpenBSD/Mac68k) operating system.

## What the heck is NetBSD/Mac68k?

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`. Do this by sending mail to `majordomo@netbsd.org` with no subject and the single-line message:

`subscribe port-mac68k J. Random User`

replacing J. Random User with your real name, of course.

## Hardware Prerequisites

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.

## How do I boot this silly thing!?

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 MacOS!) installed, here is how to boot it:

- Open the BSD/Mac68k Booter from the MacOS. 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

## A Quick Overview of the Boot Process

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.

## Boot Options, Ad Nauseam

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.

### Booting dialog window:

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 MacOS 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 MacOS 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 MacOS, 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

### Serial ports dialog window:

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.

### Monitors dialog window:

Current kernels and X Windows 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 MacOS as well as BSD/Mac68k, these options allow you to keep you MacOS 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 X Windows 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 MacOS 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.

### Startup dialog window:

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

## Common Boot Errors

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 MacOS 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

## Booter Versions

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' MacOS 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
  - MacOS 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)

## Who's responsible for this?

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.

## Copyrights, Trademarks, et cetera

Apple, Macintosh, LocalTalk, System 7, and MacOS 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:

1. Redistributions of this document must retain the above copyright notice, this list of conditions and the following disclaimer.
2. 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.