Forth Lesson 10

Review

In the previous lesson, we learned:

• The purpose and basic structure of the Open Firmware Device Tree
• The syntax for device specifiers, including pathnames and devaliases
• How to list the device nodes with "show-devs"
• How to browse the device tree with "dev" and ".properties"

Device Methods

Device nodes also have "methods". Whereas properties are static information - strings and numbers - describing the device, methods are subroutines (actually Forth words) that exercise the device's hardware functionality. The collection of methods in a device node is a driver for the device.

You can choose a device node and list its methods with, for example:

  ok dev /pci
  ok words

You can look inside (decompile) a method with, for example:

  ok see open

"see" is the same Forth decompiler that was described in a previous lesson.

Although device methods are Forth words, they cannot be executed in isolation. You must first set up an execution context so the device can get services from other devices and helper functions. That will be described later.

Standard Device Methods

Use "dev" and "words" to look at the list of methods for several device nodes (recall that "show-devs" will show you some node names, and that you can use "lazy pathnames" to reduce typing).

Notice that most device nodes have "open" and "close" methods. "open" prepares the device for subsequent use, "close" shuts it down.

There are other standard methods, depending on what kind of device it is. Data transfer devices have "read" and "write" methods, which transfer data between the device and memory.

Bus bridges have methods like "map-in", "map-out", "dma-map-in" and "dma-map-out", which let the device node's children set up access to their registers and DMA resources. Bus bridges also have methods like "encode-unit" and "decode-unit", which let OFW resolve pathnames with bus-dependent physical address representations.

In order to be used for a given purpose, for example network booting, a node must implement a stipulated set of methods. (It can also implement additional ones if desired). For example, network devices must implement "open", "close", "read" and "write" methods that behave in a certain way, and can then be used with OFW's network protocol stack for things like booting from HTTP servers.

The standard "selftest" method tests the device's functionality; it is useful for system diagnostics.

Nodes can also have device-specific methods with arbitrary names. The Open Firmware standard defines the methods that apply to all systems. Supplementary "binding" documents define additional methods for special circumstances.

Support Packages

Some device tree nodes are not associated with specific devices. The nodes underneath "/packages" are "support packages" - collections of Forth words that are not tied directly to a specific device, but which help other drivers do their jobs. They serve the same purpose as Linux libraries.

Examples include "/packages/disk-label", which understands disk partition table formats, and "/packages/obp-tftp", which is a network protocol stack.

When drivers are opened, they often invoke one or more support packages.

Other Nodes

There are a few nodes that are neither drivers nor support packages. They typically provide information about the OFW system in general.

"/options" contains properties that report configuration settings (the same information that the "printenv" command, which we haven't seen yet, displays).

"/openprom" contains properties that identify the firmware version.

"/aliases" contains the list of devaliases in property form (the same information that "devalias" displays).

"/chosen" contains properties that reflect dynamic choices such as the device that was used to boot the OS.

"/client-services" contains methods that a booted program can call to use OFW's drivers.

Thus endeth the lesson

Next Lesson: Device Instances