OPENFIRM(4) FreeBSD Kernel Interfaces Manual OPENFIRM(4)
NAME
openfirm - Open Firmware interface
SYNOPSIS
#include <sys/types.h>
#include <sys/ioctl.h>
#include <dev/ofw/openfirmio.h>
DESCRIPTION
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.
FILES
/dev/openfirm Open Firmware interface node
DIAGNOSTICS
The following may result in rejection of an operation:
[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.
SEE ALSO
ioctl(2), ofwdump(8)
IEEE Std 1275-1994:, IEEE Standard for Boot Firmware (Initialization
Configuration) Firmware:, Core Requirements and Practices", IEEE
Standards Organization, ISBN 1-55937-426-8.
HISTORY
The openfirm interface first appeared in NetBSD 1.6. The first FreeBSD
version to include it was FreeBSD 5.0.
AUTHORS
The openfirm interface was ported to FreeBSD by Thomas Moestl
<tmm@FreeBSD.org>. This manual page was written by Marius Strobl
<marius@FreeBSD.org> based on the OpenBSD manual page for openprom(4).
CAVEATS
Due to limitations within Open Firmware itself, these functions run at
elevated priority and may adversely affect system performance.
For at least the /options node the property value passed in to the
OFIOCSET call has to be null-terminated and the value length passed in
has to include the terminating `\0'. However, as with the OFIOCGET call,
the returned value length does not include the terminating `\0'.
FreeBSD 13.1-RELEASE-p6 January 16, 2021 FreeBSD 13.1-RELEASE-p6
man2web Home...