NAME

openprom — OPENPROM interface

SYNOPSIS

#include < sys/types.h>
#include < sys/ioctl.h>
#include < dev/ofw/openpromio.h>

DESCRIPTION

The /dev/openfirm device is a SunOS / Solaris compatible interface to the Open Firmware device tree. This interface is similar to the openprom(4) interface. It uses ioctl(2) calls for all operations. These calls refer to the nodes in the Open Firmware device tree. However, FreeBSD only implements a subset of the ioctl(2) calls SunOS / Solaris does. The nodes are represented by integer values, which are simply describing data areas. Occasionally the number 0 may be used or returned instead, as described below.

All calls use a pointer to a struct openpromio descriptor, which has the following definition:

struct openpromio { 
 uint32_t oprom_size; 
 char  oprom_array[]; 
};

The oprom_size member refers to the size of oprom_array. The oprom_array member actually works like a union. Depending on the ioctl(2) call and whether the struct openpromio is used to pass in or return data, oprom_array either contains an integer referring to a node or a string referring to a property name or property value. The maximum size of oprom_array is OPROMMAXPARAM.

The following ioctl(2) calls are currently implemented:

OPROMNEXT

Takes the number of a node and returns the number of the next node in the Open Firmware device tree. The node following the last node is number 0. The node following number 0 is the first node.

OPROMCHILD

Takes the number of a node and returns the number of the first child of that node. This child may have siblings. These can be determined by using OPROMNEXT. If the node does not have a child, 0 is returned.

OPROMGETPROP

Takes the name of a property. Returns the property value. The OPROMGETPROP call refers to the node previously returned by either the OPROMNEXT or the OPROMCHILD call, depending on which one was invoked last. If the property referenced by the given name is not associated with that node, EINVAL is returned. If the named property exists but has no value, an empty string is returned.

OPROMNXTPROP

Takes the name of a property. Returns the name of the next property of the node. As with the OPROMGETPROP call, the OPROMNXTPROP call refers to the node previously returned by either the OPROMNEXT or the OPROMCHILD call. If the property referenced by the given name is the last property of the node, an empty string is returned.

FILES

/dev/openprom

OPENPROM interface node

DIAGNOSTICS

The following may result in rejection of an operation:

[ EBUSY]

The /dev/openprom node is already opened.

[ EINVAL]

The given node number is not 0 and does not correspond to any valid node, or the given node number is 0 where 0 is not allowed, or the given size value is invalid, or the given property name exceeds the maximum allowed length of OPROMMAXPARAM bytes.

[ ENOMEM]

The kernel could not allocate memory to copy in data from user-space or to retrieve data from the Open Firmware.

SEE ALSO

ioctl(2), openfirm(4), eeprom(8), ofwdump(8)

HISTORY

The first FreeBSD version to include the openprom interface was FreeBSD 5.0.

AUTHORS

The openprom interface was written by Jake Burkholder <jake@FreeBSD.org>.

CAVEATS

Due to limitations within Open Firmware itself, these functions run at elevated priority and may adversely affect system performance.

The openprom interface exists entirely for compatibility with software like X11, and only the features that are actually needed for that are implemented. The interface sucks too much to actually use, new code should use the openfirm(4) interface instead.