Technote RTN001

The Rhapsody Boot Process

By Timothy Carroll
Apple Worldwide Developer Technical Support

CONTENTS

Open Firmware

Rhapsody Control Panel

Secondary Loader

The Kernel

Appendix - Unsupported Hardware

The Rhapsody Developer Release modifies the Macintosh boot process to allow both MacOS and Rhapsody to coexist on the same machine. This note details the modifications that were made to the Open Firmware configuration to support Rhapsody, and documents the process taken to load the Mach kernel. Finally, this note documents the problems of running the developer release on unsupported hardware.

The information in this technote applies only to the first Developer Release of Rhapsody, and is therefore of a short term usefulness. Developer Release 2 will change a number of pieces in the boot process, and many other pieces will be altered as Rhapsody continues to evolve. This information is provided primarily to assist in debugging a Rhapsody machine that isn't booting correctly. Do not base a product on this information. The surgeon general has proven that this information causes cancer in lab rats. Caveat emptor.

This note assumes some knowledge of Open Firmware. Macintosh Technotes 1044, 1061, and 1062 provide an introduction to Open Firmware on the Macintosh.

Open Firmware


The standard Open Firmware configuration variables are stored in non-volatile RAM (henceforth known as 'nvram'). When the machine is powered on, these variables are used to configure the machine and to boot the machine into a particular OS. Only a few of them are useful in this discussion, however.

Variable

Usage

auto-boot?

If true, executes the regular boot-command. If false, stops at the Open Firmware console.

use-nvramrc?

If true, executes the nvramrc script

nvramrc

An Open Firmware program, usually used to fix Open Firmware bugs or to add user-defined commands.

boot-command

The default Open Firmware command used to boot the machine.

boot-device

The default device to boot the OS from.

boot-file

The default file to load to start the OS.

A standard Open Firmware boot process would follow the following steps:

  1. Power-on self-test
  2. System initialization
  3. Evaluate the nvramrc script (if use-nvramrc? is true)
  4. Probe all attached devices and build the device tree
  5. Execute the default boot-command if auto-boot? is true)

On Rhapsody, nvramrc has been modified to fix a few critical driver commands and to define a new command, bootr (boot rhapsody). The nvramrc script is limited by the small size of nvram (2K) and so a lot of fixes that could be done instead need to be deferred until later in the boot process.

bootr acts as a front end to boot, correcting a few bugs, and allowing kernel arguments to be passed to it. bootr expects one argument on the stack -- a mask indicating whether Mac OS (0x40) or Rhapsody (0x0) is the default OS to start. If bootr detects the caps lock key down, it boots the other OS instead. (0x40 happens to be the mask for the caps lock key.) The remainder of the line after bootr is picked up as kernel command line arguments. Note that to launch the Mac OS from Open Firmware, you can just type bye.

If the machine is booting into Rhapsody, boot searches the boot device for the SecondaryLoader, loads it into RAM, and executes it. For a SCSI device, the partition number of the boot device will always be 0, causing boot to search the drive's partition map for a bootable partition. boot will choose the first bootable partition (i.e. bit 3 in the pmPartStatus is set) that has the pmProcessor field set to PowerPC. MacOS Driver partitions are also marked as bootable, but the pmProcessor field is set to 68000, so Rhapsody doesn't consider them bootable. For more information on partition maps, see Inside Mac: Devices, p. 3-13 through 3-15 and 3-25 through 3-27.

If the machine boots into the MacOS, it replaces the Open Firmware configuration with the default values (which boots from the Mac ROM, and looks for a bootable MacOS drive). This has some important implications. If you do not have a bootable MacOS drive connected to the machine, the machine will halt at the flashing question mark. Worse, because the Rhapsody configuration has been wiped from NVRAM, the machine will no longer be able to boot into Rhapsody.

The current solution to this problem is to always have a bootable MacOS partition on a Rhapsody development machine, and a Rhapsody control panel to write the Open Firmware configuration on startup. For detailed instructions on configuring a machine with multiple partitions, see Rhapsody technical note RTN0002: Dual Boot Installation.


Rhapsody Control Panel

The Rhapsody Control Panel includes an INIT that modifies the Open Firmware variables in nvram. It does this by applying a number of script resources ('ofpt') found inside the control panel or the panel's preference file.

The 'ofpt' resource's name is the Open Firmware variable it modifies, and the resource's contents are the value to change it to. The beginning of the resource MUST be an Open Firmware comment with list of machines to apply that patch against. For example, the nvramrc script supports the following machines:

\ {AAPL,9500|AAPL,9600|AAPL,8600|AAPL,8500}

The 'ofpt' resources in the shipping version of the control panel list a few other machines (7200, 7300, 7500 and 7600). These machines aren't officially supported, although machines such as the 7300 and 7600 have been used successfully internally at Apple. That they are there at all is mostly an artifact of the control panel's earlier existence as part of the Copland project.

It is possible to match all machines by putting an asterisk inside the comment field:

\ {*}

In any case, the first 3 characters must be "\ {" and any spaces or returns inside the comment will be matched just like any other characters.

The list of machines is compared against the compatible field of the Devices:device-tree node, inside the expanded device tree. If this field matches any of the strings stored in the resource, then the value will be written into nvram.

Importantly, the Rhapsody Control Panel is currently only expected to work on supported configurations. If you install the panel on other machines, it will override some of the boot parameters, but not others, resulting in a machine that will not boot. Specifically, the boot command is always changed to 40 bootr, but the nvramrc script that defines bootr is only written on supported configuration. Zapping PRAM should restore the defaults and allow the machine to boot properly.

