Open Firmware

Preface

Open Firmware (OF) is a computer firmware system, similar to the BIOS on a PC, found in all MorphOS compatible Macs. The Pegasos, Pegasos II, and Efika also have an Open Firmware based hardware implementation, but with small differences to Mac firmware.

Open Firmware uses a Command-Line based user interface, which can be used to control booting and other processes. This tutorial focuses on useful tips and tricks when using the user interface by way of specific examples. The examples were tested on PowerPC Macs, but may also work under bPlan machines to some extent.

Output texts in these examples have been truncated in most cases to show only the information of interest.

Accessing the User Interface

Hold down the Command-Option-O-F key combination on a Mac keyboard, though the Option key is sometimes marked as Alt - with a symbol/icon below it, or press the Win-Alt-O-F key combination on a PC Windows keyboard while booting the machine. Release the keys only after you see the Open Firmware prompt display on a grey background.

Apple PowerBook5,9 4.9.6f0 BootROM built on 10/05/05 at 16:45:50
Copyright 1994-2005 Apple Computer, Inc.
All Rights Reserved.

Welcome to Open Firmware, the system time and date is: 07/24/2018 21:07:11

To continue booting, type "mac-boot" and press return.
To shut down, type "shut-down" and press return.

Release keys to continue!

 ok
0 > _

If the machine boots to an installed OS instead of the OF prompt, reboot and try again. It may help to connect the keyboard directly to the machine's USB port, not via a USB hub. The keys don't have to be pressed immediately when powering the machine on, but promptly after hearing the startup sound (if it has not been disabled) or as the machine triggers access to the optical drive.

Open Firmware uses the US keyboard layout, tips for typing using other keyboards can be found within the official MorphOS USB boot guide.

Useful Commands

• mac-boot - Continues booting from the current OF state
• reset-all - Resets the machine to the power-on state and reboots
• shut-down - Shuts down the machine
• load <file> <args> - Loads an OF code file (e.g. ELF binary image like MorphOS boot.img or Forth script) into memory
• go - Runs/boots the loaded file
• boot <file> <args> - Loads an OF code file and boots it
• printenv - Prints environment variable values
• setenv - Sets environment variable values
• devalias - Displays a list of aliases for devices (similar to assigns on MorphOS)
• .properties - Displays a list of properties for the selected device
• ls - Displays contents of the current path in the device tree
• pwd - Displays the current path within the device tree
• dev - Selects a device (using either the alias or absolute/relative device tree path)
• dir - Lists files on a partition

Environment Variables

Use the printenv command to list all environment variable values.

0 > printenv
-------------- Partition: common -------- Signature: 0x70 ---------------
little-endian?           false                false
real-mode?              false                false
auto-boot?              true                 true
skip-netboot?           false                false
use-nvramrc?           false                false

The first value in the list is the current value and the second value is the default value. It's quite rare that you need to change these values, but it's interesting to learn more about your computer nevertheless.

One common choice is to speed up Startup Manager (the boot menu you see when booting with the option/alt key pressed) by disabling the netboot option. So, let's change that, as an example, and check that we succeeded.

0 > setenv skip-netboot? true
0 > printenv skip-netboot?
-------------- Partition: common -------- Signature: 0x70 ---------------
skip-netboot?           true                 false

Examining Devices

The dev command selects a device to be examined, and .properties, ls, and dir commands can be used to print information about the selected device. Note that it depends on the device type if these commands will print something. dir only works for devices containing a filesystem, and such like.

Listing Aliases

A special /aliases device contains information about shortcuts (aliases) to different hardware devices. Let's see a few examples of how to show that information.

The device can be selected with the dev command and then the aliases can be listed with the .properties command:

0 > dev /aliases
0 > .properties
name                    aliases 
pci0                    /pci@f0000000
agp                     /pci@f0000000
pci1                    /pci@f2000000
pci2                    /pci@f4000000
usb0                    /pci@f2000000/@15
usb1                    /pci@f2000000/@15,1
usb2                    /pci@f2000000/@15,2
hd                      /pci@f4000000/ata-6@d/disk@0
cd                      /pci@f4000000/ata-6@d/disk@1
ud                      /pci@f2000000/usb@15,1/disk@1

The commands can also be input combined, on a single line:

0 > dev /aliases .properties
name                    aliases 
pci0                    /pci@f0000000
agp                     /pci@f0000000
pci1                    /pci@f2000000
pci2                    /pci@f4000000
usb0                    /pci@f2000000/@15
usb1                    /pci@f2000000/@15,1
usb2                    /pci@f2000000/@15,2
hd                      /pci@f4000000/ata-6@d/disk@0
cd                      /pci@f4000000/ata-6@d/disk@1
ud                      /pci@f2000000/usb@15,1/disk@1

