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