Section 4.4. Open Firmware

4.4. Open Firmware

Open Firmware originated at Sun Microsystems in 1988. The "pizza-box" SPARCstation 1 was released in 1989 with OpenBoot 1.0, the first shipping implementation of Open Firmware. The firmware standard was later adopted by Apple, IBM, and other vendors such as those creating ARM-based^[7] and PowerPC-based embedded systems. Sun's implementation is trademarked as OpenBoot, whereas Apple simply calls it Open Firmware. The Open Firmware Working Group was formed in 1991, with one of its goals being to publish relevant information on Open Firmware, including recommended practices.

^[7] ARM originally stood for Acorn RISC Machine and later stood for Advanced RISC Machine.

Open Firmware is a nonproprietary, platform-independent, programmable, and extensible environment for use in boot ROMs. Its key features include the following:

• The Open Firmware software architecture is defined by the IEEE Standard for Boot (Initialization Configuration) Firmware standard, which is also known as IEEE 1275. The standard is open and anybody may create an implementation. However, note that the IEEE withdrew the standard in 1999.^[8]

  ^[8] The IEEE's withdrawal of the standard does not mean that the standard has been abandoned. It means only that the standard is no longer supported or made available by the IEEE. Vendors such as IBM, Sun, and Apple continue to use and improve Open Firmware.

• Open Firmware's architecture is independent of the underlying instruction set, busses, other hardware, and operating system. However, the core requirements and practices specified by the standard are augmented by platform-specific requirements. For example, processors such as PowerPC and SPARC, or busses such as PCI and Sun's SBus, all have their own requirements and bindings. The union of the core and platform-specific requirements provides a complete firmware specification for a given platform.

• Open Firmware exposes various interfaces such as one for interaction with the end user, another for use by operating systems, and yet another for use by developers of plug-in devices. It presents a machine's various hardware components and their interconnections in the form of a hierarchical data structure: the device tree.

• An Open Firmware implementation is based on the Forth programming language, in particular, the FCode dialect. FCode is an ANS-compliant^[9] dialect that supports compilation of source to machine-independent bytecode. This allows FCode drivers to be used on different platforms. Moreover, FCode bytecodes need less storage space than Forth textual strings do. They are also evaluated faster than Forth text. An FCode evaluator is part of a ROM-resident Open Firmware implementation.

  ^[9] ANS stands for American National Standards.

• Open Firmware is modular in the sense that many features of the architecture are optional for an implementation. Moreover, if certain plug-in devices are required at boot time, the expansion ROMs on the cards for such devices can contain FCode-based drivers. As an Open Firmwareequipped machine is turned on, the main ROM begins execution. It probes both onboard and plug-in devices, as part of which the FCode programs on the plug-in ROMs are also executed. Consequently, such plug-in device drivers become part of the Open Firmware environment. A plug-in FCode driver's references to procedures in the main firmware are resolved in a linking process similar to one involving shared libraries in a traditional execution environment. Note that FCode is position-independent.

• Open Firmware provides useful facilities for diagnosing hardware and for debugging its own programs as well as the operating system.

4.4.1. Interacting with Open Firmware

In the rest of the discussion, we will use the term Open Firmware to refer to Apple's implementation, unless otherwise stated.

You can enter Open Firmware by keeping the key combination pressed for a few seconds just as you power-on or reset the machine. After seeing a welcome message and other verbiage, you will be dropped into a prompt like the following:

 ok 0 >

At this point, you may continue booting the machine by typing mac-boot, reinitialize the hardwareincluding Open Firmware's data structuresby typing reset-all, or shut the machine down by typing shut-down.

Let us now look at several ways of interacting with Open Firmware.

4.4.1.1. Forth Shell

Open Firmware's ok prompt represents a Forth command interpreter: a shell. Apple's implementation includes the optional command-line editor extensions that provide some powerful editing features, most of which should be familiar to users of the EMACS editor. Table 42 lists some examples of commonly used key combinations. The ^ character represents the control key.

Table 42. Key Combinations for Open Firmware Command-Line Editing

Keys	Purpose
^<space>	Complete the preceding word.[a]
^/	Show all possible matches.[b]
^a	Go to the beginning of the line.
^b	Go backward one character.[c]
esc-b	Go backward one word.
^d	Erase the character over the cursor.
esc-d	Erase the word beginning at the character over the cursor, to the end of the word.
^e	Go to the end of the line.
^f	Go forward one character.[c]
esc-f	Go forward one word.
^h	Erase the previous character.
esc-h	Erase from the beginning of the word to the character before the cursor.
^k	Erase from the cursor to the end of the line.
^l	Display the command-line history.[d]
^n	Go to the next line.[c]
^p	Go to the previous line.c
^u	Erase the entire line.
^y	Insert the contents of the save buffer before the cursor.[e]

^[a] Does not show all possible matches.

^[b] Does not complete the preceding word.

^[c] You can also use the arrow keys to move up (^p), down (^n), left (^b), and right (^f).

^[d] The command h N executes the contents of history line number N.

^[e] Commands that erase more than one character cause the erased characters to be stored in a save buffer.

