Synopsis

void OF_CloseKey(
         void * Key );

Function

Release a node handle obtained from openfirmware.resource.

Inputs

Key - Node handle to close. The current implementation ignores it.

Result

None.

Notes

This is currently a no-op: no memory is freed and no reference count
is changed. The tree remains owned by the boot environment. Closing
a handle does not invalidate borrowed child or property pointers.
This function performs no allocation or wait.

See also

OF_OpenKey() OF_GetChild()

Synopsis

void * OF_FindNodeByCompatible(
         void * Start,
         char * Compatible );

Function

Find the first node whose "compatible" property contains an exact,
case-sensitive match for the requested string. Search the start
node first, then recursively search each child subtree in list
order. The whole NUL-separated compatible list is examined.

Inputs

Start - Node handle at which to start, or NULL for the tree root.
Compatible - NUL-terminated binding string. NULL is accepted and
             returns no match.

Result

The first matching borrowed node handle, or NULL for no match,
a missing root or a NULL Compatible argument.

Notes

Returned pointers refer to the boot-supplied tree; no copy is made
and ownership is not transferred. Do not modify or free this data.
The tree must remain valid while its handles or values are used.
This function performs no allocation or wait.

Start is included in the search; it is not an iteration cursor.
There is no status-property filtering: a matching disabled node
can be returned. Property strings must be well-formed and terminated
within their stored values. The search uses recursive stack space
proportional to tree depth.

See also

OF_OpenKey() OF_GetChild() OF_FindProperty()

Synopsis

void * OF_FindProperty(
         void * Key,
         char * name );

Function

Find a named property among the immediate properties of a node.

Inputs

Key - Non-NULL node handle.
name - NUL-terminated property name, matched exactly and
       case-sensitively. NULL matches no property.

Result

A borrowed property handle, or NULL if no name matches.

Notes

Returned pointers refer to the boot-supplied tree; no copy is made
and ownership is not transferred. Do not modify or free this data.
The tree must remain valid while its handles or values are used.
This function performs no allocation or wait.

See also

OF_GetProperty() OF_GetPropName() OF_GetPropLen() OF_GetPropValue()

Synopsis

void * OF_GetChild(
         void * Key,
         void * Prev );

Function

Enumerate the immediate children of a node in list order.
Pass NULL as Prev to start, then pass the previous result to advance.

Inputs

Key - Non-NULL node handle.
Prev - NULL, or the last child node handle returned for this same Key.
       It must still belong to that node's list.

Result

A borrowed child node handle, or NULL for an empty list or after
its last element.

Notes

Returned pointers refer to the boot-supplied tree; no copy is made
and ownership is not transferred. Do not modify or free this data.
The tree must remain valid while its handles or values are used.
This function performs no allocation or wait.

There is no handle-type or parent-membership validation. A non-NULL
Prev is followed directly; Key is not used to check its parent.

See also

OF_OpenKey() OF_CloseKey()

Synopsis

void * OF_GetProperty(
         void * Key,
         void * Prev );

Function

Enumerate the immediate properties of a node in list order.
Pass NULL as Prev to start, then pass the previous result to advance.

Inputs

Key - Non-NULL node handle.
Prev - NULL, or the last property handle returned for this same Key.
       It must still belong to that node's list.

Result

A borrowed property handle, or NULL for an empty list or after
its last element.

Notes

Returned pointers refer to the boot-supplied tree; no copy is made
and ownership is not transferred. Do not modify or free this data.
The tree must remain valid while its handles or values are used.
This function performs no allocation or wait.

There is no handle-type or parent-membership validation. A non-NULL
Prev is followed directly; Key is not used to check its parent.

See also

OF_FindProperty() OF_GetPropName() OF_GetPropLen() OF_GetPropValue()

Synopsis

uint32_t OF_GetPropLen(
         void * Key );

Function

Return the recorded byte length of a property value.

Inputs

Key - Property handle, not a node handle; NULL is accepted.

Result

The property's stored byte length, or zero for NULL. Zero may also
be a valid property length and does not by itself prove absence.

Notes

No data is copied or validated. The length describes raw property
bytes, not a count of integer cells or characters. The property
handle must remain valid. This function performs no allocation or
wait.

See also

OF_FindProperty() OF_GetProperty() OF_GetPropValue()

Synopsis

char * OF_GetPropName(
         void * Key );

Function

Return the name attached to a property.

Inputs

Key - Property handle, not a node handle; NULL is accepted.

Result

The borrowed name pointer for a property. For NULL, the literal
string "(null)" is returned rather than a NULL pointer.

Notes

Returned pointers refer to the boot-supplied tree; no copy is made
and ownership is not transferred. Do not modify or free this data.
The tree must remain valid while its handles or values are used.
This function performs no allocation or wait.

See also

OF_FindProperty() OF_GetProperty()

Synopsis

void * OF_GetPropValue(
         void * Key );

Function

Return direct access to the bytes of a property value.

Inputs

Key - Property handle, not a node handle; NULL is accepted.

Result

The stored value pointer, or NULL when Key is NULL. The pointer is
not a copy and does not imply that any particular length or type
is available.

Notes

Returned pointers refer to the boot-supplied tree; no copy is made
and ownership is not transferred. Do not modify or free this data.
The tree must remain valid while its handles or values are used.
This function performs no allocation or wait.

Use OF_GetPropLen() before accessing bytes. Values may be binary,
zero-length, strings or lists of strings; no NUL termination is
added. Numeric byte order and cell layout are those of the supplied
device tree: this function does not convert them to host types.

See also

OF_GetPropLen() OF_FindProperty() OF_GetProperty()

Synopsis

void * OF_OpenKey(
         char * Key );

Function

Find a node by an absolute path in the boot-supplied device tree.
Each component is matched exactly and case-sensitively against a
child node name. Unit-address suffixes are part of the name.
The path "/" returns the root; a trailing slash names the same node.

Inputs

Key - Non-NULL NUL-terminated absolute path. Use components of
      at most 63 bytes and a single slash between components.

Result

A borrowed node handle, or NULL for a relative path or a component
that cannot be found.

Notes

Returned pointers refer to the boot-supplied tree; no copy is made
and ownership is not transferred. Do not modify or free this data.
The tree must remain valid while its handles or values are used.
This function performs no allocation or wait.

The string is not modified. No alias expansion, wildcard matching,
unit-address abbreviation or dot/dot-dot resolution is performed.
OF_CloseKey() currently has no effect on the returned handle.

Bugs

An empty component terminates traversal, so repeated slashes can
return an ancestor without examining the rest of the path. Components
longer than 63 bytes are not handled as complete names and are not
reliably rejected. Use the input form described above.

See also

OF_CloseKey() OF_GetChild() OF_FindProperty() OF_FindNodeByCompatible()