1.\" $OpenBSD: openprom.4,v 1.1 2019/04/25 16:47:56 denis Exp $ 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.\" 35.Dd $Mdocdate: April 25 2019 $ 36.Dt OPENPROM 4 37.Os 38.Sh NAME 39.Nm openprom 40.Nd OPENPROM interface 41.Sh SYNOPSIS 42.In machine/openpromio.h 43.Sh DESCRIPTION 44The file 45.Pa /dev/openprom 46is an interface to the OPENPROM. 47This interface is highly stylized, 48ioctls are used for all operations. 49These ioctls refer to 50.Dq nodes , 51which are simply 52.Dq magic 53integer values describing data areas. 54Occasionally the number 0 may be used or returned instead, 55as described below. 56.Pp 57The calls that take and/or return a node 58use a pointer to an 59.Li int 60variable for this purpose; 61others use a pointer to a 62.Li struct opiocdesc 63descriptor, 64which contains a node and two counted strings. 65The first string is comprised of the fields 66.Li op_namelen 67(an 68.Li int ) 69and 70.Li op_name 71(a 72.Li "char *" ) , 73giving the name of a field. 74The second string is comprised of the fields 75.Li op_buflen 76and 77.Li op_buf , 78used analogously. 79These two counted strings work in a 80.Dq value-result 81fashion. 82At entry to the ioctl, 83the counts are expected to reflect the buffer size; 84on return, 85the counts are updated to reflect the buffer contents. 86.Pp 87The following ioctls are supported: 88.Bl -tag -width OPIOCGETOPTNODE 89.It Dv OPIOCGETOPTNODE 90Takes nothing, and fills in the options node number. 91.It Dv OPIOCGETNEXT 92Takes a node number and returns the number of the following node. 93The node following the last node is number 0; 94the node following number 0 is the first node. 95.It Dv OPIOCGETCHILD 96Takes a node number and returns the number of the first 97.Dq child 98of that node. 99This child may have siblings; these can be discovered by using 100.Dv OPIOCGETNEXT . 101.It Dv OPIOCGET 102Fills in the value of the named property for the given node. 103If no such property is associated with that node, 104the value length is set to -1. 105If the named property exists but has no value, 106the value length is set to 0. 107.It Dv OPIOCSET 108Writes the given value under the given name. 109The OPENPROM may refuse this operation, 110in this case 111.Dv EINVAL 112is returned. 113.It Dv OPIOCNEXTPROP 114Finds the property whose name follows the given name 115in OPENPROM internal order. 116The resulting name is returned in the value field. 117If the named property is the last, the 118.Dq next 119name is the empty string. 120As with 121.Dv OPIOCGETNEXT , 122the next name after the empty string is the first name. 123.El 124.Sh FILES 125.Pa /dev/openprom 126.Sh ERRORS 127The following may result in rejection of an operation: 128.Bl -tag -width "[ENAMETOOLONG]" 129.It Bq Er EINVAL 130The given node number 131is not zero 132and does not correspond to any valid node, 133or is zero where zero is not allowed. 134.It Bq Er EBADF 135The requested operation requires permissions not specified at the call to 136.Fn open . 137.It Bq Er ENAMETOOLONG 138The given name or value field 139exceeds the maximum allowed length (8191 bytes). 140.It Bq Er ENOMEM 141Memory could not be allocated. 142.It Bq Er ENOTTY 143The ioctl is not supported on this architecture. 144.El 145.Sh SEE ALSO 146.Xr ioctl 2 , 147.Xr eeprom 8 148.Sh HISTORY 149The 150.Nm 151interface first appeared in 152.Ox 3.0 153for sparc64. 154It has been available on macppc since 155.Ox 4.3 , 156on octeon since 157.Ox 6.0 , 158on armv7 since 159.Ox 6.0 , 160and on arm64 since 161.Ox 6.1 . 162.Sh BUGS 163Due to limitations within the OPENPROM itself, 164these functions run at elevated priority 165and may adversely affect system performance. 166