There's also a shorter devalias command available on most firmware versions, and it does the same as the previous example:

0 > devalias
name                    aliases 
pci0                    /pci@f0000000
agp                     /pci@f0000000
pci1                    /pci@f2000000
pci2                    /pci@f4000000
usb0                    /pci@f2000000/@15
usb1                    /pci@f2000000/@15,1
usb2                    /pci@f2000000/@15,2
hd                      /pci@f4000000/ata-6@d/disk@0
cd                      /pci@f4000000/ata-6@d/disk@1
ud                      /pci@f2000000/usb@15,1/disk@1

Other Useful Properties

.properties on the root device shows the computer specs:

0 > dev / .properties
model                   PowerBook5,9
compatible              PowerBook5,9
                        MacRISC3
                        Power Macintosh
						
serial-number           SX0

The enet device shows the MAC address of the computer. 00:11:24:e3:66:66 in this case:

0 > dev enet .properties
vendor-id               0000106b
device-id               0000006b
name                    ethernet
device_type             network
local-mac-address       001124e3 6666

Listing Devices

The ls command lists devices found in the current device in the device tree:

0 > dev usb1 ls
ff9e1650  /disk@1
ff9e1a28: /device@2
ff9e1c48:   /keyboard@0
ff9e1f88:   /mouse@1
ff9e2230:   /interface@2

Listing Files

If a device (disk) contains a supported filesystem (HFS(+), FAT, ISO9660), its contents can be listed with the dir command.

Syntax of the dir command is: dir disk:partition,path

• disk is a device path to a disk, aliases can be used here and the delimiter in the device tree is /
• partition is a partition number (starting from 1), the default partition is used if left blank
• path is a path in the filesystem, the directory delimiter is \ and the same character is also used to access the root directory

Listing the root (\) directory from the default partition on the default HD (this is usually the Boot: partition on a MorphOS system). The "," character could be omitted in certain cases, but it's safer to type that as well:

0 > dir hd:,\

Listing the root directory from the first partition on the (default) HD:

0 > dir hd:1,\

Listing the root directory from a CD:

0 > dir cd:,\

Listing a sub-directory from a CD:

0 > dir cd:,\mac_ppc32

Listing the root directory from a USB mass storage device found in the usb1 device (use the previously mentioned ls command to find the correct device):

0 > dir usb1/disk@1:,\

