About This Web Page
This Web Page describes Open Firmware at an introductory level. This
description will not substitute for a course given by Firmworks or Forth
Inc on Open Firmware, but it will, I hope, give the reader a pretty good
idea of how Open Firmware presents the industry with an elegant solution
to some knotty problems of booting an operating system.
© 1996 Sabaki Engineering. Copies may be made for strictly non-commercial,
non-pecuniary purposes. All other copies require written permission from
Sabaki Engineering. Links, of course, may be freely made to this page.
A Note on Reading This Page
Since not everybody's browser has a navigation key for returning to the
previous anchor instead of to the previous
document, I have included an anchor titled "Back" for
each definition in the Glossary. But it does not take you back to
wherever you were, it takes you back to the first reference to the word
defined.
Disclaimer and Acknowledgments
This web page on Open Firmware is the exclusive work of Sabaki
Engineering. It does not represent the claims, opinions or promises of
any other legal person. We at Sabaki Engineering express our thanks to
the Open Firmware Working Group for hosting this page.
Note that all comments on this page should be directed to the author of
this page, Matthew Johnson
and NOT to the Open Firmware Working Group.
Open Firmware - A New Class of Software Tool
Open Firmware provides a novel capability, virtually unheard of before its
invention in 1988 at Sun. This new capability is writing hardware
independent boot code, firmware and device drivers.
A Brief History of Open Firmware
As mentioned above, Open Firmware was invented at Sun for release in 1988
to prevent a maintenance and support nightmare with the then unprecedented
wide choice of hardware and software configurations the new product lines
required. Open Firmware, then called Open Boot, prevented the nightmare
by allowing one version of the Boot Rom to run on any configuration of
hardware and software, even supporting boot-time operations on third-party
plug-in cards.
The idea worked so well, other major players in the computer market, such
as IBM and Apple, got in on the act as well. The existence of a
comprehensive IEEE standard for Open Firmware, IEEE-1275, makes this
possible.
Hardware Independent Boot Code? Get Real!
This is such a new capability, it defies belief. Open Firmware provides
this capability by a careful application of the FORTH philosophy. Just as
FORTH has always presented its users with unique capabilities through a
careful combination of 1) pushdown stack 2) dictionary and 3) interpreter,
so Open Firmware works because of its combination of 1) standardized
tokens=FCode, 2) User Interface~= outer interpreter 3) Device Interface ~= inner interpreter
and 4) Client Interface to allow the
OS to call Open Firmware services with the calling conventions and bindings
of a high-level language, such as C. We will see later in this web page how
all these pieces fit together to form such an amazingly flexible whole.
The Tasks of Boot Code
Before we can understand why the various pieces of OF fit together the way
they do, we must understand for what purpose they do so. This in turn
requires that we understand the basic tasks of boot code on a wide class
of systems. These tasks are largely 1) Boot-time Drivers and 2) building
a device tree, which the Operating System then uses to discover
what devices are available to it and how to use them. The particular
format of the device tree is
operating system dependent, but all device trees have a great deal in
common. That commonality can be expressed in a common language
independent of the operating system. The format of an Open Firmware
device tree is such a common language. In a typical installation, the
operating system uses Client Interface calls to translate the Open
Firmware device tree into the Operating system's own format. In the rest
of this web page, we will assume that Open Firmware is being used for such
a "typical installation", although there are cases when you might want to
use only parts of Open Firmware, such as only a Device Interface, for
"non-typical" applications.
An Open Firmware Device Tree
The Open Firmware Device Tree is a generic and simple format for a device
tree. It can be used to represent the various entries in a device tree
for just about any operating system. Like any tree, it consists of nodes,
some of which are leaf nodes, i.e. have no children. Every node has one
parent, except for the top node. Each node has a node name, and a list of
"properties" and"methods". In fact, the node name
is a property, one that is required for every node. The
properties are named data. Open firmware makes no restrictions on how the
operating system will eventually use this named data, except for reserving
certain names to have certain meanings: the "name" property, for example,
is always the node name. This named data may also be of any type: string
and integer types are specifically supported, while compound types may be
grouped together out of combinations of "int" "string" and "bytes", the
latter being for any length of arbitrary consecutive bytes.
Open Firmware Boot Drivers
The Boot Drivers supplied by Open Firmware are mainly meant for supplying
messages that must be displayed during boot time, before the operating
system has been loaded. They are also handy for other purposes, such as
debugging hardware that is failing during boot time. For such purposes,
it is not important that this sort of driver knows nothing about the
operating system (which typically hasn't even been loaded yet). These
drivers therefore do not work in the background, are not multi-taskable,
nor do they use interrupts. They provide the most basic operations on the
device, such as open, close, read and write. These operations are all
implemented as Open Firmware methods, i.e., FORTH words accessible from
the User Interface when the given device is selected. We will cover this
concept in more detail later.
This is the Open Firmware component that most closely resembles a
traditional FORTH system. On the Apple PCI Macintoshes, you enter the
Open Firmware User Interface by holding down the NMI switch while toggling
the Reset Line. Then the System Firmware, sensing these switches, goes
through a truncated boot process; instead of loading the entire system, it
starts with low-level hardware diagnostics, then loads Open Firmware,
opens the modem port (i.e. Serial Port # 1) for I/O, prints a boot message
and awaits your commands on that port, just like QUIT in a traditional
FORTH system. The method of entering the User Interface is not defined by
the IEEE-1275 standard; it is implementation dependent.
Dictionary Searching
Dictionary Searching is a little strange in Open Firmware. There are no
vocabularies in the FORTH79 or FORTH83 sense of the word. Instead, Open
Firmware supports a new and peculiar notion, the active-package. Furthermore, there are really two
sorts of definitions possible under the User Interface: conventional FORTH
words appended to the root "vocabulary", and Open Firmware methods
appended to the active-package. When the user types in a word, the User
Interface looks up the word first in the list of methods of the active-package, then in the root FORTH definitions not
attached to any package.
Clearly, the use of packages instead of the more usual sort of
vocabularies takes some getting used to. But this new sort of vocabulary
is pretty well suited for the tasks of boot-time firmware.
An even more marked difference from the traditional method of dictionary
searching is the use of $call-method or its congeners
$call-parent and call-package to call
methods not in the current search order. These words are used
frequently. We will describe the use of these words in more detail after
covering the prerequisite notion of the instance
chain.
Devices, Packages and THE Active Package
Unfortunately, the IEEE-1275 spec and the Open Firmware language itself
uses the terms "device" and "package" inconsistently. Sometimes, the two
terms are used to mean the same thing, sometimes they are not! In the
spec's own words:
A package is the combination of a device node's properties, methods and
private data. In most cases, the terms "package" and "device node" may
be used interchangeably. "Device node" is typically used when the
emphasis is on the node as a part of the device tree, and "package" is
used with emphasis on the use of the node's driver methods.
I would have been happier if they had said:
A package is the combination of a device node's properties, methods and
private data (so far, so good). "Device nodes" and "packages" are
usually strongly linked, i.e, a device node has a package associated
with it, every package has an entry in the device tree, i.e., a device
node associated with it. But there are pure software packages with no
physical device associated with them. For all other packages, the
device node and the package are two different ways of looking at the
same thing.
A simple example should make the above ideas more clear: the IEEE-1275
spec suggests (but does not require) that the default input device be
named "keyboard". In this case, there will be an entry in the device-tree
(i.e. a device node) named "keyboard", which includes methods "open",
"close" and "read". The only property it MUST contain is the "name"
property, "keyboard". For the convenience of the users, the properties
"model" (a string property naming the model number) and "compatible" (a
string property naming a more popular model with which the keyboard is
compatible) might also be included. In Apple's case, it also defines the
property "device_type", setting it equal to "serial".
The collection of all these properties, methods and whatever private data
the methods use is the package corresponding to the device "keyboard".
Now many systems will also define a pure software package, called the
"deblocker", whose purpose in life is to "deblock" a block-oriented
device, i.e., provide byte-oriented methods to access the block-oriented device. This is
analogous to the old FORTH trick of implementing virtual memory using
BLOCK, which views the disk as a block-oriented device (hence the name).
The deblocker has its own entry in the device-tree much like a true
physical device, but there are a few significant differences: it must be a
child of the node "/packages" in the device-tree, it has no address, and
it can and should be opened with"open-package" instead of with
"open-device".
Blazing the Trail to Plug and Play
Open Firmware does not solve all the problems that need to be solved to
make Plug & Play a reality in the DOS, Windows or Macintosh environments.
However,it solves some of the major problems, and provides a framework for
solving the others. If manufacturers can agree on how to use the
properties that might be defined for their devices, then this will go a
long way to making plug and play a reality. Open Firmware makes this much
simpler than ever before.
Why FORTH for all This?
Forth programmers have known for years that Forth provides a virtual
machine, consisting of a data stack, a return stack and the registers IP,
W, RP and SP. It is amazing how much computing can be done with such a
simple machine. This machine needs only a small supplement to become an
excellent virtual machine for all the tasks of boot code. This supplement
is the hardware dependent portion of the Open Firmware code, whether in
the Fcode on a plug-in card, or in the Host's Open Firmware interpreter.
Open Firmware for Debugging
In addition to providing a hardware independent method of building the
device tree and providing boot drivers, Open Firmware provides a
convenient FORTH environment for debugging new hardware and firmware.
Suppose, for example, you need to test SCSI device capability, running
with different devices in different parts of the chain of SCSI devices.
You could write an endless loop as follows:
\ Generate the path name for the drive with the given SCSI-id
: diskno 30 + pad c! pad 1 ( scsi-id -- adr cnt)
" /yourprocessorbus/XYZ,scsi@" cat2str ;
\ Use "open-dev" to open the disk w/ SCSI-ID "diskno", show the instance
\ handle, then close it.
: testdisk ( diskno --)
diskno open-dev
." ihandle= " dup .
close-dev ;
: scsi-test ( --)
begin
probe-scsi-all
7 0 do i testdisk loop
key? until ;
If you need to test the ability to do real data transfers as well, you
need only add the standard block-size/read calls via $call-method, as follows:
0 value my-ih
1000 alloc-mem constant TEST_BLOCK
: block-size ( --#bytes)
" block-size" my-ih $call-method ;
: read ( bufadr #bytes-to-read -- #actual-read)
" read" my-ih $call-method ;
: testdisk ( diskno --)
dup >r
diskno open-dev
." ihandle= " dup . to my-ih
test_block block-size read
block-size - if ." ERROR READING BLOCK Disk: " r> . else r> drop then
close-dev ;<\pre>
Glossary
-
Active-package
- the package whose methods constitute the current vocabulary
Back
-
Byte-oriented
- an Open Firmware device having device_type "byte", and methods
read, write, seek and load. These last
two differ from the block-oriented case in that they treat the device
like a tape drive.
Back
-
Block-oriented
- an Open Firmware device having device_type "block", and methods
read, write, seek and load. These last
two differ from the byte-oriented case in that they treat the device
like a disk drive.
Back
-
Device Tree
- a tree each node of which describes a
device in terms of properties and methods
Back
-
Device Interface
- the component of Open Firmware that builds the device tree, which
process is dominated by interpreting
FCode
Back
-
Client Interface
- the interface providing C calling conventions and bindings for
Open Firmware
Back
-
FCode
- Open Firmware's hardware independent byte-codes for common
operations, such as 0x47 for "duplicate top of stack" or 0x46 for "pop
stack"
Back
-
User Interface
- the "shell" of Open Firmware, which interprets FORTH words typed by the user
on the standard input.
Back
-
Properties
- data of arbitrary type describing the device type.
Back
-
Instance Chain
- A linked list of Instances. These in turn are a sort
of device context. Every time you open a device, you create an instance
of the device, adding it to the chain. They are also analogous to
multiple handles to the same file, or multiple copies of the same program
running as separate tasks in a multi-tasking operating system.
Back
-
Methods
- FORTH words attached to a package, typically for
handling driver services, e.g., "read", "write", "open" & "close"
Back
-
More Info on Open Firmware
The following Web Sites have more info on Open Firmware.
For the O.F. Working Group's Open Firmware page, click here
For informtion on FORTH in general, go to The FORTH Home Page,
by clicking here
For the Open Firmware vendor Firmworks, click here
What is Open Firmware / Sabaki Engineering / mejohnsn@netcom.com
To send an e-mail message to Sabaki Engineering click
here