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.\" from: OpenBSD: openprom.4,v 1.9 2004/03/22 22:07:21 miod Exp 33.\" 34.\"- 35.\" Copyright (c) 2005 Marius Strobl <marius@FreeBSD.org> 36.\" All rights reserved. 37.\" 38.\" Redistribution and use in source and binary forms, with or without 39.\" modification, are permitted provided that the following conditions 40.\" are met: 41.\" 42.\" 1. Redistributions of source code must retain the above copyright 43.\" notice, this list of conditions and the following disclaimer. 44.\" 2. Redistributions in binary form must reproduce the above copyright 45.\" notice, this list of conditions and the following disclaimer in the 46.\" documentation and/or other materials provided with the distribution. 47.\" 48.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 49.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 50.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 51.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 52.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 53.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 54.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 55.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 56.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 57.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 58.\" 59.Dd January 16, 2021 60.Dt OPENFIRM 4 61.Os 62.Sh NAME 63.Nm openfirm 64.Nd "Open Firmware interface" 65.Sh SYNOPSIS 66.In sys/types.h 67.In sys/ioctl.h 68.In dev/ofw/openfirmio.h 69.Sh DESCRIPTION 70The 71.Pa /dev/openfirm 72device is an interface to the 73.Tn Open Firmware 74device tree. 75This interface is highly stylized. 76It uses 77.Xr ioctl 2 78calls for all operations. 79These calls refer to the nodes in the 80.Tn Open Firmware 81device tree. 82The nodes are represented by package handles, 83which are simply integer values describing data areas. 84Occasionally a package handle of 0 may be used or returned instead, 85as described below. 86.Pp 87The calls that only take and/or return the package handle of a node 88use a pointer to a 89.Vt phandle_t 90for this purpose. 91The others use a pointer to a 92.Vt "struct ofiocdesc" 93descriptor, 94which has the following definition: 95.Bd -literal 96struct ofiocdesc { 97 phandle_t of_nodeid; 98 int of_namelen; 99 const char *of_name; 100 int of_buflen; 101 char *of_buf; 102}; 103.Ed 104.Pp 105The 106.Va of_nodeid 107member is the package handle of the node that is passed in or returned. 108Strings are passed in via the 109.Va of_name 110member of 111.Va of_namelen 112length. 113The maximum accepted length of 114.Va of_name 115is 116.Dv OFIOCMAXNAME . 117The 118.Va of_buf 119member is used to return strings except for the 120.Dv OFIOCSET 121call where it is also used to pass in a string. 122In the latter case the maximum accepted length of 123.Va of_buf 124is 125.Dv OFIOCMAXVALUE . 126Generally, 127.Va of_buf 128works in a value-result fashion. 129At entry to the 130.Xr ioctl 2 131call, 132.Va of_buflen 133is expected to reflect the buffer size. 134On return, 135.Va of_buflen 136is updated to reflect the buffer contents. 137.Pp 138The following 139.Xr ioctl 2 140calls are supported: 141.Bl -tag -width ".Dv OFIOCGETOPTNODE" 142.It Dv OFIOCGETOPTNODE 143Uses a 144.Vt phandle_t . 145Takes nothing and returns the package handle of the 146.Pa /options 147node. 148.It Dv OFIOCGETNEXT 149Uses a 150.Vt phandle_t . 151Takes the package handle of a node and returns the package handle of the next 152node in the 153.Tn Open Firmware 154device tree. 155The node following the last node has a package handle of 0. 156The node following the node with the package handle of 0 is the first node. 157.It Dv OFIOCGETCHILD 158Uses a 159.Vt phandle_t . 160Takes the package handle of a node and returns the package handle of the first 161child of that node. 162This child may have siblings. 163These can be determined by using 164.Dv OFIOCGETNEXT . 165If the node does not have a child, 166a package handle of 0 is returned. 167.It Dv OFIOCGET 168Uses a 169.Vt "struct ofiocdesc" . 170Takes the package handle of a node and the name of a property. 171Returns the property value and its length. 172If no such property is associated with that node, 173the length of the value is set to \-1. 174If the named property exists but has no value, 175the length of the value is set to 0. 176.It Dv OFIOCGETPROPLEN 177Uses a 178.Vt "struct ofiocdesc" . 179Takes the package handle of a node and the name of a property. 180Returns the length of the property value. 181This call is the same as 182.Dv OFIOCGET 183except that only the length of the property value is returned. 184It can be used to determine whether a node has a particular property or whether 185a property has a value without the need to provide memory for storing the value. 186.It Dv OFIOCSET 187Uses a 188.Vt "struct ofiocdesc" . 189Takes the package handle of a node, 190the name of a property and a property value. 191Returns the property value and the length that actually have been written. 192The 193.Tn Open Firmware 194may choose to truncate the value if it is too long or write a valid value 195instead if the given value is invalid for the particular property. 196Therefore the returned value should be checked. 197The 198.Tn Open Firmware 199may also completely refuse to write the given value to the property. 200In this case 201.Er EINVAL 202is returned. 203.It Dv OFIOCNEXTPROP 204Uses a 205.Vt "struct ofiocdesc" . 206Takes the package handle of a node and the name of a property. 207Returns the name and the length of the next property of the node. 208If the property referenced by the given name is the last property of the node, 209.Er ENOENT 210is returned. 211.It Dv OFIOCFINDDEVICE 212Uses a 213.Vt "struct ofiocdesc" . 214Takes the name or alias name of a device node. 215Returns package handle of the node. 216If no matching node is found, 217.Er ENOENT 218is returned. 219.El 220.Sh FILES 221.Bl -tag -width ".Pa /dev/openfirm" 222.It Pa /dev/openfirm 223Open Firmware interface node 224.El 225.Sh DIAGNOSTICS 226The following may result in rejection of an operation: 227.Bl -tag -width Er 228.It Bq Er EBADF 229The requested operation requires permissions not specified at the call to 230.Fn open . 231.It Bq Er EINVAL 232The given package handle is not 0 and does not correspond to any valid node, 233or the given package handle is 0 where 0 is not allowed. 234.It Bq Er ENAMETOOLONG 235The given name or value exceeds the maximum allowed length of 236.Dv OFIOCMAXNAME 237and 238.Dv OFIOCMAXVALUE 239bytes respectively. 240.El 241.Sh SEE ALSO 242.Xr ioctl 2 , 243.Xr ofwdump 8 244.Rs 245.%Q "IEEE Standards Organization" 246.%B "IEEE Std 1275-1994:" 247.%B "IEEE Standard for Boot Firmware (Initialization Configuration) Firmware:" 248.%B Core Requirements and Practices" 249.%O ISBN 1-55937-426-8 250.Re 251.Sh HISTORY 252The 253.Nm 254interface first appeared in 255.Nx 1.6 . 256The first 257.Fx 258version to include it was 259.Fx 5.0 . 260.Sh AUTHORS 261.An -nosplit 262The 263.Nm 264interface was ported to 265.Fx 266by 267.An Thomas Moestl Aq Mt tmm@FreeBSD.org . 268This manual page was written by 269.An Marius Strobl Aq Mt marius@FreeBSD.org 270based on the 271.Ox 272manual page for 273.Xr openprom 4 . 274.Sh CAVEATS 275Due to limitations within 276.Tn Open Firmware 277itself, 278these functions run at elevated priority and may adversely affect system 279performance. 280.Pp 281For at least the 282.Pa /options 283node the property value passed in to the 284.Dv OFIOCSET 285call has to be null-terminated and the value length passed in has to include 286the terminating 287.Ql \e0 . 288However, as with the 289.Dv OFIOCGET 290call, 291the returned value length does not include the terminating 292.Ql \e0 . 293