Open Firmware

Open Firmware is the boot loader software on PCI-based macintosh computers. (No, it is not just macs-- a number of other systems, including IBM's ppc offerings and some others, use OF.) Open Firmware is designed to work totally independent of whatever hardware or processor it may be running on-- it's simply an abstract, standard way to locate an operating system and boot it. It also gives plug-in cards a way to interface with the OS (or even boot the OS _from_ the card) without having to write a hardware-specific firmware (or even be aware of what the hardware is). It has all kinds of other nifty features i don't understand, and despite all this functionality it still manages to make simple things very simple. It is based around a built-in Forth interpreter, and everything (even device drivers) that happens in Open Firmware is done with processor-independent interpreted Forth (They call this "FCode") rather than platform-tied compiled machine code.

Open Firmware was begun by Sun. Sun had a number of different systems they were going to be shipping with totally different hardware configurations and different processors, and they wanted some simple, common way to interface booting and pci cards across all of them. So they set up a system written by Sun employee Mitch Bradley that was at the time called OpenBoot and later changed to Open Firmware.

Apple, facing pretty much the same dilemma, began using Open Firmware on the Power Macintosh 7200 (which was also, by the way, the first PCI-based mac). This is, blessedly, one of many reasons Macs neither have nor need a BIOS, and also basically eliminates the need for things like LILO-- booting into a linux partition which you have lost the boot floppy for is nearly impossible on a PC unless LILO is installed, and installing LILO is nearly impossible to do unless you're booted into linux, but in Open Firmware it's a single command. (I'm gonna get flamed for that one, i can tell.) Apple made some interesting enhancements to the original Open Firmware starting with the imac, which included the ability to boot over a drive located somewhere on the network the computer is attached to via ethernet (it uses bootp).If you want to boot into Open Firmware on a mac, hold down command-option-O-F on startup, and you will be presented with a nice little command-line interface (which, amazingly enough, uses a decently high screen resolution, a monaco-like font, AND is black text on a white background! ahh..). To continue normally, type 'bye'. The commands to boot a specific OS from a given place vary from mac to mac, but are well documented at linuxppc.org and other places.

That Forth interpreter i mentioned, by the way, is a complete implementation of ANSI Forth. You mostly see it used to write device drivers and LILO-esque boot loaders (yaboot, for example), although you can run pretty much anything you want in it-- freakily enough, a couple years ago some people went and wrote a complete Pong game in Forth that ran inside of Open Firmware on power macs, and as a result won an award from the MacHack conference. Yes, that's right; if you have a PCI macintosh sitting around, you can play Pong on it even if you have no hard or disk drives! I'm sure that now that you know that, you're going to all throw out all your x86 hardware and rush out to buy Power Mac G4s so that you can play Pong without an OS installed.

Open Firmware is defined by IEEE standard 1275-1994, and is part of the CHRP/PReP standard. It is also the only firmware standard in existence to have its own theme song.

For details on what exactly Open Firmware is doing, read ccunning's w/u under How an Operating System Boots. For an overview of how to use it, read The Custodian below. To see how this technology's mirror on the Sun side of things currently works, see Open Boot PROM-- note though that while some of that information may apply here and some vice versa, i'm not sure to what extent.

Quick note in response to The Custodian's writeup: if you do mess something up, be aware you can erase everything in PRAM by starting up with command-option-P-R held down, or by removing the battery on the motherboard for a few minutes.

Major Corrections (to my own material below)! Please Check!

I can't resist adding a few specific commands to mcc's excellent writeup. This came up (for me) because I was trying to install a boot loader onto my PowerMac G4/500 AGP (single processor). Naturally, I found myself at several points staring at a machine that would obstinately only boot into what was the absolutely wrong partition. Sigh. So, in the hopes of sparing some of you the angst, here is what I have learned mucking about in Open Firmware.

WARNING! This information is presented for you to use at your own risk! Mucking around in Open Firmware can make your Mac unbootable! In other words, you should only try this if all else has failed. I take no responsibility for what happens to you.

To begin with, I must reiterate one of mcc's tips. To actually get into Open Firmware at boot time, you need to do one of two things. The first thing to try (and safest) is to hold down 'Command-Option-o-f' at boot (all four keys). This should bring you to OF. If not, reboot the machine, and as soon as you hear the startup chord, press and hold the programmer's switch (the convex button on the right, of the two just below the power switch on the case). If nothing happens after ten seconds, release the programmer's switch, then press it once and let go. The machine should boot into OF.

The most useful command I found, if everything hasn't gone south, is mac-boot. This will tell OF to attempt to find a MacOS bootable partition on an internal drive and boot from it. This is useful if, for example, you've used Startup Disk to set the startup volume to one that now doesn't work; the mac-boot command will usually get the Mac to boot into MacOS so that you can undo the Startup Disk setting.

If you need to boot off another device, here's the skinny. The command is boot . Open Firmware device paths are funny things. Here are some examples of aliases, which function as shortcuts to full device paths, that are present on the PowerMac G4:

• ultra0: - this is the master drive of the first internal IDE controller (usually the Mac OS drive as it's shipped from the factory).
• ultra1: - this is a slave drive on the same controller.
• cd: - the cdrom (or DVD), as shipped.
• zip: - the internal Zip drive as shipped.

These are (very, very) shorthand. As an example, the full OF device path to my primary IDE drive (referred to as ultra0 above) is:

/pci@f2000000/@d/mac-io@7/ata-4@1000/disk@0

Those handy aliases above were placed in my PowerMac G4 by Apple so as to not force their techs to need to remember the above monstrosity, especially since the path will change from machine to machine depending on its configuration. To get a list of the aliases on your machine, enter OF and type devalias and hit return.

Open Firmware looks for a boot script of type 'tbxi' on the partitions it finds on that device. If it finds one, it boots that partition immediately. You can force a specific partition by inserting the partition number immediately after the colon, remembering that partition numbers start at '1' not '0'. So, for example, to boot off the second partition of the slave IDE hard drive on interface 0, you'd use: boot ultra1:2

Useful, huh? :-) Okay, what else. It's possible you have a SCSI drive on your machine, attached to a PCI SCSI card like the Adaptec 2930. You can still get to this device from open firmware. You'll just need to specify the entire OF device path. To find the device path, use the command dev / ls. The spaces between the three terms are essential! This should produce an enormous listout of your hardware, done as a tree. At the root level (leftmost column) somewhere will be your pci bus, labeled something like pci@f2000000. Traverse the tree down from there until you locate the adaptec card (labeled either 'scsi' or 'adaptec'. The complete path can then be used to boot the machine, adding the requisite drive number on at the end. Note that you should first check devalias; it's possible there's an alias defined for it already.

If you think the machine has gone totally strange on you, the command reset-all will restore all settings as if you'd just powered on, and reboot the machine.

Here's a list of some commands:

• setenv variable value: set an environment variable variable to value.
• printenv variable: list out the contents of environment variable. With no variable, lists all.
• devalias: print out list of current aliases
• devalias device alias: create an alias for the device at OF path device
• dev device: set the 'current device' to device
• ls: list subdevices of current device (listing device '/' lists all)
• properties: list properties of current device (Note:Potatoswatter informs me this should be .properties - note period!)

Hope this helps someone!

---

Sources include FAQs from the Linux on PowerPC Faq-o-matic, Yellow Dog Linuxand LinuxPPC, and mucking around with my PowerMac G4.

A few other notes about OF. First, in the unfortunate event of your Mac becoming unbootable, you can use the catch-all fix of zapping the PRAM. Hold down command-option-shift-p as you reset the machine. This will zap all the settings to their factory default, meaning you should at least be able to boot MacOS, if nothing else.

Secondly, all PCI based Macs have Open Firmware, but it's a little harder to access on OldWorld Macs. It's not impossible, however. These machines defaulted to serial terminal I/O for Open Firmware (which is pretty dumb, considering pretty much every Mac ever made has had a monitor and keyboard attached to it). You need a program called BootVariables (which is becoming annoyingly hard to find...but, you can, as of this writing, downlaod it from http://wuarchive.wustl.edu/systems/unix/NetBSD/arch/macppc/macos-utils/bootvars/bootvars1.3b.sit.hqx), which will let you change the the NVRAM settings within MacOS. Open the program, and, if you're on a OldWorld Mac, note the input-device and output-device fields are both set to "ttya", which is the printer serial port. You can change the input device to "kbd" to get it to accept input from the keyboard. Unfortunately, the output-device is a little more complicated. Under MacOS 8.x or higher, open the Apple System Profiler and click the "Devices and Volumnes" tab. Undepress the "Display card" arrow and note the "Card name". On my old my UMAX clone with a Rage 128 Orion PCI card, this was "ATY,Rage128o". Clones with an IMS card will look more like "IMS,tt128mb", There will always be a comma in the name, though.

Now, enter in the output-device "/bandit/ATY,Rage128o", or whatever your card is. Note that it's only /bandit for the Bandit PCI bus on newer Macs. Early first-generation OF Macs had onboard video, in which case the output-device is simply "/chaos/control". Once you've got that all set, click "Write&reboot" in BootVariables and hold down the command-option-o-f hotkey. If you're lucky, you should now the see the white Open Firmware screen on your monitor. Note that the NVRAM seems to reset when you power the machine off, so you'll need to reenter the devices each time you want to go into OF. Good luck.

Open Firmware is extremely cool. It's not just something to write boot loaders in, it's a real operating system. But more than that, it's just really, really neat.

First off, there's the nature of Forth, Open Firmware (from here on OF)'s language. Forth is a highly functional language. You generally write little simple functions, and build on them in higher-level (but still small) functions up to the top of the program.

The thing is, every function you define is actually compiled! So although it's stored as machine-independent ASCII Forth source or FCode, it's executed natively, very fast. And it's compact from the functionalism.

Next is the driver support. From OF, you can access your Mac's disk drives, flash its blinkenlights, control its graphics with some basic drawing commands, handle user input from the keyboard and mouse, and, if you're into lower-level stuff, fool with logical-to-physical memory mapping and turn a multiprocessing Mac's CPUs on and off (tho that last I haven't done yet). When I write an OS, it'll just keep OF alive in a process space and access the drivers every Mac has in firmware.

So how do you learn how to use this wonderful creature? There isn't much documentation out there. The best resource I've seen is Sun's documentation for OpenBoot, which is essentially the same thing. Google for the Sun OpenBoot AnswerBook. It's tedious to look through the big dictionary appendix, tho. If you want something more convenient, get the IEEE 1275 spec from Global Engineering Documents. That might be a little expensive for the hobbyist tho, and it comes in an unhandsomely unbound stack of white copier paper :v(.

Aside from that, look at the Forth built into your Mac by using the see and sifting commands. See (someword) gives you a pretty-printed disassembly, and sifting (string) gives you all the words containing a given string.

Just a few corrections to the above posts... an OF program, in FCode, resides on every Mac PCI card. Its main purpose is to allow a booting system to build a schematic of itself and its peripherals, and its peripherals' peripherals, which is saved in the Name Registry (in the case of the Mac OS). Bootloader stuff is kind of a secondary function that OF takes on because it's such a good general-purpose OS. Many of OF's more advanced features result from the demands of dealing with a filesystem on disk and interacting with the user.

Also, the standard is ANS Forth, not ANSI. Not to be anal.

OFPong runs as a file loaded into OF from a serial port (or, disk or network connection in the case of my OFPong 1.1). So your Mac can't really play Pong with no external storage connected. (Actually, it might be possible to load it into NVRAM, but AFAIK nobody's ever done it and it wouldn't improve the coolness factor that much.)

Finally, to reiterate the point made by everyone else here already - you can reset your Mac with cmd-opt-p-r if something goes wrong. You are very unlikely to make something go wrong, however, unless you fool with the nvset command (which you shouldn't). Using this key combo won't clear your preferences folder or anything - it mainly resets the clock, your default startup drive and startup screen.

So have fun OF-hacking. And sing the open firmware song as you do!

An educational Open Firmware story

The Summary: if you have a New World Mac, and are having trouble booting your Linux installation from the CD, find a way to copy over yaboot and a kernel image to the hard drive, and use Open Firmware to boot it.

The Story:

So a couple of years ago I bought a used Blue and White G3 off of craigslist for $100. Seemed like a good deal. However, the seller admitted a problems, the first being it was a Rev A motherboard (with the bad IDE controller, causing data corruption on IDE hard drives). After failing to install Mac OS X.2.4 a couple of times on the IDE drive he provided it with, I managed to find (on craigslist again) an Adaptec 2940U2B SCSI-2 card with a 9GB hard drive. Put that into the G3, and lo and behold, the drive had Mac OS 9 and booted perfectly!

So that was step one. The next was seeing if I could install Mac OS X from there. Booted from the CD just fine, but now instead of random freezes during install (like with the IDE drive)... it said it just could not install on this machine. Bummer. So I moved it over to the Power Macintosh 9500, and installed OS X from there. Put it back in the Blue and White, booted up OS 9, went to the Startup Disk control panel, and success, it boots OS X.

In the meantime, there has been the addition of a G4/500, more RAM, and a second 9GB hard drive. Around the same time, some instability started to develop (random freezes etc). It may be due to bad RAM or motherboard issues that OS X is unable to cope with. So while I waited to scrap together some money to try out Panther, I decided I would try Gentoo Linux to see how that fared for stability. Here's where more fun begins.

First of all, I cannot boot from the Gentoo CD. Or any CD, except the OS X install CD. That's a bummer, for a while I thought it was a lost cause until I saw this post on the Gentoo forums:

But good news, I was playing around in Openfirmware (apparently it does read the keyboard at least for that when the screen is black, I also tried C but still no work) and after lots of web browsing on the subject and tinkering, I manager to get it to boot from the partition where I copied the contents of the Gentoo CD. I just had to change the yaboot.conf file to point to hd:xx (partition number) and it worked!

So on my particular installation, this involved copying the contents from the Gentoo CD to the hard drive and modifying the yaboot.conf file appropriately. This took some poking around in Open Firmware (you need to figure out how your hard drive is referenced). For me, with my disks attached to a PCI card, the device name was something like "bridge/ADPT,2940U2B@4/@0:6". This needs to be correct so yaboot can correctly find the kernel. Also make sure the root device is left as the RAM disk or else things the boot-up will fail.

So I boot into Open Firmware (start up with command+option+O+F) and type in "boot bridge/ADPT,2940U2B@4/@0:6,\boot\yaboot". And lo and behold, I get the Linux kernel/Gentoo Live CD set up. After setting up Gentoo just a couple of things I noticed:

• If you have an adaptec card, during the live cd setup get into the modules directory and find the aic7xxx module and run insmod
• When you compile the kernel, make sure you compile aic7xxx support INTO THE KERNEL AND NOT AS A MODULE or else it won't be able to find your root device
• Linux, at this point, seems much more tolerant of whatever is wrong with my system than OS X is

It's good to make a note of the Open Firmware devices names of your disks once you start messing with yaboot and Open Firmware... if something breaks, you want to be able to drop into OF and get something to boot up. A couple of good commands are:

• "boot <device name here>" (boots from that device); one example is "boot bridge/ADPT,2940U2B@4/@0:6,\System\Library\CoreServices\BootX" this boots OS X for me... the standard entry of "device,\\:tbxi" doesn't work on my machine (and if you're reading this probably not yours either)
  
• "dev / ls"  Prints out the device tree
• "devalias" prints out a list of known aliases. For instance, "bridge" in the above examples is short for some long name for the PCI bridge

For something more comprehensive head over to Apple Developer Connection's library and do a search for "open firmware"
http://developer.apple.com/technicalnotes/
Other reference:
http://forums.gentoo.org/viewtopic.php?t=171092