share/man/man4/man4.sparc/openprom.4

   1 .\"     $NetBSD: openprom.4,v 1.7 2003/04/16 13:35:21 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1992, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This software was developed by the Computer Systems Engineering group
   7 .\" at Lawrence Berkeley Laboratory under DARPA contract BG 91-66 and
   8 .\" contributed to Berkeley.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     from: @(#)openprom.4    8.1 (Berkeley) 6/5/93
  35 .\"
  36 .Dd June 5, 1993
  37 .Dt OPENPROM 4 sparc
  38 .Os
  39 .Sh NAME
  40 .Nm openprom
  41 .Nd Sun OPENPROM and EEPROM interface
  42 .Sh SYNOPSIS
  43 .In machine/openpromio.h
  44 .Sh DESCRIPTION
  45 The file
  46 .Nm /dev/openprom
  47 is an interface to the SPARC OPENPROM,
  48 including the EEPROM area.
  49 This interface is highly stylized;
  50 ioctls are used for all operations.
  51 These ioctls refer to
  52 .Dq nodes ,
  53 which are simply
  54 .Dq magic
  55 integer values describing data areas.
  56 Occasionally the number 0 may be used or returned instead,
  57 as described below.
  58 A special distinguished
  59 .Dq options
  60 node holds the EEPROM settings.
  61 .Pp
  62 The calls that take and/or return a node
  63 use a pointer to an
  64 .Li int
  65 variable for this purpose;
  66 others use a pointer to an
  67 .Li struct opiocdesc
  68 descriptor,
  69 which contains a node and two counted strings.
  70 The first string comprises the fields
  71 .Li op_namelen
  72 (an
  73 .Li int )
  74 and
  75 .Li op_name
  76 (a
  77 .Li "char *" ) ,
  78 giving the name of a field.
  79 The second string comprises the fields
  80 .Li op_buflen
  81 and
  82 .Li op_buf ,
  83 used analogously.
  84 These two counted strings work in a
  85 .Dq value-result
  86 fashion.
  87 At entry to the ioctl,
  88 the counts are expected to reflect the buffer size;
  89 on return,
  90 the counts are updated to reflect the buffer contents.
  91 .Pp
  92 The following ioctls are supported:
  93 .Bl -tag -width OPIOCGETOPTNODE
  94 .It Dv OPIOCGETOPTNODE
  95 Takes nothing, and fills in the options node number.
  96 .It OPIOCGETNEXT
  97 Takes a node number and returns the number of the following node.
  98 The node following the last node is number 0;
  99 the node following number 0 is the first node.
 100 .It Dv OPIOCGETCHILD
 101 Takes a node number and returns the number of the first
 102 .Dq child
 103 of that node.
 104 This child may have siblings; these can be discovered by using
 105 .Dv OPIOCGETNEXT .
 106 .It Dv OPIOCGET
 107 Fills in the value of the named property for the given node.
 108 If no such property is associated with that node,
 109 the value length is set to -1.
 110 If the named property exists but has no value,
 111 the value length is set to 0.
 112 .It Dv OPIOCSET
 113 Writes the given value under the given name.
 114 The OPENPROM may refuse this operation;
 115 in this case
 116 .Dv EINVAL
 117 is returned.
 118 .It Dv OPIOCNEXTPROP
 119 Finds the property whose name follows the given name
 120 in OPENPROM internal order.
 121 The resulting name is returned in the value field.
 122 If the named property is the last, the
 123 .Dq next
 124 name is the empty string.
 125 As with
 126 .Dv OPIOCGETNEXT ,
 127 the next name after the empty string is the first name.
 128 .El
 129 .Sh FILES
 130 .Pa /dev/openprom
 131 .Sh ERRORS
 132 The following may result in rejection of an operation:
 133 .Bl -tag -width Er
 134 .It Bq Er EINVAL
 135 The given node number
 136 is not zero
 137 and does not correspond to any valid node,
 138 or is zero where zero is not allowed.
 139 .It Bq Er EBADF
 140 The requested operation requires permissions not specified at the call to
 141 .Fn open .
 142 .It Bq Er ENAMETOOLONG
 143 The given name or value field
 144 exceeds the maximum allowed length (8191 bytes).
 145 .El
 146 .Sh SEE ALSO
 147 .Xr ioctl 2
 148 .Pp
 149 .Pa http://playground.sun.com/1275/
 150 .Sh BUGS
 151 Due to limitations within the
 152 .Nm
 153 itself, these functions run at elevated priority
 154 and may adversely affect system performance.
 155 .Pp
 156 The
 157 .Tn Sun
 158 .Nm
 159 is what became the Open Firmware
 160 .Pq Tn IEEE 1275
 161 standard for processor and system independent boot firmware.