Section 4.7. Open Firmware Interfaces

4.7. Open Firmware Interfaces

When we enumerated Open Firmware's key features, we noted that it provides multiple interfaces: for end users, for client programs, and for device vendors.

4.7.1. The User Interface

In this chapter, we have so far used Open Firmware's user interface to interact with it. We likened the Forth interpreter's command-line feature to a Unix shell. The user interface provides a set of words for interactively performing various Open Firmware functions such as managing configurations; debugging hardware, firmware, and software; and controlling aspects of booting.

4.7.2. The Client Interface

Open Firmware provides a client interface that its clients may use. A client is a programsuch as a bootloader or an operating systemthat is loaded and executed by Open Firmware. As we will see shortly, in the case of Mac OS X, Open Firmware's primary client is BootX, the bootloader. Examples of important services provided through the client interface include the following.

• It provides access to the device tree: walking and searching the tree, opening and closing devices, performing I/O on devices, and so on. In particular, a client uses this interface to access devices that may be critical for booting, such as console, network, and storage devices.

• It provides capabilities for allocating, deallocating, and mapping memory.

• It facilitates transfer of control during the boot process.

The device tree contains standard system nodes such as /chosen, /openprom, and /options. These nodes play important roles in the client interface. We will take a look at them when we discuss the bootloader.

Typically, you need to open a device and get an instance handle before you can call the device's methods. This can be achieved by using a method such as open-dev, although there are other approaches, including shortcut methods that open a device, call a specified method in it, and close itall in a single invocation. Opening a device using open-dev causes all devices in the chain to be opened. We will frequently use the following idiom for calling device methods in our programming examples:

0 value mydevice " devicename" open-dev to mydevice arg1 arg2 ... argN " methodname" mydevice $call-method

4.7.3. The Device Interface

Open Firmware's third interface is the device interface, which exists between Open Firmware and a developer's device. The expansion ROM in a plug-in device contains an FCode program that uses the device interface. This allows Open Firmware to identify the device during probing, to characterize it, and to possibly use it during booting.