1.\" Copyright (c) 1992, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" This software was developed by the Computer Systems Engineering group
5.\" at Lawrence Berkeley Laboratory under DARPA contract BG 91-66 and
6.\" contributed to Berkeley.
7.\"
8.\" %sccs.include.redist.man%
9.\"
10.\"     @(#)openprom.4	8.1 (Berkeley) 06/05/93
11.\"
12.Dd
13.Dt OPENPROM 4 sparc
14.Os
15.Sh NAME
16.Nm openprom
17.Nd OPENPROM and EEPROM interface
18.Sh SYNOPSIS
19.Fd #include <machine/openpromio.h>
20.Sh DESCRIPTION
21The file
22.Nm /dev/openprom
23is an interface to the SPARC OPENPROM,
24including the EEPROM area.
25This interface is highly stylized;
26ioctls are used for all operations.
27These ioctls refer to
28.Dq nodes ,
29which are simply
30.Dq magic
31integer values describing data areas.
32Occasionally the number 0 may be used or returned instead,
33as described below.
34A special distinguished
35.Dq options
36node holds the EEPROM settings.
37.Pp
38The calls that take and/or return a node
39use a pointer to an
40.Li int
41variable for this purpose;
42others use a pointer to an
43.Li struct opiocdesc
44descriptor,
45which contains a node and two counted strings.
46The first string is comprised of the fields
47.Li op_namelen
48(an
49.Li int )
50and
51.Li op_name
52(a
53.Li "char *" ) ,
54giving the name of a field.
55The second string is comprised of the fields
56.Li op_buflen
57and
58.Li op_buf ,
59used analogously.
60These two counted strings work in a
61.Dq value-result
62fashion.
63At entry to the ioctl,
64the counts are expected to reflect the buffer size;
65on return,
66the counts are updated to reflect the buffer contents.
67.Pp
68The following ioctls are supported:
69.Bl -tag -width OPIOCGETOPTNODE
70.It Dv OPIOCGETOPTNODE
71Takes nothing, and fills in the options node number.
72.It OPIOCGETNEXT
73Takes a node number and returns the number of the following node.
74The node following the last node is number 0;
75the node following number 0 is the first node.
76.It Dv OPIOCGETCHILD
77Takes a node number and returns the number of the first
78.Dq child
79of that node.
80This child may have siblings; these can be discovered by using
81.Dv OPIOCGETNEXT .
82.It Dv OPIOCGET
83Fills in the value of the named property for the given node.
84If no such property is associated with that node,
85the value length is set to -1.
86If the named property exists but has no value,
87the value length is set to 0.
88.It Dv OPIOCSET
89Writes the given value under the given name.
90The OPENPROM may refuse this operation;
91in this case
92.Dv EINVAL
93is returned.
94.It Dv OPIOCNEXTPROP
95Finds the property whose name follows the given name
96in OPENPROM internal order.
97The resulting name is returned in the value field.
98If the named property is the last, the
99.Dq next
100name is the empty string.
101As with
102.Dv OPIOCGETNEXT ,
103the next name after the empty string is the first name.
104.El
105.Sh FILES
106.Pa /dev/openprom
107.Sh ERRORS
108The following may result in rejection of an operation:
109.Bl -tag -width Er
110.It Bq Er EINVAL
111The given node number
112is not zero
113and does not correspond to any valid node,
114or is zero where zero is not allowed.
115.It Bq Er EBADF
116The requested operation requires permissions not specified at the call to
117.Fn open .
118.It Bq Er ENAMETOOLONG
119The given name or value field
120exceeds the maximum allowed length (8191 bytes).
121.El
122.Sh SEE ALSO
123.Xr ioctl 2
124.Sh BUGS
125Due to limitations within the OPENPROM itself,
126these functions run at elevated priority
127and may adversely affect system performance.
128