Technote RTN0003

SCSI Disks on Rhapsody

By Martin Minow

CONTENTS

Background

The Bootstrap Process

Effects of System Configuration Changes

Changing the System Configuration

Recovering from Misconfiguration or Errors

T hese notes are intended to help you use SCSI disks on the Rhapsody Developer release. They point out some pitfalls, problems, and workarounds. As the Rhapsody operating system matures, these problems should disappear.

The easiest way to avoid the problems outlined here is to keep your system configuration stable, i.e., once you've installed Rhapsody, do not add or remove any disk devices that were present -- and powered on -- when you installed Rhapsody. Also, do not install Rhapsody on one machine, then move it to another machine with a different configuration. Many of the workarounds here are intended to help you recover from varying configurations.

Background


MacOS users are familiar with two ways to designate SCSI disks and the volumes stored on them: the volume name as it appears on the desktop, and the SCSI bus id (the bus number, target ID and, infrequently, the logical unit number). On Mac OS, the SCSI bus ID is used only for administrative tasks, such as installing a new disk or updating drivers.

Rhapsody adds a third SCSI device designator to this picture: the Unix device name. Unix uses a tree-structured file system where every directory (folder) and file is located in a path starting at the top-level "root" directory of the boot device.

Also, on Unix, hardware devices are located within this tree, where they are identified as files stored in the "/dev" directory. (These are not actual files, but rather provide a name that the operating system uses to locate the device driver for that particular device.)

When the system starts, the Rhapsody bootstrap looks at each SCSI bus in turn, examining each SCSI bus ID in turn. When it discovers a SCSI disk (either a hard disk or CD-ROM), it initializes an entry in the "/dev" folder. The first disk it discovers will always be sd0, the next sd1, etc. Since each hardware disk can contain more than one Unix file system partition, the device name is extended with a letter designating the partition. So, the actual Unix device will be named sd0a, etc. If, for some reason, there is more than one partition on this disk, the next will be named sd0b, and so on.

The relationship between SCSI bus and target ID and the raw device name that represents that particular SCSI bus and target ID is computed on each Rhapsody restart. This means that, if you change your configuration or power on (or off) an external device, all of the devices found later will be associated with a different Unix raw device name.

Unfortunately, because of its Unix heritage, the developer release bootstrap requires the boot device's SCSI bus and target ID, as well as the Unix device name. Furthermore, the boot device name is also stored in the fstab file in the /etc directory. You will soon see how this complicates matters.

Another potential source of confusion for Macintosh users is that, on MacOS, the internal bus is number zero and the external number one. Rhapsody reverses this: it looks at the external bus first and the internal bus second. The Rhapsody developer release does not support third-party SCSI busses.


The Bootstrap Process

When Rhapsody is installed it stores three strings into the hardware non-volatile RAM (NVRAM) and configures the "/etc/fstab" file.

The boot device
The boot device string is used by the Open Firmware bootstrap to locate the initial bootstrap module. This string designates the bus (scsi for the external bus, scsi-int for the internal bus), device type (sd for SCSI disk), target ID and logical unit number. For example, to boot from a disk attached to the external bus at SCSI bus ID 1, the string would be "scsi/sd@1:0".

 

The boot file
The boot file is used by the initial bootstrap to locate the SCSI bus, target ID, partition number, and kernel file. The partition number is the index of the Unix file system (UFS) partition containing the root directory. If you installed Rhapsody on a disk that was initialized to contain only a single UFS partition, the boot file string for the above boot device will be "scsi/sd@1:3,mach_kernel.

 

The boot command
The boot command is used by Rhapsody to configure and control the bootstrap process. Open Firmware passes it to Rhapsody when it relinquishes control to the Mach kernel. This string contains the command "0 bootr," any options, and the Unix device name of the root filesystem. The boot command for this example is "0 bootr -v rd=sd0" The "-v" option means "verbose:" display the startup commands on the console display. You may also provide "-s" to boot "single-user" without starting the general system. This may be needed to recover from configuration changes.

 

