NAME | SYNOPSIS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES | SEE ALSO
#include <dki/dki.h>DevNode dtreeNodeRoot(void);
DKI
Provides device tree operations.
The device tree is a data structure which provides a description of the hardware topology and device properties. 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 sequence of bytes specified by the length / address pair.
Note that the property value format is property specific and has to be standardized between the given producer and its consumers. For instance, among all device node properties there are some properties related to the bus resources required/allocated for the device (for instance, interrupt lines, I/O registers, DMA channels).
These types of properties must be standardized in order to be understood by the bus driver as well as by 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 booter . For instance, the booter may include a pre-defined sequence of device tree function calls. Another use of the 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 parents to children.
Note that it is possible to combine both methods. In other words, an initial (non complete) device tree may be provided by the booter which will later be completed dynamically using an enumeration/probing mechanism. However it is implemented, the device tree structure can be modified (extended/truncated) dynamically at run time using hot-plug insertion/removal (for example, PCMCIA cards). The device tree API is described in detail below.
This section describes APIs related to device tree browsing.
DevNode
is an abstract type designating a device node object, and is
opaque to the driver.
dtreeNodeRoot returns the root device node if the device tree is not empty, otherwise NULL is returned.
dtreeNodeChild returns the first child node from the list of children. NULL is returned when the list of children is empty.
dtreeNodePeer returns the next device node from the sibling list, if any, otherwise NULL is returned. The node argument specifies the current device node in the sibling list.
dtreeNodeParent returns the parent device node, if any, otherwise NULL is returned. The node argument specifies the child device node.
dtreePathLeng returns the pathname length of a device node.
dtreePathGet returns in buf the absolute pathname of a device noe. The trailing path, of the pathname, is the name of the node and is read in a node property. If this property does not exist, the trailing path of the returned pathname is set to '???'.
This section describes APIs related to device tree topology modification.
dtreeNodeAlloc allocates a new device node object. A non zero DevNode cookie is returned in case of success, otherwise NULL is returned. The allocated node has neither parent nor child nodes. There are no properties attached to the newly allocated node.
dtreeNodeFree releases the memory allocated by the node object and all property objects attached to the node. The node argument specifies the node object being released.
dtreeNodeAttach adds the device node specified by the cnode argument in the child list of the parent node specified by the pnode argument.
dtreeNodeDetach detaches the node object specified by the node argument from its parent (if any). When node specifies the root node, the device tree is emptied.
This section describes APIs related to the device node properties.
DevProperty
is an abstract type designating a device property
object, and is opaque to the driver.
dtreePropFind searches the first property within the properties list of the device node specified by the node argument. If the name argument is not NULL, dtreePropFind returns the first property whose name matches the name string. If the name argument is NULL, dtreePropFind returns the first property from the list regardless of its name.
In case of success, a non zero DevProperty cookie is returned, otherwise NULL is returned. Once the first property is found, the dtreePropFindNext routine may be used in order to find a subsequent property in the list. dtreePropFindNext searches the next property within the properties list. The current position within the properties list is specified by the prop argument. If the name argument is not NULL , dtreePropFindNext returns the next property (with respect to the current position) whose name matches the name string. If the name argument is NULL , dtreePropFindNext returns the next property from the list (with respect to the current position) regardless of its name.
If successful, a non zero DevProperty cookie is returned, otherwise NULL is returned. The dtreePropFind / dtreePropFindNext pair are typically used to iterate through either all device node properties, or a subset of device node properties whose names match a given name. In a case where a user knows that there is only one property with a given name attached to the device node, a single dtreePropFind invocation is sufficient.
dtreePropLength returns the property value length (in bytes). The property object is specified by the prop argument.
dtreePropValue returns a pointer to the first byte of the property value. The property object is specified by the prop argument. A driver can read and write the property value directly using the returned pointer. Typically, the driver will cast the pointer to a well known type/structure in order to access the property value. Note that the property value must always be presented in the CPU endian format.
dtreePropName returns a pointer to an ASCII string which designates the property name. The property object is specified by the prop argument.
dtreePropAlloc
allocates a new device property object.
A non zero
DevProperty
cookie is returned if successful, otherwise
NULL
is returned. The
name
argument specifies
the property name. The
length
argument specifies
the length of the property value. The property value is undefined. The property
object allocated is not attached to any device node. Once the property value
is initialized, the property object can be attached to a node (that is, added
to the node properties list) using the
dtreePropAttach
function.
dtreePropFree releases the memory allocated by the property object. The prop parameter specifies the property object being released. Note that the property object must not be attached to any device node.
dtreePropAttach adds the property object specified by the prop argument to the node properties list. The node argument specifies the device node to which the property will be attached.
dtreePropDetach detaches the property object from the device node to which it is attached (if any). The prop argument specifies the property object.
Note that the device tree structure must only be accessed in the DKI thread context. The DKI thread provides access synchronization to the device tree. In many cases, driver routines which typically examine or modify the device tree are already invoked by the DKI thread. For instance, the driver probing, initialization and shut-down code is executed by the DKI thread. In a case when a driver needs to access the device tree at run time, a driver routine which uses the device tree API must be explicitly called in the DKI thread context. This rule also applies to driver clients; a driver client must always switch to the DKI thread context when accessing the device tree structure.
This section describes high-level APIs built upon other basic services. This API implements certain useful services for building and searching the device tree, in order to avoid implementing this code in all device tree users.
dtreeNodeAdd allocates a new device node object, and adds it to the child list of the parent device node specified..
The
name
argument specifies the name of the new
device node allocated.. This means that a
node
property is allocated
and attached to the new node with the value specified by
name
.
If successful, the newly allocated node object is returned, otherwise, a NULL
pointer is returned.
dtreeNodeFind looks for a named node in the child list of a specified device node. The parent argument specifies the device node within which the child list should be searched. The name argument specifies the value which must match the node property value of the node being searched.. If successful, the matching node object is returned, otherwise a NULL pointer is returned.
dtreePropAdd allocates a new property, sets its value and attaches it to a given device node. The node argument specifies the node to which the new property must be attached. The name argument specifies the name of the new property to allocate. The length argument specifies the memory size in bytes to be allocated for the new property value. The value argument specifies the value to be set for the newly allocated property. If successful, the newly allocated property object is returned, otherwise, a NULL pointer is returned.
The following table specifies the contexts in which a caller may invoke each service:
Services | Base level | DKI thread | Interrupt | Blocking |
dtreeNodeRoot | - | + | - | - |
dtreeNodeChild | - | + | - | - |
dtreeNodePeer | - | + | - | - |
dtreeNodeParent | - | + | - | - |
dtreeNodeAlloc | + | + | - | + |
dtreeNodeFree | + | + | - | + |
dtreeNodeAttach | - | + | - | - |
dtreeNodeDetach | - | + | - | - |
dtreePropFind | - | + | - | - |
dtreePropFindNext | - | + | - | - |
dtreePropLength | - | + | - | - |
dtreePropValue | - | + | - | - |
dtreePropName | - | + | - | - |
dtreePropAlloc | + | + | - | + |
dtreePropFree | + | + | - | + |
dtreePropAttach | - | + | - | - |
dtreePropDetach | - | + | - | - |
dtreeNodeAdd | - | + | - | + |
dtreeNodeFind | - | + | - | - |
dtreePropAdd | - | + | - | + |
dtreePathLeng | + | + | _ | _ |
dtreePathGet | + | + | _ | _ |
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES | SEE ALSO