Device Tree

The device tree is a data structure providing a description of the hardware topology and device properties of a given device. The hardware topology is specified in terms of parent/child relationships. Device properties associated with each device node in the tree are device specific.

A device property is a name/value pair. The property name is a null terminated ASCII string. The property value is a stream of bytes specified by the length/address pair. Note that the property value format is property specific and has to be standardized between the property producer and its consumers.

For instance, among all device node properties, there are some related to the bus resources allocated to the device (for example, interrupt lines, I/O registers, DMA channels). These properties must be standardized to be understood by the bus driver, as well as any device drivers connected to the given bus.

The device tree data structure may be built either statically or dynamically.

• In the static case, the device tree is populated by the system booter.

  For instance, the system booter may include a pre-defined sequence of device tree function calls. Another possibility for the system booter is to build the device tree from a hardware description provided by firmware.

• In the dynamic case, the device tree is populated at system initialization time using an enumeration/probing mechanism. The device tree is populated by propagating from parent to children.

Note that it is possible to combine both methods. In other words, an initial (incomplete) device tree may be provided by the ChorusOS operating system booter, which will later be completed dynamically using an enumeration/probing mechanism. In any case, the device tree structure can be modified (extended/truncated) dynamically at run time using hot-plug insertion/removal service (for example, when using PCMCIA cards).

Device Tree related services are described below. See the man pages for complete descriptions of the commands listed:

Device Tree Browsing

dtreeNodeRoot

returns the root device node

dtreeNodeChild

returns the first child node

dtreeNodePeer

returns the next "sibling" device node

dtreeNodeParent

returns the parent device node

dtreePathLeng

returns the pathname length of the given device node

dtreePathGet

returns, in buf, the absolute pathname of the given device node. The trailing part of the pathname is the name of the node and is read in a node property. If this property does not exist, the trailing part of the returned pathname is set to '???'.

Device Tree Modification

dtreeNodeAlloc

allocates a new device node object

dtreeNodeFree

releases all memory and properties attached to the node

dtreeNodeAttach

adds a child node to the specified parent

dtreeNodeDetach

detaches a node from its parent

Device Node Properties

dtreePropFind

return the first property of a node

dtreePropFindNext

return the next property of a node

dtreePropLength

returns the property value length (in bytes)

dtreePropValue

returns a pointer to the first byte of the property value

dtreePropName

returns a pointer to the property name

dtreePropAlloc

allocates a new device property object

dtreePropFree

releases the memory allocated by the property object

dtreePropAttach

attaches a property object to a device node

dtreePropDetach

detaches a property object from a device node

Device tree high-level services

dtreeNodeAdd

adds a named device node to the tree

dtreeNodeFind

looks for a named node in the list of children of a given device node

dtreePropAdd

allocates a new property, sets its value and attaches it to a given device node