NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES | SEE ALSO
#include <dki/dki.h>DevNode dtreeNodeRoot(void);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
DKI
Provides device tree operations.
The device tree is a data structure that 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 and value pair. The name property is a null terminated ASCII string. The value property is a sequence of bytes specified by the length / address pair.
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 example, interrupt lines, I/O registers, and DMA channels). These types of properties must be standardized 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 predefined 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.
It is possible to combine both methods. An initial (non-complete) device tree may be provided by the booter that will later be completed dynamically using an enumeration/probing mechanism. In whichever way 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. It 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. If the list of children is empty, NULL is returned.
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 node. The trailing path, of the pathname, is the name of the node. It 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, which is specified by the cnode argument, in the child list of the parent node. The parent node is 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. After 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.
dtreePropFind() and dtreePropFindNext() are 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 using the returned pointer. Typically, to access the property value, the driver will cast the pointer to a well known type/structure.
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. If successful, a non-zero DevProperty cookie is returned. 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. After 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.
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.
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 that 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. When a driver needs to access the device tree at run time, a driver routine that 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. To avoid implementing this code in all device tree users, this API implements certain useful services for building and searching the device tree.
dtreeNodeAdd() allocates a new device node object and adds it to the child list of the specified parent device node.
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 | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | Allowed Calling Contexts | ATTRIBUTES | SEE ALSO