share/man/man4/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 January 16, 2021
  64 .Dt OPENFIRM 4
  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 highly stylized.
  80 It uses
  81 .Xr ioctl 2
  82 calls for all operations.
  83 These calls refer to the nodes in the
  84 .Tn Open Firmware
  85 device tree.
  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,
  89 as described below.
  90 .Pp
  91 The calls that only take and/or return the package handle of a node
  92 use a pointer to a
  93 .Vt phandle_t
  94 for this purpose.
  95 The others use a pointer to a
  96 .Vt "struct ofiocdesc"
  97 descriptor,
  98 which has the following definition:
  99 .Bd -literal
 100 struct ofiocdesc {
 101         phandle_t       of_nodeid;
 102         int             of_namelen;
 103         const char      *of_name;
 104         int             of_buflen;
 105         char            *of_buf;
 106 };
 107 .Ed
 108 .Pp
 109 The
 110 .Va of_nodeid
 111 member is the package handle of the node that is passed in or returned.
 112 Strings are passed in via the
 113 .Va of_name
 114 member of
 115 .Va of_namelen
 116 length.
 117 The maximum accepted length of
 118 .Va of_name
 119 is
 120 .Dv OFIOCMAXNAME .
 121 The
 122 .Va of_buf
 123 member is used to return strings except for the
 124 .Dv OFIOCSET
 125 call where it is also used to pass in a string.
 126 In the latter case the maximum accepted length of
 127 .Va of_buf
 128 is
 129 .Dv OFIOCMAXVALUE .
 130 Generally,
 131 .Va of_buf
 132 works in a value-result fashion.
 133 At entry to the
 134 .Xr ioctl 2
 135 call,
 136 .Va of_buflen
 137 is expected to reflect the buffer size.
 138 On return,
 139 .Va of_buflen
 140 is updated to reflect the buffer contents.
 141 .Pp
 142 The following
 143 .Xr ioctl 2
 144 calls are supported:
 145 .Bl -tag -width ".Dv OFIOCGETOPTNODE"
 146 .It Dv OFIOCGETOPTNODE
 147 Uses a
 148 .Vt phandle_t .
 149 Takes nothing and returns the package handle of the
 150 .Pa /options
 151 node.
 152 .It Dv OFIOCGETNEXT
 153 Uses a
 154 .Vt phandle_t .
 155 Takes the package handle of a node and returns the package handle of the next
 156 node in the
 157 .Tn Open Firmware
 158 device tree.
 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.
 161 .It Dv OFIOCGETCHILD
 162 Uses a
 163 .Vt phandle_t .
 164 Takes the package handle of a node and returns the package handle of the first
 165 child of that node.
 166 This child may have siblings.
 167 These can be determined by using
 168 .Dv OFIOCGETNEXT .
 169 If the node does not have a child,
 170 a package handle of 0 is returned.
 171 .It Dv OFIOCGET
 172 Uses a
 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
 181 Uses a
 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
 186 .Dv OFIOCGET
 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.
 190 .It Dv OFIOCSET
 191 Uses a
 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.
 196 The
 197 .Tn Open Firmware
 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.
 201 The
 202 .Tn Open Firmware
 203 may also completely refuse to write the given value to the property.
 204 In this case
 205 .Er EINVAL
 206 is returned.
 207 .It Dv OFIOCNEXTPROP
 208 Uses a
 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,
 213 .Er ENOENT
 214 is returned.
 215 .It Dv OFIOCFINDDEVICE
 216 Uses a
 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,
 221 .Er ENOENT
 222 is returned.
 223 .El
 224 .Sh FILES
 225 .Bl -tag -width ".Pa /dev/openfirm"
 226 .It Pa /dev/openfirm
 227 Open Firmware interface node
 228 .El
 229 .Sh DIAGNOSTICS
 230 The following may result in rejection of an operation:
 231 .Bl -tag -width Er
 232 .It Bq Er EBADF
 233 The requested operation requires permissions not specified at the call to
 234 .Fn open .
 235 .It Bq Er EINVAL
 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
 240 .Dv OFIOCMAXNAME
 241 and
 242 .Dv OFIOCMAXVALUE
 243 bytes respectively.
 244 .El
 245 .Sh SEE ALSO
 246 .Xr ioctl 2 ,
 247 .Xr ofwdump 8
 248 .Rs
 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
 254 .Re
 255 .Sh HISTORY
 256 The
 257 .Nm
 258 interface first appeared in
 259 .Nx 1.6 .
 260 The first
 261 .Fx
 262 version to include it was
 263 .Fx 5.0 .
 264 .Sh AUTHORS
 265 .An -nosplit
 266 The
 267 .Nm
 268 interface was ported to
 269 .Fx
 270 by
 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
 274 based on the
 275 .Ox
 276 manual page for
 277 .Xr openprom 4 .
 278 .Sh CAVEATS
 279 Due to limitations within
 280 .Tn Open Firmware
 281 itself,
 282 these functions run at elevated priority and may adversely affect system
 283 performance.
 284 .Pp
 285 For at least the
 286 .Pa /options
 287 node the property value passed in to the
 288 .Dv OFIOCSET
 289 call has to be null-terminated and the value length passed in has to include
 290 the terminating
 291 .Ql \e0 .
 292 However, as with the
 293 .Dv OFIOCGET
 294 call,
 295 the returned value length does not include the terminating
 296 .Ql \e0 .