Flameman/openfirmware-apple

= A tiny guide to Open Firmware =

What is Open Firmware
Open Firmware is the hardware-independent firmware (computer software which loads the operating system) that the XO runs.

It was developed by Mitch Bradley at Sun Microsystems, and used in post-NuBus PowerPC-based Apple Macintosh computers (though it has been dropped with Apple's transition to Intel processors), Sun Microsystems SPARC based workstations and servers, IBM POWER systems, and PegasosPPC systems, among others. On those computers, Open Firmware fulfills the same tasks as BIOS does on PC computers.

gentoo uses YaBoot BootLoader for Open Firmware.

The Open Firmware user interface includes a FORTH-based shell interface. FORTH is a powerful high level language that is remarkably compact. A complete Forth development environment including compiler, decompiler, assembler, disassembler, source level debugger, and assembly language debugger is present in the XO boot ROM (SPI FLASH). With the Open Firmware Forth system, you can directly access all of the hardware devices on the XO, use built-in functions like selftest diagnostics and games, and even write complete applications, without needing any external tools. The bulk of Open Firmware is written in Forth, so the source level debugger can be used to debug Open Firmware itself.

The Apple BIOS, hardware-independent firmware
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.

Boot Process
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.

Booting from a CD-ROM
The easiest route for most people will be to use an Ubuntu CD. If you have a CD, and if your machine supports booting directly off the CD, great! Simply insert your CD, reboot, and proceed to the next chapter.

Note that certain CD drives may require special drivers, and thus be inaccessible in the early installation stages. If it turns out the standard way of booting off a CD doesn't work for your hardware, revisit this chapter and read about alternate kernels and installation methods which may work for you.

If you have problems booting, see the section called “Troubleshooting the Installation Process”.

Currently, the only PowerPC subarchitectures that support CD-ROM booting are PReP (though not all systems) and New World PowerMacs. On PowerMacs, hold the c key, or else the combination of Command, Option, Shift, and Delete keys together while booting to boot from the CD-ROM.

If your system doesn't boot directly from CD-ROM, you can still use the CD-ROM to install the system. On NewWorlds, you can also use an OpenFirmware command to boot from the CD-ROM manually. Follow the instructions in the section called “Booting NewWorld Macs from OpenFirmware” for booting from the hard disk, except use the path to yaboot on the CD at the OF prompt, such as

0 > boot cd:,\app.elf

Booting from Hard Disk
Booting from an existing operating system is often a convenient option; for some systems it is the only supported method of installation.

To boot the installer from hard disk, you will have already completed downloading and placing the needed files

Booting NewWorld Macs from OpenFirmware
You will have already placed the vmlinux, initrd.gz, yaboot, and yaboot.conf files at the root level of your HFS partition in the section called “Hard Disk Installer Booting for NewWorld Macs”. You will now have to boot into OpenFirmware. At the prompt, type

0 > boot hd:x,app.elf

replacing x with the partition number of the HFS partition where the kernel and yaboot files were placed, followed by a Enter. On some machines, you may need to use ide0: instead of hd:. In a few more seconds you will see a yaboot prompt

Booting with TFTP
Booting from the network requires that you have a network connection and a TFTP network boot server (DHCP, RARP, or BOOTP).

Currently, PReP and New World PowerMac systems support netbooting.

On machines with Open Firmware, such as NewWorld Power Macs, enter the boot monitor and use the command

0 > boot enet:0

If this doesn't work, you might have to add the filename like this:

0 > boot enet:0,app.elf

PReP and CHRP boxes may have different ways of addressing the network. On a PReP machine, you should try

0 > boot net:server_ipaddr,app.elf,client_ipaddr

OpenFirmware Init
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 bblessed 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 World vs New World
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 initialize 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.

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.

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.

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 - execites 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:

/pci@f0000000 /uni-north-agp@b /ATY,RageM_Lp@10 /pci@f2000000 /mac-io@17 ....           /ata-4@1f000 /disk ....       /usb@18 /pci@f4000000 /ethernet@f

The segement 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 segement shows an example of the mac-io portion of the tree with an ATA device and a seperate 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
 * probe

debug-usb-flags fshowprobe and if ?cr"PROBE:" type then init-hardware debug-usb-flags fshowprobe and if hc-base u then 0 probe-hub debug-usb-flags fshowprobe and if cr then 0 > source probe ok 2 > _
 * ok

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.

Disclaimer
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 gaurentee 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.

Transition to EFI

 * Apple's Transition from Open Firmware to Extensible Firmware Interface