Many Mac OS compatibles are derived from the Power Macintosh 9500 logic-board, and can probably run Rhapsody if they are using a supported ATI or IXMicro video card. While no rigorous testing has been performed, informal testing has shown that Rhapsody will work on these machines. In order for the Rhapsody control panel to work properly, the machine must report itself as compatible with one of the existing configurations. Not all compatibles do so -- for example, the Power Computing PowerWave reports itself as AAPL,????. Adventuresome souls can use DisplayNameRegister (from the PCI Driver Development Kit) to read the compatible field, and ResEdit to modify the 'ofpt' resources.

If the caps lock key is down when the Rhapsody Control Panel's INIT loads, the Control Panel forces the machine to restart. As the default is to load the Mac OS (40 bootr), in order to boot into Rhapsody, caps lock must stay down until the SecondaryLoader kicks in.

In Developer Release 2, the Rhapsody Control Panel has been replaced with a new application, Multibooter, that manages booting to any number of different OSes. Detailed information on Multibooter may be provided in a future version of this technote.


Secondary Loader

The SecondaryLoader can be much larger than the bootr script, so it loads a more complete set of drivers and bug fixes, and loads the first actual graphic to show you that Rhapsody is being loaded. It then loads the kernel boot file, copies it into memory, and executes it. The kernel, like other executables on Rhapsody is in Mach-O format.

If the secondary loader fails to find the kernel file at the location specified by boot-file, then it will put up a grey screen with a "broken folder" icon. If you see this icon, the first thing you should do is check the name of the kernel file in the Rhapsody Control Panel. You can also use the BootVars application on the Rhapsody Installer CD to look at the actual boot-file settings, and compare them to the partition maps on the hard drive or CD.

While any partition could theoretically be specified for the boot file, the current build of Rhapsody is only aware of the first Apple_Rhapsody_UFS partition it finds. Currently, you should not place multiple UFS partitions on the same device.

The SecondaryLoader picks up the kernel command line arguments from open firmware. The SecondaryLoader also checks for the 's' key (single-user) and 'v' key (verbose), booting the kernel with those additional parameters as necessary. The 'v' key will also cause the SecondaryLoader to print out some additional debugging messages to the output device. Here are some commands the SecondaryLoader recognizes:

-s

boot single user

-v

send verbose boot data to console

-i

ask for the name of the /etc/machinit program

-p

do not auto reboot on System Panic (i.e. stay panicked)

-a

ask for the rootdevice

And settable values:

maxmem=<number of bytes of memory>

rootdev=<"name" of rootdevice>

rd=<"name" of rootdevice>

Finally, the SecondaryLoader changes the boot-command to 0 bootr, making Rhapsody the default OS.


The Kernel

The kernel treats the video device as a large frame buffer, and uses its own graphics code and fonts to present a terminal showing the status as the kernel loads. If the kernel is loaded in "verbose" mode, then it will provided detailed explanations as it searches out the various devices attached to the machine. Overall, verbose booting is recommended when doing development or diagnosing problems on a Rhapsody system.

Currently, the PPC build loads a fixed set of drivers to configure the hardware. As the new driver model evolves, the PPC version of Rhapsody will dynamically load drivers as necessary.

As devices are scanned, they are assigned an abbreviation that can be used to refer to the device. The two most common abbreviations are sd, used for scsi devices, and en, used for ethernet devices. The first device will be numbered with a zero (sd0), and other devices are numbered sequentially. For more information on how scsi devices are managed, see the note titled "SCSI Disks on Rhapsody" (coming soon).

In most cases, the root device is going to be sd0, but it is possible to make Rhapsody boot off of a different device in the chain.


Appendix - Unsupported Hardware

The following list of PowerMacintosh compatibles are based off of the PowerMac 9500, and may be able to run the Rhapsody developer release. Some clones used different CD-ROM drives, SCSI controllers or other incompatible hardware. The table below provides some information about specific configurations that have been used in the past; others are listed, but have never been tested.

While it may be possible to get DR1 to work on unsupported configurations, there are limitations to the level of support that can be provided. Many bugs were fixed between DR1 and DR2, so any bugs found in DR1 should also be tested on a supported machine running DR2 before being reported.

IXMicro Video Compatibility

Many of the compatibles are using variations of the IXMicro Twin Turbo card. In some cases, the initial console window will come up with an alternating display of garbage and console data. Once the machine finishes loading the kernel and initializing all of the processes, it will switch to the correct mode and everything should appear fine.

Power Macintosh Compatibles

Akia Computer Corp

MicroBook Power

DayStar Digital

Genesis MP (reports itself as AAPL,9500)
Genesis MP 800+
Genesis MP 400+

Power Computing Corp

PowerWave (reports itself as AAPL,????. DR1 has installed onto this machine and runs fine.)
PowerTower (reports itself as AAPL,7300)
PowerTower Pro (reports itself as AAPL,9500. A few developers have reported success installing DR1 onto this machine, although it did ship with an IXMicro card with the problems listed above.
ATX Tower

UMAX Computer Corp

Storm Surge
S900
S900 Gemini


Acknowledgments

Thanks to Dan Peterson, Michael Prichard, Deborah Grits, Eric Simenel, Quinn "The Eskimo" and Eryk Vershen

To contact us, please use the Contact Us page.
Updated: 5-11-98

Technotes
Contents Next Technote