The "/etc/fstab" file
The "/etc/fstab" file contains a list of Unix devices that are to be mounted at system startup. The root (system boot) device must be provided, and others may be provided, but this is not normally needed as an autoboot background process will detect and mount them. The "/etc/fstab" file for the example contains: "/dev/sd0a / ufs rw 0 1". For the Rhapsody bootstrap, the device named in /etc/fstab must match the device named in the bootr command in the Open Firmware bootstrap.

Effects of System Configuration Changes

If your system configuration changes, you may have to change the NVRAM strings and/or edit the "/etc/fstab" file entry for the root device.

  • If the bootstrap device changes SCSI bus ID, you will have to edit the "boot device" and "boot file" strings to designate the new SCSI bus ID and possibly the partition number. If you change the boot device from the internal bus to the external bus or vice-versa, you will also have to change the bus name.
  • If you add disk devices to the SCSI bus so that they would take a lower Unix device name than the boot device, you will have to edit the boot command and the "/etc/fstab" file to set the correct Unix boot device name.

Thus, to minimize the inconvenience, you should note the following:

  • Install Rhapsody on an external disk with a low SCSI bus ID. Make sure that any other disks on the external bus have higher SCSI bus ID's, as their Unix device names aren't stored in the bootstrap.
  • If you install Rhapsody on an internal disk, and your external bus configuration must vary, prepare several bootstrap configuration files under MacOS and reset NVRAM whenever your configuration changes. Then, boot single-user and edit "/etc/fstab" before starting timesharing.

Changing the System Configuration

You can change the NVRAM configuration by running the BootVars application under MacOS. Edit the dialog fields (the boot command is visible when you select the "all variables" checkbox) and save the configuration on your MacOS system disk.

If the Unix device name changes, you should reboot single-user (either set the -s option in the NVRAM boot command or hold the 's' key down when you reboot Rhapsody). Then, type the following at the prompt:

mount -w /dev/sd0a /
Mount the correct volume (substitute the correct device name for sd0. Note that this mounts the volume read-write.
. /root/.profile
Configure the console for the pico editor. Note that this string is typed "dot", "space", /root/, "dot", profile.
pico /etc/fstab
Start the pico editor and change the device name. Exit pico and save the changes.
sync
Tell the file system to write all changes to the disk.
reboot
Reboot to check that everything is now correct.

Recovering from Misconfiguration or Errors

Here are a few common errors and ways to recover from them:

Incorrect bus or bus ID; incorrect partition number
If the NVRAM bus or bus ID is incorrect, the system will appear dead when you reboot. First, try typing "bye<Return>" to boot to MacOS. If this fails, try rebooting with the <CAPS-LOCK> key down. If this fails, you will have to reboot holding the <Command>, <Option>, <P>, and <R> keys down to reset the nonvolatile RAM to its factory default.

If you do reset NVRAM, be sure to use the Macintosh date and time control panel to set your timezone. You may also want to change the AppleTalk configuration, which was set to "Printer Port" when you reset PRAM.

Incorrect Unix device name in the boot command.
If the SCSI device is correct, but the Unix device name stored in the boot command is not correct, you will see an error displayed on the console and the boot will stop with a kernel panic. In the following example, I set the Unix device name to "sd2," which is not present on my system. When I booted Rhapsody, a small "Kernel Panic" window was displayed, ending with the following messages:

  sd2: Disk Not Ready
  ... several other messages
  System Panic:
  cannot mount root
  ... more messages...
  Rhapsody Mini--monitor
  panic>

Don't panic: just reboot to MacOS (<CAPS-LOCK> should be sufficient) and edit the device name in the Control Panel or Boot Variables dialog. (The Boot Variables application is in the Utilities folder on your Rhapsody Developer CD-ROM. You can use it to create and save a number of configuration documents that can be useful if your system configuration frequently changes.)

After updating the NVRAM Open Firmware commands, boot single-user to edit the "/etc/fstab" file.

 
Incorrect Unix device name in the /etc/fstab file.
If the SCSI device is correct, but the Unix device name stored in the /etc/fstab file is incorrect, the system will mount the root device read-only, then stop in single-user mode. Use the script shown above to mount the device read-write, edit /etc/fstab, and restart to test your changes.

 

To contact us, please use the Contact Us page.
Updated: Date-Month-98

Technotes
Previous Technote | Contents | Next Technote