OpenBoot 3.x Command Reference Manual

The Device Tree

Devices are attached to a host computer through a hierarchy of interconnected buses. OpenBoot represents the interconnected buses and their attached devices as a tree of nodes. Such a tree is called the device tree. A node representing the host computer's main physical address bus forms the tree's root node.

Each device node can have:

Properties, which are data structures describing the node and its associated device

Methods, which are the software procedures used to access the device

Data, which are the initial values of the private data used by the methods

Children, which are other device nodes "attached" to a given node and that lie directly below it in the device tree

A parent, which is the node that lies directly above a given node in the device tree.

Nodes with children usually represent buses and their associated controllers, if any. Each such node defines a physical address space that distinguishes the devices connected to the node from one another. Each child of that node is assigned a physical address in the parent's address space.

The physical address generally represents a physical characteristic unique to the device (such as the bus address or the slot number where the device is installed). The use of physical addresses to identify devices prevents device addresses from changing when other devices are installed or removed.

Nodes without children are called leaf nodes and generally represent devices. However, some such nodes represent system-supplied firmware services.

Device Path Names, Addresses, and Arguments

OpenBoot deals directly with hardware devices in the system. Each device has a unique name representing the type of device and where that device is located in the system addressing structure. The following example shows a full device path name:

/sbus@1f,0/SUNW,fas@e,8800000/sd@3,0:a

A full device path name is a series of node names separated by slashes (/). The root of the tree is the machine node, which is not named explicitly but is indicated by a leading slash (/). Each node name has the form:

driver-name@unit-address:device-arguments

Table 1-1 describes each of these parameters.

Table 1-1 Device Path Name Parameters


Path Name Parameter	Description
`driver-name`	A human-readable string consisting of one to 31 letters, digits and punctuation characters from the set "`,` `.` `_` `+` `-` " that, ideally, has some mnemonic value. Uppercase and lowercase characters are distinct. In some cases, this name includes the name of the device's manufacturer and the device's model name, separated by a comma. Typically, the manufacturer's upper-case, publicly-listed stock symbol is used as the manufacturer's name (e.g. `SUNW,sd`). For built-in devices, the manufacturer's name is usually omitted (e.g. `sbus`).
`@`	Must precede the address parameter.
`unit-address`	A text string representing the physical address of the device in its parent's address space. The format of the text is bus dependent.
`:`	Must precede the arguments parameter.
`device-arguments`	A text string, whose format depends on the particular device. It can be used to pass additional information to the device's software.

The full device path name mimics the hardware addressing used by the system to distinguish between different devices. Thus, you can specify a particular device without ambiguity.

In general, the unit-address part of a node name represents an address in the physical address space of its parent. The exact meaning of a particular address depends on the bus to which the device is attached. Consider this example:

/sbus@1f,0/esp@0,40000/sd@3,0:a

1f,0 represents an address on the main system bus, because the SBus is directly attached to the main system bus in this example.

0,40000 is an SBus slot number (in other words, 0) and an offset (in other words, 40000), because the esp device is at offset 40000 on the card in SBus slot 0.

3,0 is a SCSI target and logical unit number, because the disk device is attached to a SCSI bus at target 3, logical unit 0.

When specifying a path name, either the @unit-address or driver-name part of a node name is optional, in which case the firmware tries to pick the device that best matches the given name. If there are several matching nodes, the firmware chooses one (but it may not be the one you want).

For example, using /sbus/esp@0,40000/sd@3,0 assumes that the system in question has exactly one SBus on the main system bus, making sbus as unambiguous an address as sbus@1f,0. On the same system, however, /sbus/esp/sd@3,0 might or might not be ambiguous. Since SBus accepts plug-in cards, there could be more than one esp device on the same SBus bus. If there were more than one on the system, using esp alone would not specify which one, and the firmware might not choose the one you intended.

As another example, /sbus/@2,1/sd@3,0 would normally be unambiguous, while /sbus/scsi@2,1/@3,0 usually would not, since both a SCSI disk device driver and a SCSI tape device driver can use the SCSI target, logical unit address 3,0.

The :device-arguments part of the node name is also optional. Once again, in the example:

/sbus@1f,0/scsi@2,1/sd@3,0:a

the argument for the disk device is a. The software driver for this device interprets its argument as a disk partition, so the device path name refers to partition a on that disk.

Some implementations also enable you to omit path name components. So long as the omission does not create any ambiguity, those implementations will select the device that you intended. For example, if our example system had only one sd device,/sd:a would identify the same device as the much longer preceding expression.

Device Aliases

