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.
68 .Nd "Open Firmware interface"
72 .In dev/ofw/openfirmio.h
76 device is an interface to the
79 This interface is highly stylized.
82 calls for all operations.
83 These calls refer to the nodes in the
86 The nodes are represented by package handles,
87 which are simply integer values describing data areas.
88 Occasionally a package handle of 0 may be used or returned instead,
91 The calls that only take and/or return the package handle of a node
95 The others use a pointer to a
96 .Vt "struct ofiocdesc"
98 which has the following definition:
111 member is the package handle of the node that is passed in or returned.
112 Strings are passed in via the
117 The maximum accepted length of
123 member is used to return strings except for the
125 call where it is also used to pass in a string.
126 In the latter case the maximum accepted length of
132 works in a value-result fashion.
137 is expected to reflect the buffer size.
140 is updated to reflect the buffer contents.
145 .Bl -tag -width ".Dv OFIOCGETOPTNODE"
146 .It Dv OFIOCGETOPTNODE
149 Takes nothing and returns the package handle of the
155 Takes the package handle of a node and returns the package handle of the next
159 The node following the last node has a package handle of 0.
160 The node following the node with the package handle of 0 is the first node.
164 Takes the package handle of a node and returns the package handle of the first
166 This child may have siblings.
167 These can be determined by using
169 If the node does not have a child,
170 a package handle of 0 is returned.
173 .Vt "struct ofiocdesc" .
174 Takes the package handle of a node and the name of a property.
175 Returns the property value and its length.
176 If no such property is associated with that node,
177 the length of the value is set to \-1.
178 If the named property exists but has no value,
179 the length of the value is set to 0.
180 .It Dv OFIOCGETPROPLEN
182 .Vt "struct ofiocdesc" .
183 Takes the package handle of a node and the name of a property.
184 Returns the length of the property value.
185 This call is the same as
187 except that only the length of the property value is returned.
188 It can be used to determine whether a node has a particular property or whether
189 a property has a value without the need to provide memory for storing the value.
192 .Vt "struct ofiocdesc" .
193 Takes the package handle of a node,
194 the name of a property and a property value.
195 Returns the property value and the length that actually have been written.
198 may choose to truncate the value if it is too long or write a valid value
199 instead if the given value is invalid for the particular property.
200 Therefore the returned value should be checked.
203 may also completely refuse to write the given value to the property.
209 .Vt "struct ofiocdesc" .
210 Takes the package handle of a node and the name of a property.
211 Returns the name and the length of the next property of the node.
212 If the property referenced by the given name is the last property of the node,
215 .It Dv OFIOCFINDDEVICE
217 .Vt "struct ofiocdesc" .
218 Takes the name or alias name of a device node.
219 Returns package handle of the node.
220 If no matching node is found,
225 .Bl -tag -width ".Pa /dev/openfirm"
227 Open Firmware interface node
230 The following may result in rejection of an operation:
233 The requested operation requires permissions not specified at the call to
236 The given package handle is not 0 and does not correspond to any valid node,
237 or the given package handle is 0 where 0 is not allowed.
238 .It Bq Er ENAMETOOLONG
239 The given name or value exceeds the maximum allowed length of
249 .%Q "IEEE Standards Organization"
250 .%B "IEEE Std 1275-1994:"
251 .%B "IEEE Standard for Boot Firmware (Initialization Configuration) Firmware:"
252 .%B Core Requirements and Practices"
253 .%O ISBN 1-55937-426-8
258 interface first appeared in
262 version to include it was
268 interface was ported to
271 .An Thomas Moestl Aq Mt tmm@FreeBSD.org .
272 This manual page was written by
273 .An Marius Strobl Aq Mt marius@FreeBSD.org
279 Due to limitations within
282 these functions run at elevated priority and may adversely affect system
287 node the property value passed in to the
289 call has to be null-terminated and the value length passed in has to include
295 the returned value length does not include the terminating