share/man/man4/man4.sparc64/openfirm.4

   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$
  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
  74 The
  75 .Pa /dev/openfirm
  76 device is an interface to the
  77 .Tn Open Firmware
  78 device tree.
  79 This interface is similar to the
  80 .Tn SunOS /
  81 .Tn Solaris
  82 compatible
  83 .Xr openprom 4
  84 interface and highly stylized.
  85 It uses
  86 .Xr ioctl 2
  87 calls for all operations.
  88 These calls refer to the nodes in the
  89 .Tn Open Firmware
  90 device tree.
  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,
  94 as described below.
  95 .Pp
  96 The calls that only take and/or return the package handle of a node
  97 use a pointer to a
  98 .Vt phandle_t
  99 for this purpose.
 100 The others use a pointer to a
 101 .Vt "struct ofiocdesc"
 102 descriptor,
 103 which has the following definition:
 104 .Bd -literal
 105 struct 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
 114 The
 115 .Va of_nodeid
 116 member is the package handle of the node that is passed in or returned.
 117 Strings are passed in via the
 118 .Va of_name
 119 member of
 120 .Va of_namelen
 121 length.
 122 The maximum accepted length of
 123 .Va of_name
 124 is
 125 .Dv OFIOCMAXNAME .
 126 The
 127 .Va of_buf
 128 member is used to return strings except for the
 129 .Dv OFIOCSET
 130 call where it is also used to pass in a string.
 131 In the latter case the maximum accepted length of
 132 .Va of_buf
 133 is
 134 .Dv OFIOCMAXVALUE .
 135 Generally,
 136 .Va of_buf
 137 works in a value-result fashion.
 138 At entry to the
 139 .Xr ioctl 2
 140 call,
 141 .Va of_buflen
 142 is expected to reflect the buffer size.
 143 On return,
 144 .Va of_buflen
 145 is updated to reflect the buffer contents.
 146 .Pp
 147 The following
 148 .Xr ioctl 2
 149 calls are supported:
 150 .Bl -tag -width ".Dv OFIOCGETOPTNODE"
 151 .It Dv OFIOCGETOPTNODE
 152 Uses a
 153 .Vt phandle_t .
 154 Takes nothing and returns the package handle of the
 155 .Pa /options
 156 node.
 157 .It Dv OFIOCGETNEXT
 158 Uses a
 159 .Vt phandle_t .
 160 Takes the package handle of a node and returns the package handle of the next
 161 node in the
 162 .Tn Open Firmware
 163 device tree.
 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.
 166 .It Dv OFIOCGETCHILD
 167 Uses a
 168 .Vt phandle_t .
 169 Takes the package handle of a node and returns the package handle of the first
 170 child of that node.
 171 This child may have siblings.
 172 These can be determined by using
 173 .Dv OFIOCGETNEXT .
 174 If the node does not have a child,
 175 a package handle of 0 is returned.
 176 .It Dv OFIOCGET
 177 Uses a
 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
 186 Uses a
 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
 191 .Dv OFIOCGET
 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.
 195 .It Dv OFIOCSET
 196 Uses a
 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.
 201 The
 202 .Tn Open Firmware
 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.
 206 The
 207 .Tn Open Firmware
 208 may also completely refuse to write the given value to the property.
 209 In this case
 210 .Er EINVAL
 211 is returned.
 212 .It Dv OFIOCNEXTPROP
 213 Uses a
 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,
 218 .Er ENOENT
 219 is returned.
 220 .It Dv OFIOCFINDDEVICE
 221 Uses a
 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,
 226 .Er ENOENT
 227 is returned.
 228 .El
 229 .Sh FILES
 230 .Bl -tag -width ".Pa /dev/openfirm"
 231 .It Pa /dev/openfirm
 232 Open Firmware interface node
 233 .El
 234 .Sh DIAGNOSTICS
 235 The following may result in rejection of an operation:
 236 .Bl -tag -width Er
 237 .It Bq Er EBADF
 238 The requested operation requires permissions not specified at the call to
 239 .Fn open .
 240 .It Bq Er EINVAL
 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
 245 .Dv OFIOCMAXNAME
 246 and
 247 .Dv OFIOCMAXVALUE
 248 bytes respectively.
 249 .It Bq Er ENOMEM
 250 The kernel could not allocate memory to copy in data from user-space or to
 251 retrieve data from the
 252 .Tn Open Firmware .
 253 .El
 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
 267 The
 268 .Nm
 269 interface first appeared in
 270 .Nx 1.6 .
 271 The first
 272 .Fx
 273 version to include it was
 274 .Fx 5.0 .
 275 .Sh AUTHORS
 276 The
 277 .Nm
 278 interface was ported to
 279 .Fx
 280 by
 281 .An "Thomas Moestl" Aq tmm@FreeBSD.org .
 282 .Sh CAVEATS
 283 Due to limitations within
 284 .Tn Open Firmware
 285 itself,
 286 these functions run at elevated priority and may adversely affect system
 287 performance.
 288 .Pp
 289 For at least the
 290 .Pa /options
 291 node the property value passed in to the
 292 .Dv OFIOCSET
 293 call has to be null-terminated and the value length passed in has to include
 294 the terminating
 295 .Ql \e0 .
 296 However, as with the
 297 .Dv OFIOCGET
 298 call,
 299 the returned value length does not include the terminating
 300 .Ql \e0 .