2 .\" Copyright (c) 1992, 1993
3 .\" The Regents of the University of California. All rights reserved.
5 .\" This software was developed by the Computer Systems Engineering group
6 .\" at Lawrence Berkeley Laboratory under DARPA contract BG 91-66 and
7 .\" contributed to Berkeley.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. Neither the name of the University nor the names of its contributors
18 .\" may be used to endorse or promote products derived from this software
19 .\" without specific prior written permission.
21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .\" from: @(#)openprom.4 8.1 (Berkeley) 6/5/93
34 .\" from: OpenBSD: openprom.4,v 1.9 2004/03/22 22:07:21 miod Exp
37 .\" Copyright (c) 2005 Marius Strobl <marius@FreeBSD.org>
38 .\" All rights reserved.
40 .\" Redistribution and use in source and binary forms, with or without
41 .\" modification, are permitted provided that the following conditions
44 .\" 1. Redistributions of source code must retain the above copyright
45 .\" notice, this list of conditions and the following disclaimer.
46 .\" 2. Redistributions in binary form must reproduce the above copyright
47 .\" notice, this list of conditions and the following disclaimer in the
48 .\" documentation and/or other materials provided with the distribution.
50 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
51 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
52 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
53 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
54 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
55 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
56 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
57 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
58 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
59 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
64 .Dt OPENFIRM 4 sparc64
68 .Nd "Open Firmware interface"
72 .In dev/ofw/openfirmio.h
76 device is an interface to the
79 This interface is similar to the
84 interface and highly stylized.
87 calls for all operations.
88 These calls refer to the nodes in the
91 The nodes are represented by package handles,
92 which are simply integer values describing data areas.
93 Occasionally a package handle of 0 may be used or returned instead,
96 The calls that only take and/or return the package handle of a node
100 The others use a pointer to a
101 .Vt "struct ofiocdesc"
103 which has the following definition:
116 member is the package handle of the node that is passed in or returned.
117 Strings are passed in via the
122 The maximum accepted length of
128 member is used to return strings except for the
130 call where it is also used to pass in a string.
131 In the latter case the maximum accepted length of
137 works in a value-result fashion.
142 is expected to reflect the buffer size.
145 is updated to reflect the buffer contents.
150 .Bl -tag -width ".Dv OFIOCGETOPTNODE"
151 .It Dv OFIOCGETOPTNODE
154 Takes nothing and returns the package handle of the
160 Takes the package handle of a node and returns the package handle of the next
164 The node following the last node has a package handle of 0.
165 The node following the node with the package handle of 0 is the first node.
169 Takes the package handle of a node and returns the package handle of the first
171 This child may have siblings.
172 These can be determined by using
174 If the node does not have a child,
175 a package handle of 0 is returned.
178 .Vt "struct ofiocdesc" .
179 Takes the package handle of a node and the name of a property.
180 Returns the property value and its length.
181 If no such property is associated with that node,
182 the length of the value is set to \-1.
183 If the named property exists but has no value,
184 the length of the value is set to 0.
185 .It Dv OFIOCGETPROPLEN
187 .Vt "struct ofiocdesc" .
188 Takes the package handle of a node and the name of a property.
189 Returns the length of the property value.
190 This call is the same as
192 except that only the length of the property value is returned.
193 It can be used to determine whether a node has a particular property or whether
194 a property has a value without the need to provide memory for storing the value.
197 .Vt "struct ofiocdesc" .
198 Takes the package handle of a node,
199 the name of a property and a property value.
200 Returns the property value and the length that actually have been written.
203 may choose to truncate the value if it is too long or write a valid value
204 instead if the given value is invalid for the particular property.
205 Therefore the returned value should be checked.
208 may also completely refuse to write the given value to the property.
214 .Vt "struct ofiocdesc" .
215 Takes the package handle of a node and the name of a property.
216 Returns the name and the length of the next property of the node.
217 If the property referenced by the given name is the last property of the node,
220 .It Dv OFIOCFINDDEVICE
222 .Vt "struct ofiocdesc" .
223 Takes the name or alias name of a device node.
224 Returns package handle of the node.
225 If no matching node is found,
230 .Bl -tag -width ".Pa /dev/openfirm"
232 Open Firmware interface node
235 The following may result in rejection of an operation:
238 The requested operation requires permissions not specified at the call to
241 The given package handle is not 0 and does not correspond to any valid node,
242 or the given package handle is 0 where 0 is not allowed.
243 .It Bq Er ENAMETOOLONG
244 The given name or value exceeds the maximum allowed length of
250 The kernel could not allocate memory to copy in data from user-space or to
251 retrieve data from the
260 .%Q "IEEE Standards Organization"
261 .%B "IEEE Std 1275-1994:"
262 .%B "IEEE Standard for Boot Firmware (Initialization Configuration) Firmware:"
263 .%B Core Requirements and Practices"
264 .%O ISBN 1-55937-426-8
269 interface first appeared in
273 version to include it was
278 interface was ported to
281 .An "Thomas Moestl" Aq tmm@FreeBSD.org .
283 Due to limitations within
286 these functions run at elevated priority and may adversely affect system
291 node the property value passed in to the
293 call has to be null-terminated and the value length passed in has to include
299 the returned value length does not include the terminating