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.Dd January 16, 2021 62.Dt OPENFIRM 4 63.Os 64.Sh NAME 65.Nm openfirm 66.Nd "Open Firmware interface" 67.Sh SYNOPSIS 68.In sys/types.h 69.In sys/ioctl.h 70.In dev/ofw/openfirmio.h 71.Sh DESCRIPTION 72The 73.Pa /dev/openfirm 74device is an interface to the 75.Tn Open Firmware 76device tree. 77This interface is highly stylized. 78It uses 79.Xr ioctl 2 80calls for all operations. 81These calls refer to the nodes in the 82.Tn Open Firmware 83device tree. 84The nodes are represented by package handles, 85which are simply integer values describing data areas. 86Occasionally a package handle of 0 may be used or returned instead, 87as described below. 88.Pp 89The calls that only take and/or return the package handle of a node 90use a pointer to a 91.Vt phandle_t 92for this purpose. 93The others use a pointer to a 94.Vt "struct ofiocdesc" 95descriptor, 96which has the following definition: 97.Bd -literal 98struct ofiocdesc { 99 phandle_t of_nodeid; 100 int of_namelen; 101 const char *of_name; 102 int of_buflen; 103 char *of_buf; 104}; 105.Ed 106.Pp 107The 108.Va of_nodeid 109member is the package handle of the node that is passed in or returned. 110Strings are passed in via the 111.Va of_name 112member of 113.Va of_namelen 114length. 115The maximum accepted length of 116.Va of_name 117is 118.Dv OFIOCMAXNAME . 119The 120.Va of_buf 121member is used to return strings except for the 122.Dv OFIOCSET 123call where it is also used to pass in a string. 124In the latter case the maximum accepted length of 125.Va of_buf 126is 127.Dv OFIOCMAXVALUE . 128Generally, 129.Va of_buf 130works in a value-result fashion. 131At entry to the 132.Xr ioctl 2 133call, 134.Va of_buflen 135is expected to reflect the buffer size. 136On return, 137.Va of_buflen 138is updated to reflect the buffer contents. 139.Pp 140The following 141.Xr ioctl 2 142calls are supported: 143.Bl -tag -width ".Dv OFIOCGETOPTNODE" 144.It Dv OFIOCGETOPTNODE 145Uses a 146.Vt phandle_t . 147Takes nothing and returns the package handle of the 148.Pa /options 149node. 150.It Dv OFIOCGETNEXT 151Uses a 152.Vt phandle_t . 153Takes the package handle of a node and returns the package handle of the next 154node in the 155.Tn Open Firmware 156device tree. 157The node following the last node has a package handle of 0. 158The node following the node with the package handle of 0 is the first node. 159.It Dv OFIOCGETCHILD 160Uses a 161.Vt phandle_t . 162Takes the package handle of a node and returns the package handle of the first 163child of that node. 164This child may have siblings. 165These can be determined by using 166.Dv OFIOCGETNEXT . 167If the node does not have a child, 168a package handle of 0 is returned. 169.It Dv OFIOCGET 170Uses a 171.Vt "struct ofiocdesc" . 172Takes the package handle of a node and the name of a property. 173Returns the property value and its length. 174If no such property is associated with that node, 175the length of the value is set to \-1. 176If the named property exists but has no value, 177the length of the value is set to 0. 178.It Dv OFIOCGETPROPLEN 179Uses a 180.Vt "struct ofiocdesc" . 181Takes the package handle of a node and the name of a property. 182Returns the length of the property value. 183This call is the same as 184.Dv OFIOCGET 185except that only the length of the property value is returned. 186It can be used to determine whether a node has a particular property or whether 187a property has a value without the need to provide memory for storing the value. 188.It Dv OFIOCSET 189Uses a 190.Vt "struct ofiocdesc" . 191Takes the package handle of a node, 192the name of a property and a property value. 193Returns the property value and the length that actually have been written. 194The 195.Tn Open Firmware 196may choose to truncate the value if it is too long or write a valid value 197instead if the given value is invalid for the particular property. 198Therefore the returned value should be checked. 199The 200.Tn Open Firmware 201may also completely refuse to write the given value to the property. 202In this case 203.Er EINVAL 204is returned. 205.It Dv OFIOCNEXTPROP 206Uses a 207.Vt "struct ofiocdesc" . 208Takes the package handle of a node and the name of a property. 209Returns the name and the length of the next property of the node. 210If the property referenced by the given name is the last property of the node, 211.Er ENOENT 212is returned. 213.It Dv OFIOCFINDDEVICE 214Uses a 215.Vt "struct ofiocdesc" . 216Takes the name or alias name of a device node. 217Returns package handle of the node. 218If no matching node is found, 219.Er ENOENT 220is returned. 221.El 222.Sh FILES 223.Bl -tag -width ".Pa /dev/openfirm" 224.It Pa /dev/openfirm 225Open Firmware interface node 226.El 227.Sh DIAGNOSTICS 228The following may result in rejection of an operation: 229.Bl -tag -width Er 230.It Bq Er EBADF 231The requested operation requires permissions not specified at the call to 232.Fn open . 233.It Bq Er EINVAL 234The given package handle is not 0 and does not correspond to any valid node, 235or the given package handle is 0 where 0 is not allowed. 236.It Bq Er ENAMETOOLONG 237The given name or value exceeds the maximum allowed length of 238.Dv OFIOCMAXNAME 239and 240.Dv OFIOCMAXVALUE 241bytes respectively. 242.El 243.Sh SEE ALSO 244.Xr ioctl 2 , 245.Xr ofwdump 8 246.Rs 247.%Q "IEEE Standards Organization" 248.%B "IEEE Std 1275-1994:" 249.%B "IEEE Standard for Boot Firmware (Initialization Configuration) Firmware:" 250.%B Core Requirements and Practices" 251.%O ISBN 1-55937-426-8 252.Re 253.Sh HISTORY 254The 255.Nm 256interface first appeared in 257.Nx 1.6 . 258The first 259.Fx 260version to include it was 261.Fx 5.0 . 262.Sh AUTHORS 263.An -nosplit 264The 265.Nm 266interface was ported to 267.Fx 268by 269.An Thomas Moestl Aq Mt tmm@FreeBSD.org . 270This manual page was written by 271.An Marius Strobl Aq Mt marius@FreeBSD.org 272based on the 273.Ox 274manual page for 275.Xr openprom 4 . 276.Sh CAVEATS 277Due to limitations within 278.Tn Open Firmware 279itself, 280these functions run at elevated priority and may adversely affect system 281performance. 282.Pp 283For at least the 284.Pa /options 285node the property value passed in to the 286.Dv OFIOCSET 287call has to be null-terminated and the value length passed in has to include 288the terminating 289.Ql \e0 . 290However, as with the 291.Dv OFIOCGET 292call, 293the returned value length does not include the terminating 294.Ql \e0 . 295