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.\"
|
61.\" $FreeBSD: head/share/man/man4/man4.sparc64/openfirm.4 161833 2006-09-01 20:01:51Z marius $
|
61.\" $FreeBSD: head/share/man/man4/man4.sparc64/openfirm.4 208027 2010-05-13 12:07:55Z uqs $ |
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
|
254.Sh CAVEATS
255Due to limitations within
256.Tn Open Firmware
257itself,
258these functions run at elevated priority and may adversely affect system
259performance.
260.Pp
261For at least the
262.Pa /options
263node the property value passed in to the
264.Dv OFIOCSET
265call has to be null-terminated and the value length passed in has to include
266the terminating
267.Ql \e0 .
268However, as with the
269.Dv OFIOCGET
270call,
271the returned value length does not include the terminating
272.Ql \e0 .
|
254.Sh SEE ALSO 255.Xr ioctl 2 , 256.Xr openprom 4 , 257.Xr eeprom 8 , 258.Xr ofwdump 8 259.Rs 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 265.Re 266.Sh HISTORY 267The 268.Nm 269interface first appeared in 270.Nx 1.6 . 271The first 272.Fx 273version to include it was 274.Fx 5.0 . 275.Sh AUTHORS 276The 277.Nm 278interface was ported to 279.Fx 280by 281.An "Thomas Moestl" Aq tmm@FreeBSD.org .
|
282.Sh CAVEATS 283Due to limitations within 284.Tn Open Firmware 285itself, 286these functions run at elevated priority and may adversely affect system 287performance. 288.Pp 289For at least the 290.Pa /options 291node the property value passed in to the 292.Dv OFIOCSET 293call has to be null-terminated and the value length passed in has to include 294the terminating 295.Ql \e0 . 296However, as with the 297.Dv OFIOCGET 298call, 299the returned value length does not include the terminating 300.Ql \e0 . |
|