A device alias, or simply, alias, is a shorthand representation of a device path.

For example, the alias disk may represent the complete device path name:

/sbus@1f,0/esp@0,40000/sd@3,0:a

Systems usually have predefined device aliases for the most commonly used devices, so you rarely need to type a full device path name.

Table 1-2 describes the devalias command, which is used to examine, create, and change aliases.

Table 1-2 Examining and Creating Device Aliases


Command	Description
`devalias`	Display all current device aliases.
`devalias` `alias`	Display the device path name corresponding to alias.
`devalias` `aliasdevice-path`	Define an alias representing device-path. If an alias with the same name already exists, the new value supersedes the old.

User-defined aliases are lost after a system reset or power cycle. If you want to create permanent aliases, you can either manually store the devalias command in a portion of non-volatile RAM (NVRAM) called nvramrc, or use the nvalias and nvunalias commands. (See Chapter 3, Setting Configuration Variables, for more details.)

Displaying the Device Tree

You can browse the device tree to examine and modify individual device tree nodes. The device tree browsing commands are similar to the SolarisTM ^TMcommands for changing, displaying and listing the current directory in the Solaris directory tree. Selecting a device node makes it the current node.

The User Interface commands for browsing the device tree are shown in Table 1-3.

Table 1-3 Commands for Browsing the Device Tree


Command	Description
`.properties`	Display the names and values of the current node's properties.
`dev` `device-path`	Choose the indicated device node, making it the current node.
`dev` `node-name`	Search for a node with the given name in the subtree below the current node, and choose the first such node found.
`dev ..`	Choose the device node that is the parent of the current node.
`dev /`	Choose the root machine node.
`device-end`	Leave the device tree.
`"` device-path`" find-device`	Choose device node, similar to `dev`.
`ls`	Display the names of the current node's children.
`pwd`	Display the device path name that names the current node.
`see` `wordname`	Decompile the specified word.
`show-devs [device-path]`	Display all the devices directly beneath the specified device in the device tree. `show-devs` used by itself shows the entire device tree.
`words`	Display the names of the current node's methods.
`"` `device-path" select-dev`	Select the specified device and make it the active node.

.properties displays the names and values of all the properties in the current node:

ok dev /zs@1,f0000000 
ok .properties 
address               ffee9000 
port-b-ignore-cd 
port-a-ignore-cd 
keyboard 
device_type           serial 
slave                 00000001 
intr                  0000000c  00000000 
interrupts            0000000c 
reg                   00000001  f0000000  00000008 
name                  zs
ok

dev sets the current node to the named node so its contents can be viewed. For example, to make the ACME company's SBus device named "ACME,widget" the current node:

ok dev /sbus/ACME,widget

find-device is essentially identical to dev differing only in the way the input pathname is passed.

ok " /sbus/ACME,widget" find-device

Note -

After choosing a device node with dev or find-device, you can't execute that node's methods because dev does not establish the current instance. For a detailed explanation of this issue, refer toWriting FCode 3.x Programs.

show-devs lists all the devices in the OpenBoot device tree, as shown in the following example:

ok show-devs 
/SUNW,UltraSPARC@0,0
/sbus@1f,0
/counter-timer@1f,3c00
/virtual-memory
/memory@0,0
/aliases
/options
/openprom
/chosen
/packages
/sbus@1f,0/cgsix@1,0
/sbus@1f,0/lebuffer@0,40000
/sbus@1f,0/dma@0,81000
/sbus@1f,0/SUNW,bpp@e,c800000
/sbus@1f,0/SUNW,hme@e,8c00000
/sbus@1f,0/SUNW,fas@e,8800000
/sbus@1f,0/sc@f,1300000
/sbus@1f,0/zs@f,1000000
/sbus@1f,0/zs@f,1100000
/sbus@1f,0/eeprom@f,1200000
/sbus@1f,0/SUNW,fdtwo@f,1400000
/sbus@1f,0/flashprom@f,0
/sbus@1f,0/auxio@f,1900000    
/sbus@1f,0/SUNW,CS4231@d,c000000
/sbus@1f,0/SUNW,fas@e,8800000/st
/sbus@1f,0/SUNW,fas@e,8800000/sd
/openprom/client-services
/packages/disk-label
/packages/obp-tftp
/packages/deblocker
/packages/terminal-emulator
ok

Here is an example of the use of words:

ok dev /zs 
ok words 
ring-bell  	    read           remove-abort? 	install-abort   
close      	    open           abort?        	restore 
clear          reset          initkbdmouse	   keyboard-addr mouse 
1200baud       setbaud        initport       port-addr