openfirmware(4) manual page

The /dev/openfirm device is an interface to the Open Firmware device tree. This interface is highly stylized. It uses ioctl(2) calls for all operations. These calls refer to the nodes in the Open Firmware device tree. The nodes are represented by package handles, which are simply integer values describing data areas. Occasionally a package handle of 0 may be used or returned instead, as described below.

The calls that only take and/or return the package handle of a node use a pointer to a phandle_t for this purpose. The others use a pointer to a struct ofiocdesc descriptor, which has the following definition:

struct ofiocdesc {
        phandle_t       of_nodeid;
        int             of_namelen;
        const char      *of_name;
        int             of_buflen;
        char            *of_buf;
};

The of_nodeid member is the package handle of the node that is passed in or returned. Strings are passed in via the of_name member of of_namelen length. The maximum accepted length of of_name is OFIOCMAXNAME. The of_buf member is used to return strings except for the OFIOCSET call where it is also used to pass in a string. In the latter case the maximum accepted length of of_buf is OFIOCMAXVALUE. Generally, of_buf works in a value-result fashion. At entry to the ioctl(2) call, of_buflen is expected to reflect the buffer size. On return, of_buflen is updated to reflect the buffer contents.

The following ioctl(2) calls are supported:

OFIOCGETOPTNODE

Uses a phandle_t. Takes nothing and returns the package handle of the /options node.

OFIOCGETNEXT Uses a phandle_t. Takes the package handle of a node and returns the package handle of the next node in the Open Firmware device tree. The node following the last node has a package handle of 0. The node following the node with the package handle of 0 is the first node.

OFIOCGETCHILD Uses a phandle_t. Takes the package handle of a node and returns the package handle of the first child of that node. This child may have siblings. These can be determined by using OFIOCGETNEXT. If the node does not have a child, a package handle of 0 is returned.

OFIOCGET Uses a struct ofiocdesc. Takes the package handle of a node and the name of a property. Returns the property value and its length. If no such property is associated with that node, the length of the value is set to -1. If the named property exists but has no value, the length of the value is set to 0.

OFIOCGETPROPLEN

Uses a struct ofiocdesc. Takes the package handle of a node and the name of a property. Returns the length of the property value. This call is the same as OFIOCGET except that only the length of the property value is returned. It can be used to determine whether a node has a particular property or whether a property has a value without the need to provide memory for storing the value.

OFIOCSET Uses a struct ofiocdesc. Takes the package handle of a node, the name of a property and a property value. Returns the property value and the length that actually have been written. The Open Firmware may choose to truncate the value if it is too long or write a valid value instead if the given value is invalid for the particular property. Therefore the returned value should be checked. The Open Firmware may also completely refuse to write the given value to the property. In this case EINVAL is returned.

OFIOCNEXTPROP Uses a struct ofiocdesc. Takes the package handle of a node and the name of a property. Returns the name and the length of the next property of the node. If the property referenced by the given name is the last property of the node, ENOENT is returned.

OFIOCFINDDEVICE

Uses a struct ofiocdesc. Takes the name or alias name of a device node. Returns package handle of the node. If no matching node is found, ENOENT is returned.

[`EBADF`]
	The requested operation requires permissions not specified at the call to `open()`.
[`EINVAL`]
	The given package handle is not 0 and does not correspond to any valid node, or the given package handle is 0 where 0 is not allowed.
[`ENAMETOOLONG`]
	The given name or value exceeds the maximum allowed length of `OFIOCMAXNAME` and `OFIOCMAXVALUE` bytes respectively.

Manual Pages — OPENFIRM

NAME

CONTENTS

SYNOPSIS

DESCRIPTION

FILES

DIAGNOSTICS

SEE ALSO

HISTORY

AUTHORS

CAVEATS

`OFIOCGETOPTNODE`
	Uses a phandle_t. Takes nothing and returns the package handle of the `/options` node.
`OFIOCGETNEXT`	Uses a phandle_t. Takes the package handle of a node and returns the package handle of the next node in the Open Firmware device tree. The node following the last node has a package handle of 0. The node following the node with the package handle of 0 is the first node.
`OFIOCGETCHILD`	Uses a phandle_t. Takes the package handle of a node and returns the package handle of the first child of that node. This child may have siblings. These can be determined by using `OFIOCGETNEXT`. If the node does not have a child, a package handle of 0 is returned.
`OFIOCGET`	Uses a struct ofiocdesc. Takes the package handle of a node and the name of a property. Returns the property value and its length. If no such property is associated with that node, the length of the value is set to -1. If the named property exists but has no value, the length of the value is set to 0.
`OFIOCGETPROPLEN`
	Uses a struct ofiocdesc. Takes the package handle of a node and the name of a property. Returns the length of the property value. This call is the same as `OFIOCGET` except that only the length of the property value is returned. It can be used to determine whether a node has a particular property or whether a property has a value without the need to provide memory for storing the value.
`OFIOCSET`	Uses a struct ofiocdesc. Takes the package handle of a node, the name of a property and a property value. Returns the property value and the length that actually have been written. The Open Firmware may choose to truncate the value if it is too long or write a valid value instead if the given value is invalid for the particular property. Therefore the returned value should be checked. The Open Firmware may also completely refuse to write the given value to the property. In this case `EINVAL` is returned.
`OFIOCNEXTPROP`	Uses a struct ofiocdesc. Takes the package handle of a node and the name of a property. Returns the name and the length of the next property of the node. If the property referenced by the given name is the last property of the node, `ENOENT` is returned.
`OFIOCFINDDEVICE`
	Uses a struct ofiocdesc. Takes the name or alias name of a device node. Returns package handle of the node. If no matching node is found, `ENOENT` is returned.