1.\"-
2.\" Copyright (c) 1992, 1993
3.\" The Regents of the University of California. All rights reserved.
4.\"
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.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
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.
20.\"
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
31.\" SUCH DAMAGE.
32.\"
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
35.\"
36.\"-
37.\" Copyright (c) 2005 Marius Strobl <marius@FreeBSD.org>
38.\" All rights reserved.
39.\"
40.\" Redistribution and use in source and binary forms, with or without
41.\" modification, are permitted provided that the following conditions
42.\" are met:
43.\"
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.
49.\"
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.
60.\"
| 1.\"-
2.\" Copyright (c) 1992, 1993
3.\" The Regents of the University of California. All rights reserved.
4.\"
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.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
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.
20.\"
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
31.\" SUCH DAMAGE.
32.\"
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
35.\"
36.\"-
37.\" Copyright (c) 2005 Marius Strobl <marius@FreeBSD.org>
38.\" All rights reserved.
39.\"
40.\" Redistribution and use in source and binary forms, with or without
41.\" modification, are permitted provided that the following conditions
42.\" are met:
43.\"
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.
49.\"
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.
60.\"
|
62.\"
63.Dd September 1, 2006
64.Dt OPENFIRM 4 sparc64
65.Os
66.Sh NAME
67.Nm openfirm
68.Nd "Open Firmware interface"
69.Sh SYNOPSIS
70.In sys/types.h
71.In sys/ioctl.h
72.In dev/ofw/openfirmio.h
73.Sh DESCRIPTION
74The
75.Pa /dev/openfirm
76device is an interface to the
77.Tn Open Firmware
78device tree.
79This interface is similar to the
80.Tn SunOS /
81.Tn Solaris
82compatible
83.Xr openprom 4
84interface and highly stylized.
85It uses
86.Xr ioctl 2
87calls for all operations.
88These calls refer to the nodes in the
89.Tn Open Firmware
90device tree.
91The nodes are represented by package handles,
92which are simply integer values describing data areas.
93Occasionally a package handle of 0 may be used or returned instead,
94as described below.
95.Pp
96The calls that only take and/or return the package handle of a node
97use a pointer to a
98.Vt phandle_t
99for this purpose.
100The others use a pointer to a
101.Vt "struct ofiocdesc"
102descriptor,
103which has the following definition:
104.Bd -literal
105struct ofiocdesc {
106 phandle_t of_nodeid;
107 int of_namelen;
108 const char *of_name;
109 int of_buflen;
110 char *of_buf;
111};
112.Ed
113.Pp
114The
115.Va of_nodeid
116member is the package handle of the node that is passed in or returned.
117Strings are passed in via the
118.Va of_name
119member of
120.Va of_namelen
121length.
122The maximum accepted length of
123.Va of_name
124is
125.Dv OFIOCMAXNAME .
126The
127.Va of_buf
128member is used to return strings except for the
129.Dv OFIOCSET
130call where it is also used to pass in a string.
131In the latter case the maximum accepted length of
132.Va of_buf
133is
134.Dv OFIOCMAXVALUE .
135Generally,
136.Va of_buf
137works in a value-result fashion.
138At entry to the
139.Xr ioctl 2
140call,
141.Va of_buflen
142is expected to reflect the buffer size.
143On return,
144.Va of_buflen
145is updated to reflect the buffer contents.
146.Pp
147The following
148.Xr ioctl 2
149calls are supported:
150.Bl -tag -width ".Dv OFIOCGETOPTNODE"
151.It Dv OFIOCGETOPTNODE
152Uses a
153.Vt phandle_t .
154Takes nothing and returns the package handle of the
155.Pa /options
156node.
157.It Dv OFIOCGETNEXT
158Uses a
159.Vt phandle_t .
160Takes the package handle of a node and returns the package handle of the next
161node in the
162.Tn Open Firmware
163device tree.
164The node following the last node has a package handle of 0.
165The node following the node with the package handle of 0 is the first node.
166.It Dv OFIOCGETCHILD
167Uses a
168.Vt phandle_t .
169Takes the package handle of a node and returns the package handle of the first
170child of that node.
171This child may have siblings.
172These can be determined by using
173.Dv OFIOCGETNEXT .
174If the node does not have a child,
175a package handle of 0 is returned.
176.It Dv OFIOCGET
177Uses a
178.Vt "struct ofiocdesc" .
179Takes the package handle of a node and the name of a property.
180Returns the property value and its length.
181If no such property is associated with that node,
182the length of the value is set to \-1.
183If the named property exists but has no value,
184the length of the value is set to 0.
185.It Dv OFIOCGETPROPLEN
186Uses a
187.Vt "struct ofiocdesc" .
188Takes the package handle of a node and the name of a property.
189Returns the length of the property value.
190This call is the same as
191.Dv OFIOCGET
192except that only the length of the property value is returned.
193It can be used to determine whether a node has a particular property or whether
194a property has a value without the need to provide memory for storing the value.
195.It Dv OFIOCSET
196Uses a
197.Vt "struct ofiocdesc" .
198Takes the package handle of a node,
199the name of a property and a property value.
200Returns the property value and the length that actually have been written.
201The
202.Tn Open Firmware
203may choose to truncate the value if it is too long or write a valid value
204instead if the given value is invalid for the particular property.
205Therefore the returned value should be checked.
206The
207.Tn Open Firmware
208may also completely refuse to write the given value to the property.
209In this case
210.Er EINVAL
211is returned.
212.It Dv OFIOCNEXTPROP
213Uses a
214.Vt "struct ofiocdesc" .
215Takes the package handle of a node and the name of a property.
216Returns the name and the length of the next property of the node.
217If the property referenced by the given name is the last property of the node,
218.Er ENOENT
219is returned.
220.It Dv OFIOCFINDDEVICE
221Uses a
222.Vt "struct ofiocdesc" .
223Takes the name or alias name of a device node.
224Returns package handle of the node.
225If no matching node is found,
226.Er ENOENT
227is returned.
228.El
229.Sh FILES
230.Bl -tag -width ".Pa /dev/openfirm"
231.It Pa /dev/openfirm
232Open Firmware interface node
233.El
234.Sh ERRORS
235The following may result in rejection of an operation:
236.Bl -tag -width Er
237.It Bq Er EBADF
238The requested operation requires permissions not specified at the call to
239.Fn open .
240.It Bq Er EINVAL
241The given package handle is not 0 and does not correspond to any valid node,
242or the given package handle is 0 where 0 is not allowed.
243.It Bq Er ENAMETOOLONG
244The given name or value exceeds the maximum allowed length of
245.Dv OFIOCMAXNAME
246and
247.Dv OFIOCMAXVALUE
248bytes respectively.
249.It Bq Er ENOMEM
250The kernel could not allocate memory to copy in data from user-space or to
251retrieve data from the
252.Tn Open Firmware .
253.El
| 62.\"
63.Dd September 1, 2006
64.Dt OPENFIRM 4 sparc64
65.Os
66.Sh NAME
67.Nm openfirm
68.Nd "Open Firmware interface"
69.Sh SYNOPSIS
70.In sys/types.h
71.In sys/ioctl.h
72.In dev/ofw/openfirmio.h
73.Sh DESCRIPTION
74The
75.Pa /dev/openfirm
76device is an interface to the
77.Tn Open Firmware
78device tree.
79This interface is similar to the
80.Tn SunOS /
81.Tn Solaris
82compatible
83.Xr openprom 4
84interface and highly stylized.
85It uses
86.Xr ioctl 2
87calls for all operations.
88These calls refer to the nodes in the
89.Tn Open Firmware
90device tree.
91The nodes are represented by package handles,
92which are simply integer values describing data areas.
93Occasionally a package handle of 0 may be used or returned instead,
94as described below.
95.Pp
96The calls that only take and/or return the package handle of a node
97use a pointer to a
98.Vt phandle_t
99for this purpose.
100The others use a pointer to a
101.Vt "struct ofiocdesc"
102descriptor,
103which has the following definition:
104.Bd -literal
105struct ofiocdesc {
106 phandle_t of_nodeid;
107 int of_namelen;
108 const char *of_name;
109 int of_buflen;
110 char *of_buf;
111};
112.Ed
113.Pp
114The
115.Va of_nodeid
116member is the package handle of the node that is passed in or returned.
117Strings are passed in via the
118.Va of_name
119member of
120.Va of_namelen
121length.
122The maximum accepted length of
123.Va of_name
124is
125.Dv OFIOCMAXNAME .
126The
127.Va of_buf
128member is used to return strings except for the
129.Dv OFIOCSET
130call where it is also used to pass in a string.
131In the latter case the maximum accepted length of
132.Va of_buf
133is
134.Dv OFIOCMAXVALUE .
135Generally,
136.Va of_buf
137works in a value-result fashion.
138At entry to the
139.Xr ioctl 2
140call,
141.Va of_buflen
142is expected to reflect the buffer size.
143On return,
144.Va of_buflen
145is updated to reflect the buffer contents.
146.Pp
147The following
148.Xr ioctl 2
149calls are supported:
150.Bl -tag -width ".Dv OFIOCGETOPTNODE"
151.It Dv OFIOCGETOPTNODE
152Uses a
153.Vt phandle_t .
154Takes nothing and returns the package handle of the
155.Pa /options
156node.
157.It Dv OFIOCGETNEXT
158Uses a
159.Vt phandle_t .
160Takes the package handle of a node and returns the package handle of the next
161node in the
162.Tn Open Firmware
163device tree.
164The node following the last node has a package handle of 0.
165The node following the node with the package handle of 0 is the first node.
166.It Dv OFIOCGETCHILD
167Uses a
168.Vt phandle_t .
169Takes the package handle of a node and returns the package handle of the first
170child of that node.
171This child may have siblings.
172These can be determined by using
173.Dv OFIOCGETNEXT .
174If the node does not have a child,
175a package handle of 0 is returned.
176.It Dv OFIOCGET
177Uses a
178.Vt "struct ofiocdesc" .
179Takes the package handle of a node and the name of a property.
180Returns the property value and its length.
181If no such property is associated with that node,
182the length of the value is set to \-1.
183If the named property exists but has no value,
184the length of the value is set to 0.
185.It Dv OFIOCGETPROPLEN
186Uses a
187.Vt "struct ofiocdesc" .
188Takes the package handle of a node and the name of a property.
189Returns the length of the property value.
190This call is the same as
191.Dv OFIOCGET
192except that only the length of the property value is returned.
193It can be used to determine whether a node has a particular property or whether
194a property has a value without the need to provide memory for storing the value.
195.It Dv OFIOCSET
196Uses a
197.Vt "struct ofiocdesc" .
198Takes the package handle of a node,
199the name of a property and a property value.
200Returns the property value and the length that actually have been written.
201The
202.Tn Open Firmware
203may choose to truncate the value if it is too long or write a valid value
204instead if the given value is invalid for the particular property.
205Therefore the returned value should be checked.
206The
207.Tn Open Firmware
208may also completely refuse to write the given value to the property.
209In this case
210.Er EINVAL
211is returned.
212.It Dv OFIOCNEXTPROP
213Uses a
214.Vt "struct ofiocdesc" .
215Takes the package handle of a node and the name of a property.
216Returns the name and the length of the next property of the node.
217If the property referenced by the given name is the last property of the node,
218.Er ENOENT
219is returned.
220.It Dv OFIOCFINDDEVICE
221Uses a
222.Vt "struct ofiocdesc" .
223Takes the name or alias name of a device node.
224Returns package handle of the node.
225If no matching node is found,
226.Er ENOENT
227is returned.
228.El
229.Sh FILES
230.Bl -tag -width ".Pa /dev/openfirm"
231.It Pa /dev/openfirm
232Open Firmware interface node
233.El
234.Sh ERRORS
235The following may result in rejection of an operation:
236.Bl -tag -width Er
237.It Bq Er EBADF
238The requested operation requires permissions not specified at the call to
239.Fn open .
240.It Bq Er EINVAL
241The given package handle is not 0 and does not correspond to any valid node,
242or the given package handle is 0 where 0 is not allowed.
243.It Bq Er ENAMETOOLONG
244The given name or value exceeds the maximum allowed length of
245.Dv OFIOCMAXNAME
246and
247.Dv OFIOCMAXVALUE
248bytes respectively.
249.It Bq Er ENOMEM
250The kernel could not allocate memory to copy in data from user-space or to
251retrieve data from the
252.Tn Open Firmware .
253.El
|