1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
<table class="head">
<tr>
<td class="head-ltitle">OPENFIRM(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">OPENFIRM(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">openfirm</code> — <span class="Nd">Open
Firmware interface</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/types.h</a>></code>
<br/>
<code class="In">#include <<a class="In">sys/ioctl.h</a>></code>
<br/>
<code class="In">#include
<<a class="In">dev/ofw/openfirmio.h</a>></code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <span class="Pa">/dev/openfirm</span> device is an interface
to the Open Firmware device tree. This interface is highly stylized. It uses
<a class="Xr">ioctl(2)</a> 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.</p>
<p class="Pp">The calls that only take and/or return the package handle of a
node use a pointer to a <var class="Vt">phandle_t</var> for this purpose.
The others use a pointer to a <var class="Vt">struct ofiocdesc</var>
descriptor, which has the following definition:</p>
<div class="Bd Pp Li">
<pre>struct ofiocdesc {
phandle_t of_nodeid;
int of_namelen;
const char *of_name;
int of_buflen;
char *of_buf;
};</pre>
</div>
<p class="Pp">The <var class="Va">of_nodeid</var> member is the package handle
of the node that is passed in or returned. Strings are passed in via the
<var class="Va">of_name</var> member of <var class="Va">of_namelen</var>
length. The maximum accepted length of <var class="Va">of_name</var> is
<code class="Dv">OFIOCMAXNAME</code>. The <var class="Va">of_buf</var>
member is used to return strings except for the
<code class="Dv">OFIOCSET</code> call where it is also used to pass in a
string. In the latter case the maximum accepted length of
<var class="Va">of_buf</var> is <code class="Dv">OFIOCMAXVALUE</code>.
Generally, <var class="Va">of_buf</var> works in a value-result fashion. At
entry to the <a class="Xr">ioctl(2)</a> call,
<var class="Va">of_buflen</var> is expected to reflect the buffer size. On
return, <var class="Va">of_buflen</var> is updated to reflect the buffer
contents.</p>
<p class="Pp">The following <a class="Xr">ioctl(2)</a> calls are supported:</p>
<dl class="Bl-tag">
<dt id="OFIOCGETOPTNODE"><a class="permalink" href="#OFIOCGETOPTNODE"><code class="Dv">OFIOCGETOPTNODE</code></a></dt>
<dd>Uses a <var class="Vt">phandle_t</var>. Takes nothing and returns the
package handle of the <span class="Pa">/options</span> node.</dd>
<dt id="OFIOCGETNEXT"><a class="permalink" href="#OFIOCGETNEXT"><code class="Dv">OFIOCGETNEXT</code></a></dt>
<dd>Uses a <var class="Vt">phandle_t</var>. 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.</dd>
<dt id="OFIOCGETCHILD"><a class="permalink" href="#OFIOCGETCHILD"><code class="Dv">OFIOCGETCHILD</code></a></dt>
<dd>Uses a <var class="Vt">phandle_t</var>. 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
<code class="Dv">OFIOCGETNEXT</code>. If the node does not have a child, a
package handle of 0 is returned.</dd>
<dt id="OFIOCGET"><a class="permalink" href="#OFIOCGET"><code class="Dv">OFIOCGET</code></a></dt>
<dd>Uses a <var class="Vt">struct ofiocdesc</var>. 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.</dd>
<dt id="OFIOCGETPROPLEN"><a class="permalink" href="#OFIOCGETPROPLEN"><code class="Dv">OFIOCGETPROPLEN</code></a></dt>
<dd>Uses a <var class="Vt">struct ofiocdesc</var>. 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 <code class="Dv">OFIOCGET</code> 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.</dd>
<dt id="OFIOCSET"><a class="permalink" href="#OFIOCSET"><code class="Dv">OFIOCSET</code></a></dt>
<dd>Uses a <var class="Vt">struct ofiocdesc</var>. 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
<code class="Er">EINVAL</code> is returned.</dd>
<dt id="OFIOCNEXTPROP"><a class="permalink" href="#OFIOCNEXTPROP"><code class="Dv">OFIOCNEXTPROP</code></a></dt>
<dd>Uses a <var class="Vt">struct ofiocdesc</var>. 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, <code class="Er">ENOENT</code> is
returned.</dd>
<dt id="OFIOCFINDDEVICE"><a class="permalink" href="#OFIOCFINDDEVICE"><code class="Dv">OFIOCFINDDEVICE</code></a></dt>
<dd>Uses a <var class="Vt">struct ofiocdesc</var>. Takes the name or alias
name of a device node. Returns package handle of the node. If no matching
node is found, <code class="Er">ENOENT</code> is returned.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<dl class="Bl-tag">
<dt><span class="Pa">/dev/openfirm</span></dt>
<dd>Open Firmware interface node</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1>
<p class="Pp">The following may result in rejection of an operation:</p>
<dl class="Bl-tag">
<dt>[<code class="Er">EBADF</code>]</dt>
<dd>The requested operation requires permissions not specified at the call to
<code class="Fn">open</code>().</dd>
<dt>[<code class="Er">EINVAL</code>]</dt>
<dd>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.</dd>
<dt>[<code class="Er">ENAMETOOLONG</code>]</dt>
<dd>The given name or value exceeds the maximum allowed length of
<code class="Dv">OFIOCMAXNAME</code> and
<code class="Dv">OFIOCMAXVALUE</code> bytes respectively.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">ioctl(2)</a>, <a class="Xr">ofwdump(8)</a></p>
<p class="Pp"><cite class="Rs"><i class="RsB">IEEE Std 1275-1994:</i>,
<i class="RsB">IEEE Standard for Boot Firmware (Initialization
Configuration) Firmware:</i>, <i class="RsB">Core Requirements and
Practices"</i>, <span class="RsQ">IEEE Standards Organization</span>,
<span class="RsO">ISBN 1-55937-426-8</span>.</cite></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">openfirm</code> interface first appeared in
<span class="Ux">NetBSD 1.6</span>. The first
<span class="Ux">FreeBSD</span> version to include it was
<span class="Ux">FreeBSD 5.0</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">The <code class="Nm">openfirm</code> interface was ported to
<span class="Ux">FreeBSD</span> by <span class="An">Thomas Moestl</span>
<<a class="Mt" href="mailto:tmm@FreeBSD.org">tmm@FreeBSD.org</a>>.
This manual page was written by <span class="An">Marius Strobl</span>
<<a class="Mt" href="mailto:marius@FreeBSD.org">marius@FreeBSD.org</a>>
based on the <span class="Ux">OpenBSD</span> manual page for
<a class="Xr">openprom(4)</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1>
<p class="Pp">Due to limitations within Open Firmware itself, these functions
run at elevated priority and may adversely affect system performance.</p>
<p class="Pp">For at least the <span class="Pa">/options</span> node the
property value passed in to the <code class="Dv">OFIOCSET</code> call has to
be null-terminated and the value length passed in has to include the
terminating ‘<code class="Li">\0</code>’. However, as with the
<code class="Dv">OFIOCGET</code> call, the returned value length does not
include the terminating ‘<code class="Li">\0</code>’.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">January 16, 2021</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