Despite the command-line editing extensions, the Open Firmware "shell" might not be suitable for an edit-run-debug cycle, particularly if nontrivial code is involved. Let us look at other alternatives that are likely to be better for serious Open Firmware programming endeavors.

4.4.1.2. Telnet

Open Firmware includes the telnet support package,^[10] which you can use to access the Forth prompt over the networkfrom an arbitrary computer using a TELNET client. You can verify the presence of the telnet package as follows:

^[10] An Open Firmware package is the combination of a device node's properties, methods, and private data. It may be roughly equated to a class in the object-oriented sense. See also Section 4.6.3.

0 > dev /packages/telnet ok

If you did get an ok response, start a TELNET server in Open Firmware as follows:

0 > " enet:telnet,10.0.0.2" io

The TELNET server will use 10.0.0.2 as the IP address on the default Ethernet device. You can and should choose an appropriate local IP address. Note that although the firmware prints ok after the successful completion of most commands, hitting <ENTER> after typing the telnet command line will not result in ok being printed.

Once the TELNET server is running, you should be able to connect to Open Firmware on IP address 10.0.0.2 using a TELNET client, say, from a Windows computer. You do need to connect the two machines over Ethernet.^[11]

^[11] Ethernet ports on many modern computers, and those on all newer Apple computers, are auto-sensing and auto-configuring. Therefore, a cross-over cable is not required to connect such a computer to another computer directly.

With the TELNET solution, you can write a Forth program in your favorite text editor on a client machine, copy it, and paste it into your TELNET session. This works well, especially since operations that cannot be performed inside the TELNET sessionsuch as graphics operationswill still be performed appropriately (on the Open Firmware "server").

4.4.1.3. TFTP

It is possible to download programs from a remote machine using the trivial file transfer protocol (TFTP) and to execute them within Open Firmware. Technically, in doing this, you are simply loading a program from a boot device, which happens to be the network in this case. Similarly, programs can also be accessed from a local boot device such as a locally attached disk. However, it may be rather inconvenient to boot into the operating system to edit programs and then reboot into Open Firmware to run them.

As with the TELNET scenario, you need two machines for TFTP. We refer to the machine running Open Firmware as the client and the one running the TFTP daemon as the server. The following description assumes that the server is also running Mac OS X, although this is not a requirement.

We enable tftpd, the TFTP daemon, on the server machine by using the service command-line script.

$ service --list smtp fax-receive ... tftp $ service --test-if-available tftp $ echo $? 0 $ service --test-if-configured-on tftp $ echo $? 1 $ sudo service tftp start $ service --test-if-configured-on tftp $ echo ? 0

Beginning with Mac OS X 10.4, the TFTP service is managed by the launchd super daemon. The service script acts as a simple wrapper: It modifies the TFTP configuration file (/System/Library/LaunchDaemons/tftp.plist) by adding or removing the Disabled Boolean property, as appropriate. Thereafter, it calls the launchctl command to load or unload the TFTP job. We will discuss launchd in Chapter 5.

On older systems, service modifies /etc/xinetd.d/tftp, the TFTP configuration file for the extended Internet services daemon, by setting the disable keyword to value "no".

You can verify whether the TFTP service is indeed running by using the netstat command-line utility to display whether the default TFTP daemon portUDP port 69is being listened on.

$ netstat -na | grep \*.69 udp4       0      0  *.69                   *.* udp6       0      0  *.69                   *.*

By default, tftpd uses /private/tftpboot/ as the directory that contains files that may be downloaded by TFTP clients. If desired, a different directory may be specified in the TFTP daemon's configuration file. You should test your setup by creating a file called, say, /private/tftpboot/hello.of. The file's contents could be a trivial Forth program:

\ TFTP demo \ Some commentary is required to make Open Firmware happy. ." Hello, World!" cr

Ensure that the file is readable by everybody:

$ sudo chmod 644 /private/tftpboot/hello.of

Again, the two machines need to be on the same Ethernet. Let us assume that the IP address of the client (running Open Firmware) is 10.0.0.2 and that of the server (running tftpd) is 10.0.0.1. Next, we instruct Open Firmware to boot using TFTPthat is, to download the specified file from the specified remote machine and execute it.

0 > boot enet:10.0.0.1,hello.of,10.0.0.2;255.255.255.0,;10.0.0.1

In general, the format of the boot command for booting using TFTP is:

boot enet:<my ip>,<file>,<server ip>;<netmask>,;<gateway ip>

If you connect the two machines directly with an Ethernet cable, you must use the server's IP address as the gateway address as well.

If all goes well, the boot command line should result in the message "Hello, World!" being printed, followed by the ok prompt.

4.4.1.4. Serial Download

Open Firmware supports downloading Forth code over a serial portif one is presentand executing it. The dl command can be used for this purpose.

4.4.2. Open Firmware Emulators

Serious Open Firmware developers, such as those writing device drivers, should consider using an Open Firmware emulator that runs on a standard host operating system. A good emulator may implement a comprehensive Open Firmware environment along with a set of peripheral devicesperhaps even including the graphics extensions. The details and availability of such emulators are beyond the scope of this book.