Newer firmware versions create the ud alias for a USB mass storage device connected to the machine (if it's been connected prior to starting the OF interface), so this does the same as the previous example:

0 > dir ud:,\

Adding Custom Devaliases

The devalias command adds temporary user defined devaliases.

0 > devalias dh /pci@f4000000/ata-6@d/disk@0

nvvalias stores a devalias in nvramrc. Variable use-nvramrc? needs to be set to true in order to execute NVRAMRC script at startup.

0 > nvalias dh /pci@f4000000/ata-6@d/disk@0

nvunalias deletes an alias.

0 > nvunalias dh

You can replace existing devaliases with your own ones. Removing them will revert to original values.

Booting MorphOS

Basics

To boot into MorphOS, Open Firmware has to load a MorphOS boot image file, which is usually named as boot.img. The boot image contains the MorphOS kernel and core drivers, so it's basically comparable to the Amiga's Kickstart. Open Firmware just loads and boots the file, and the rest is handled by MorphOS itself after that. In case of errors, it's important to distinguish if loading of the boot image failed or does the error occur at a later stage.

The boot.img file usually resides on a special HFS formatted Boot: partition on Macs, or on a partition that has a filesystem known to Open Firmware in any case. The Boot: partition only contains a few Open Firmware related files and isn't used for anything else than to get the kernel loaded by the machine itself. How MorphOS sees the partition isn't important and it can even be unmounted from a MorphOS point of view. MorphOS itself is booted from a partition containing a MorphOS compatible filesystem and MorphOS system files in it, and this partition is usually named as "System:" and the SYS: assign points to it as well.

When booting manually from OF, you'll see some output lines on screen. There are two important lines that tell you the boot stage. This can be demonstrated well with the load and go commands.

Type in this line (if you have a MorphOS installation on your HD):

0 > load hd:,\boot.img

And you'll see output like this:

0 > load hd:,\boot.img load-size=16e8fc adler32=bd628950

Loading ELF
 ok
0 > _

"Loading ELF" tells you that the file has been found and loaded.

The file can be booted with the go command then:

0 > go
DO-QUIESCE finished_

"DO-QUIESCE finished" indicates that the file has been booted and the machine is now running under MorphOS. Problems after that stage are MorphOS related, and if the MorphOS boot image doesn't appear soon, then MorphOS might not have found a device or image to boot from, or there might be driver or compatibility issues. MorphOS reset keys (Ctrl-Lcmd-Rcmd, Fn-alt-alt) also work at this stage even if there are any other problems halting the boot process.

A shorter, and usual, way to boot is to use the boot command, which combines both load and go commands.

The previous example can be achieved with this single line:

0 > boot hd:,\boot.img 

And the output should then look like this:

0 > boot hd:,\boot.img load-size=16e8fc adler32=bd628950

Loading ELF
 
DO-QUIESCE finished_

Boot Arguments

Several boot arguments can be given to the boot.img file by adding them to the end of a load or boot line. More detailed explanations of these arguments can be found from Docs/Booting MorphOS.txt and Docs/PegasosFirmware.txt files on your MorphOS system or the installation CD, but let's cover the most useful booting related ones here.

Without arguments MorphOS boots a device that is bootable and has the highest boot priority set. Note that this only applies to partitions that contain a MorphOS compatible bootable filesystem. If a MorphOS installation CD is inserted, it usually has a higher priority than bootable partitions on the HD. The HDConfig tool can be used to set partitions bootable and alter their boot priorities, but usually it's unnecessary to change these settings.

The syntax for arguments is argument=value, but the equals sign can be replaced with a space character. The arguments can be given in a longer or shorter, in parenthesis () format.

• bootdevice (bd) - Overrides boot priorities and boots from a given partition. The partition name must be given in the form MorphOS sees it as a device name (volume names don't work), and the trailing ":" character can be omitted. For example, "bootdevice=dh1" works, but "bootdevice=System" doesn't.
• bootimage (bi) - Boots the MorphOS system from an ISO image file, which is placed on a partition that is accessible with the built-in filesystems of the boot.img (FAT, SFS, FFS, PFS3, CDFS). A full MorphOS style path must be given to the argument, but use device names instead of volume names again. For example, "bootimage=umsd0:morphos-3.11.iso", "bootimage=dh2:morphos-3.11.iso".
• bootmenu (bm) - Boots into the MorphOS bootmenu where you can change display settings, see information about devices, or boot without startup-sequence. The same bootmenu can be accessed by pressing the shift key during the MorphOS boot process. Pressing the v key in the bootmenu toggles between the default resolution and a 640x480@60Hz VESA mode, and that can be useful in case of display issues. The space toggles between multiple monitors instead.

Examples

Booting from CD

MorphOS documentation's usual advice is to boot the machine with the c key pressed, but that method can sometimes be unreliable for one reason or another, so you might end up in a situation where a boot image has been loaded from a HD and the actual system from a CD, which results in an error if the boot image and the CD aren't from the same MorphOS version. A more reliable way is to boot into the Startup Manager menu on Macs by holding the alt (option) key at boot, and select the CD from that graphical boot menu. Pressing the F12 key in the menu will eject the CD.

As well as the previously mentioned methods, there are other ways to boot a CD from the Open Firmware prompt.

To boot any inserted CD that is bootable on Macs:

0 > boot cd:,\\:tbxi

"\\" will look for a blessed directory on a device (you can list it by dir cd:,\\ or dir hd:,\\, for instance) and :tbxi looks for files of type tbxi (Toolbox image). This does practically the same thing as booting with the c key or booting from the Startup Manager menu, but you also see the output lines from OF (especially the "Loading ELF" & "DO-QUIESCE finished" lines) if you need some debug output.

Another way to boot the MorphOS installation CD from the OF prompt is to locate a correct boot image file from the CD and boot it with some boot arguments.

List the contents of the CD:

0 > dir cd:,\

  Volume: MorphOSBoot
     Size/        GMT                     File/Dir
     bytes   date     time   TYPE CRTR    Name
        94 07/04/2018 04:54:42  ???? ???? .morphosid
   2287135 07/04/2018 04:03:02  boot UNIX boot.img
   1454648 07/04/2018 04:03:02  boot UNIX bootcyrusplus.img
   2201986 07/04/2018 04:03:02  boot UNIX bootefika.img
   2286039 07/04/2018 04:03:02  boot UNIX bootpeg1.img
   1416944 07/04/2018 04:03:02  boot UNIX bootsam_ppc4x0.img
           01/01/1904 00:00:00           *mac_ppc32
           01/01/1904 00:00:00            mac_ppc64

As you can see, there are several different boot images for different architectures. boot.img is for Pegasos II and others are easy to guess. Boot images for Macs are located in sub-directories, mac_ppc32 contains the boot.img file for G4 Macs and mac_ppc64 for G5 Macs. The blessed directory is marked with an asterisk.

If we wanted to boot the CD on a G5 Mac:

0 > dir cd:,\mac_ppc64

     Size/        GMT                     File/Dir
     bytes   date     time   TYPE CRTR    Name
   1499688 07/04/2018 04:03:02  boot UNIX  boot.img
   
 ok
0 > boot cd:,\mac_ppc64\boot.img bd cd0

cd0: is the default CD device on MorphOS and it can be given as a bootdevice argument. The system would most likely boot from the CD even without this argument, because of the previously mentioned boot priorities.

To boot into the MorphOS boot menu on a G5 Mac:

0 > boot cd:,\mac_ppc64\boot.img bm

And the same for a G4 Mac:

0 > boot cd:,\mac_ppc32\boot.img bm

On a G4 Mac you could also use the blessed directory as a shortcut:

0 > boot cd:,\\boot.img bm

Booting MorphOS ISO from USB

The Official MorphOS USB Boot & Installation / Update Guide describes the basics of USB booting, but let's cover a few special cases here. If you can't access your FAT formatted USB stick, refer to the official guide on how to re-format it in a compatible way. Some Macs can be more picky about the format than others, and the same stick, that works in G4 Macs, might not work in a G5 Mac, etc., but it usually helps if you format it as advised in the official guide. If you still have issues with USB stick detection in OF or can't format the stick properly, this section of the tutorial provides some alternative methods to get a system booted.

The following examples assume that you have a correct boot image file (named as boot.img here) and a MorphOS ISO image file (named as morphos.iso here, remember that official MorphOS downloads have different names!) on a FAT formatted USB stick, which is plugged in before starting the OF user interface. The boot.img file can be obtained from a MorphOS installation CD/ISO, but remember that G4 and G5 Macs are stored in different directories (mac_ppc32 vs mac_ppc64). The files may be named differently too, there's no problem if you want to keep different versions around and boot whichever you want. You could have boot310.img and morphos310.iso as a bootable backup, for instance.

So, the basic idea is to boot the system from an ISO image without burning it or extracting files from it. This can be achieved by giving the ISO image location to the boot image with the bootimage argument.

Some firmware versions create a ud alias, which points to a USB mass storage device connected to the computer. List the aliases to find out if it's been created.

MorphOS itself creates a umsd0: device for the USB mass storage device and our ISO file is found from this device when the boot.img has been loaded.

If you have recent enough Open Firmware, booting the ISO file from a USB stick is easy:

0 > boot ud:,\boot.img bi umsd0:morphos.iso

If that doesn't work, try to list the contents of the USB stick to find out if it's in a compatible format:

0 > dir ud:,\

If you don't have the ud alias, you'll have to search usb* aliases for a correct path in the OF tree. List the aliases again or just start trying to list usb0, usb1, etc., devices until you find a device containing disk in its name, and that will reveal the full path to the USB stick, which can be used instead of the ud alias.

0 > dev usb0 ls
 ok
0 > dev usb1 ls
ff9e1650: /disk@1
0 > dir usb1/disk@1:,\
  Volume: USB
 258048000  07-24-2018 18:34:24    morphos.iso
   1501436  07-04-2018 04:03:02    boot.img
 ok
0 > boot usb1/disk@1:,\boot.img bi umsd0:morphos.iso

If the stick is connected to a USB hub, the path just gets deeper in the OF tree:

0 > dev usb1 ls
ff9e1650: /hub@1
ff9e1860:   /disk@4
0 > boot usb1/hub@1/disk@4:,\boot.img bi umsd0:morphos.iso

If a USB stick isn't recognised by Open Firmware, but it's accessible from MorphOS itself and you don't want to re-format it, you could copy the boot.img to a Mac partition on the HD, but still load the ISO image from the USB stick. The Mac partition can be an existing OSX installation (HFS+ formatted partition) or previous MorphOS installation (the HFS formatted Boot partition), for instance. The ISO image itself can't be loaded from an HFS partition, because MorphOS kernel (boot.img) doesn't have HFS support built-in. HFS support is loaded from filesystem level at the later stage when you boot MorphOS, but as OF recognises HFS partitions, boot.img can be loaded from them.

List the contents of the partitions until you find the correct partition where you copied the new boot.img file.

0 > dir hd:1,\
MAC-PARTS: specified MAC partition is not valid can't OPEN the DIR device
 ok
0 > dir hd:2,\

  Volume: OSX
     Size/        GMT                      File/Dir
     bytes   date     time   TYPE CRTR     Name
           07/22/2017 07:27:40              Applications
           09/27/2016 09:59:40              bin
   1501436 07-04-2018 04:03:02  ???? UNIX   boot.img
 ok
0 > boot hd:2,\boot.img bi umsd0:morphos.iso