A guide to Open Firmware - The Apple BIOS
A guide to Open Firmware - The Apple BIOS
Most Apple G3/G4 systems use a modified version of the Open Firmware standard. These machiens are normally referred to as "NewWorld Macs". Open Firmware acts as a type of bios for the PowerPC system, it is responsible for identifying various hardware components and uses a series of environment variables to all the user or developer to modify the boot behavior of the system. Open Firmware is pretty easy to access and navigate once you know how, this guide walks you through the basics, so you can get to know your system a little better.
The boot process starts with the PowerPC processor executing its reset vector as specified by the Hardware Initialization code. The boot ROM stored in NVRAM provides power on self test (POST - diagnostics), and initializes enough of the system to load Open Firmware. These POST tests are run in native PowerPC code and involve checksum testing, memory testing, detection of the manufacturing test pin and test manager support. With the new family of iMac systems, additional pre-firmware diagnostics are performed due to the addition of the UniNorth and KeyLargo ICs. When enough initialization has occurred to execute Open Firmware, the boot chime is played and Open Firmware is loaded.
Open Firmware will then probe the system's I/O buses to determine the device configuration and build a device tree, which describes the hardware it has located, the system will then examine the values of its enviroment variables. If the auto-boot? variable is flagged as true, the system will then read the value contained within the boot-device variable and attempt to boot from that device. If additional information is required the boot-file variable is read. If the auto-boot? variable is flagged as false, the system will halt the boot process and drop to the Open Firmware user interface.
Default Boot Device
The default boot device on Apple systems is "hd:,\\:tbxi". The system will automatically convert "hd" into the appropriate device path, as hd is simply an alias. The notation "\\" tells the system to start searching for "blessed" folders (directories) starting on the first HFS or HFS+ partition found on the system. The final part, "tbxi", tells the system to look for files of type tbxi. All versions of MacOS have a folder known as System Folder that is "blessed", and contains a MacOS Boot ROM file which is of type tbxi. The Boot ROM file is simply a stripped ELF executable image wrapped with a forth boot script. A "blessed" folder is simply one with a special attribute (or flag) set on it. The system will search all HFS partitions for a blessed folder and a file of type tbxi within it, if none are located, the boot will fail. The system will always select the first one found, unless the boot-device is modified to a specific partition id.
Old vs. New
Apple's Open Firmware is part of their ROM-in-RAM design approach originally used in the first iMac systems. The approach uses a small ROM that contains sufficient code to initialise the hardware and load an operating system. The rest of the system code, that on previous Mac systems (old world) resided on a physical ROM (chip) is now loaded from disk or from network into RAM. Open Firmware is part of this "New World" boot system.
Overview of Open Firmware
Open Firmware is a boot environment developed using the Forth programming language. Open Firmware exists to provide a machine independent means of loading operating systems, from a variety of boot devices. Open Firmware probes the PCI bus for devices and possible Open Firmware device drivers for those devices. These drivers can either be integrated into the Open Firmware or provided on an external device, thus providing plug and play capabilities for new boot devices. Open Firmware is then capable of using these drivers to load an operating system from the device.
On the latest revision of Apple systems Open Firmware provides a variety of functions. One of the key functions of Open Firmware is to configure the UniNorth and Keylargo ICs, to constract a device tree, probe devices, include any device drivers and finally select a boot device. Open Firmware includes FCode channels for UltraDMA/33, Firewire (1394) and USB hardware channels. Interrupts are determined by information contained within the device tree.
Open Firmware capabilities
Apple's Open Firmware can load ELF binary images directly from a HFS standard, HFS extended or a ISO9660 file system. The ELF image can be loaded using the Open Firmware user interface command boot along with the syntax hd:5,\\image.elf. The "hd" is the alias for the hard disk, 5 is the partition id, and "\\image.elf", tells the system to look for image.elf in a blessed folder on that partition.
Open Firmware supports booting from a variety of devices, to provide some element of user-friendliness, Open Firmware supports the use of aliases for a variety of devices. For example, the primary hard disk and primary CD/DVD-ROM drives are represented by hd and cd aliases. These alises are constructed from the device-tree by Open Firmware, in reality the alias hd actually is a path within the device-tree such as /pci@f2000000/mac-io@17/ata-4@1f000/disk@0.
Navigating Open Firmware
Open Firmware is easily accessible at boot time by using a simple key combination of Command + Option (alt) + O + F. This key combination must be used during the initial boot sequence (as soon as the audible chime is heard), and held util the distinctive black on white, text based Open Firmware user interface appears. Open Firmware will display a message similar to this:
Apple PowerMac2,1 1.2f2 BootROM built 09/09/99 at 18:58:29 Copyright 1994-1999 Apple Computer, Inc
All Rights Reserved
Weclome to Open Firmware
To continue booting, type "mac-boot" and press return.
To shut down, type "shut-down" and press return.
The Open Firmware interface is similar to the boot rom interface on Sun Microsystems SPARC systems, in that, it stores its environment variables through the use of the setenv command and variables can be viewed through the printenv command. Another commonality between the two systems, is that both are stored on NVRAM. While Open Firmware has several system and user definable variables, we will look at those involved in the boot process.
auto-boot? uses a boolean (true/false) value to determine whether to automatically boot or to drop to open firmware.
boot-device is a string value and is used to specify the boot device, partition and file type to load on boot.
boot-command is also a string value, and is used to supply an alias for booting the OS (eg. the default is mac-boot).
boot-file is another string value, and contains the location of a bootinfo.txt style script. This is a legacy open firmware variable that can be used to specify a chrp style script, similar to those used on the IBM RS/6000.
Apple's Open Firmware supports a variety of variables for network booting, these include variables that handle ip, subnet masks, router/gateways which can be used for network-booting the system using a boot protocol such as BOOTP.
Navigating: Examining Hardware Devices
Open Firmware can be used to provide valuable insight into the hardware configuration of the system. At boot time, Open Firmware collects information regarding each device within the system and builds a device-tree, there are a variety of commands available to examine not only the device information and current configuration, but also some of the underlying Forth source code that is used in the Open Firmware drivers for those devices. This type of hardware information is extremely useful for tuning performance, correcting errors or trying to implement new drivers for a device.
- ls - displays contents of the current path in the device tree.
- devalias - provides a list of short alias names for key hardware devices.
- .properties - provides a list of properties for the selected device.
- pwd - displays the current path within the device tree.
- dev - selects a device (using either the alias or absolute/relative device tree path).
- words - provides a list of forth scripts associated with the selected device.
- source - executes a particular forth script.
- load - loads a image from disk, cd, network or another device.
- go - executes the currently loaded image.
- see - displays the source code for a particular forth script.
The ls, dev, pwd and .properties commands can be used to navigate around the device-tree, this can be useful for learning which specific hardware devices are interconnected. The structure of the device tree reveals which particular hardware devices are connected to which hardware bus structures, for example the device tree indicates which devices are connected to which PCI bus and host controller, which devices are connected to the USB controller and so on. Device driver programmers can look at the underlying Forth scripts and examine the state of that Open Firmware will leave particular hardware devices in. Programmers can also re-write the forth scripts using the Open Firmware interface to test the behavior of particular hardware devices. A segment of the device tree for the pci bus is show below:
The segment of the device tree shown above, clearly shows the uni-north AGP controller and the ATI Rage Mobility are off pci1, while most of the input/output devices are driven from pci2. The second segment shows an example of the mac-io portion of the tree with an ATA device and a separate USB portion of the tree. Finally pci3 has the ethernet device, and may contain additional devices such as a firewire bus (on the iMac DV for example).
Looking at the source
You can use the see command to look at some of the forth code that is used for a particular device. The code below is from the USB probe function in Open Firmware. It calls other routines and is pretty simple.
0 > see probe
debug-usb-flags fshowprobe and if
init-hardware debug-usb-flags fshowprobe and if
0 probe-hub debug-usb-flags fshowprobe and if
0 > source probe ok
2 > _
The above code is a snapshot from Open Firmware, and is Copyright Apple Computer, it is displayed here for educational purposes only.
Accessing the device-tree in Linux
You do not need to be in open firmware to look at the device tree. You can examine it from within the /proc file system by simply cd'ing to /proc/device-tree. For example, you can cd to aliases within the device tree, then use ls to list the aliases, and cat to display the contents of an alias (eg. cat enet reveals /pci@f4000000/ethernet).
It might be a little easier to navigate the device tree under Linux, find what you are looking for then examine it in more detail in open firmware.
Examining the contents of open firmware on your system can give you a wealth of information about your system, however modification of variables or forth code within open firmware itself can lead to your system being unusable if done incorrectly. We do not provide any guarentee or warrenty with this document, and cannot be held liable for any damage to your system you may cause as a result of using information contained within this document. We strongly recommend that you only use this document to examine the contents of your system, and avoid modifications unless you know what you are doing.