| blob | ff3382f7006ad2dab9ae4c299d8990ce6a965f1c |
1 '\" te
2 .\" Copyright (c) 1997, Sun Microsystems, Inc.
3 .\" All Rights Reserved
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH OPENPROM 7D "Jan 13, 1997"
8 .SH NAME
9 openprom \- PROM monitor configuration interface
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <sys/fcntl.h>
14 .fi
16 .LP
17 .nf
18 #include <sys/types.h>
19 .fi
21 .LP
22 .nf
23 #include <sys/openpromio.h>
24 .fi
26 .LP
27 .nf
28 open("/dev/openprom", \fImode\fR);
29 .fi
31 .SH DESCRIPTION
32 .sp
33 .LP
34 The internal encoding of the configuration information stored in \fBEEPROM\fR
35 or \fBNVRAM\fR varies from model to model, and on some systems the encoding is
36 "hidden" by the firmware. The \fBopenprom\fR driver provides a consistent
37 interface that allows a user or program to inspect and modify that
38 configuration, using \fBioctl\fR(2) requests. These requests are defined in
39 \fB<sys/openpromio.h>\fR:
40 .sp
41 .in +2
42 .nf
43 struct openpromio {
44 uint_t oprom_size; /* real size of following data */
45 union {
46 char b[1]; /* NB: Adjacent, Null terminated */
47 int i;
48 } opio_u;
49 };
50 #define oprom_array opio_u.b /* property name/value array */
51 #define oprom_node opio_u.i /* nodeid from navigation config-ops */
52 #define oprom_len opio_u.i /* property len from OPROMGETPROPLEN */
53 #define OPROMMAXPARAM 32768 /* max size of array (advisory) */
54 .fi
55 .in -2
57 .sp
58 .LP
59 For all \fBioctl\fR(2) requests, the third parameter is a pointer to a
60 \fBstruct openpromio\fR. All property names and values are null-terminated
61 strings; the value of a numeric option is its \fBASCII\fR representation.
62 .sp
63 .LP
64 For the raw \fBioctl\fR(2) operations shown below that explicitly or implicitly
65 specify a nodeid, an error may be returned. This is due to the removal of the
66 node from the firmware device tree by a Dynamic Reconfiguration operation.
67 Programs should decide if the appropriate response is to restart the scanning
68 operation from the beginning or terminate, informing the user that the tree has
69 changed.
70 .SH IOCTLS
71 .sp
72 .ne 2
73 .na
74 \fB\fBOPROMGETOPT\fR\fR
75 .ad
76 .RS 19n
77 This ioctl takes the null-terminated name of a property in the
78 \fIoprom_array\fR and returns its null-terminated value (overlaying its name).
79 \fIoprom_size\fR should be set to the size of \fIoprom_array\fR; on return it
80 will contain the size of the returned value. If the named property does not
81 exist, or if there is not enough space to hold its value, then \fIoprom_size\fR
82 will be set to zero. See \fBBUGS\fR below.
83 .RE
85 .sp
86 .ne 2
87 .na
88 \fB\fBOPROMSETOPT\fR\fR
89 .ad
90 .RS 19n
91 This ioctl takes two adjacent strings in \fIoprom_array\fR; the null-terminated
92 property name followed by the null-terminated value.
93 .RE
95 .sp
96 .ne 2
97 .na
98 \fB\fBOPROMSETOPT2\fR\fR
99 .ad
100 .RS 19n
101 This ioctl is similar to \fBOPROMSETOPT,\fR except that it uses the difference
102 between the actual user array size and the length of the property name plus its
103 null terminator.
104 .RE
106 .sp
107 .ne 2
108 .na
109 \fB\fBOPROMNXTOPT\fR\fR
110 .ad
111 .RS 19n
112 This ioctl is used to retrieve properties sequentially. The null-terminated
113 name of a property is placed into \fIoprom_array\fR and on return it is
114 replaced with the null-terminated name of the next property in the sequence,
115 with \fIoprom_size\fR set to its length. A null string on input means return
116 the name of the first property; an \fIoprom_size\fR of zero on output means
117 there are no more properties.
118 .RE
120 .sp
121 .ne 2
122 .na
123 \fB\fBOPROMNXT\fR\fR
124 .ad
125 .br
126 .na
127 \fB\fBOPROMCHILD\fR\fR
128 .ad
129 .br
130 .na
131 \fB\fBOPROMGETPROP\fR\fR
132 .ad
133 .br
134 .na
135 \fB\fBOPROMNXTPROP\fR\fR
136 .ad
137 .RS 19n
138 These ioctls provide an interface to the raw \fIconfig_ops\fR operations in the
139 \fBPROM\fR monitor. One can use them to traverse the system device tree; see
140 \fBprtconf\fR(8).
141 .RE
143 .sp
144 .ne 2
145 .na
146 \fB\fBOPROMGETPROPLEN\fR\fR
147 .ad
148 .RS 19n
149 This ioctl provides an interface to the \fIproperty length\fR raw config op. It
150 takes the name of a property in the buffer, and returns an integer in the
151 buffer. It returns the integer \fB-1\fR if the property does not exist; \fB0\fR
152 if the property exists, but has no value (a boolean property); or a positive
153 integer which is the length of the property as reported by the \fBPROM\fR
154 monitor. See \fBBUGS\fR below.
155 .RE
157 .sp
158 .ne 2
159 .na
160 \fB\fBOPROMGETVERSION\fR\fR
161 .ad
162 .RS 19n
163 This ioctl returns an arbitrary and platform-dependent NULL-terminated string
164 in \fIoprom_array\fR, representing the underlying version of the firmware.
165 .RE
167 .SH ERRORS
168 .sp
169 .ne 2
170 .na
171 \fB\fBEAGAIN\fR\fR
172 .ad
173 .RS 10n
174 There are too many opens of the \fB/dev/openprom\fR device.
175 .RE
177 .sp
178 .ne 2
179 .na
180 \fB\fBEFAULT\fR\fR
181 .ad
182 .RS 10n
183 A bad address has been passed to an \fBioctl\fR(2) routine.
184 .RE
186 .sp
187 .ne 2
188 .na
189 \fB\fBEINVAL\fR\fR
190 .ad
191 .RS 10n
192 The size value was invalid, or (for \fBOPROMSETOPT\fR) the property does
193 not exist, or an invalid ioctl is being issued, or the ioctl is not supported
194 by the firmware, or the nodeid specified does not exist in the firmware device
195 tree.
196 .RE
198 .sp
199 .ne 2
200 .na
201 \fB\fBENOMEM\fR\fR
202 .ad
203 .RS 10n
204 The kernel could not allocate space to copy the user's structure.
205 .RE
207 .sp
208 .ne 2
209 .na
210 \fB\fBEPERM\fR\fR
211 .ad
212 .RS 10n
213 Attempts have been made to write to a read-only entity, or read from a write
214 only entity.
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fB\fBENXIO\fR\fR
221 .ad
222 .RS 10n
223 Attempting to open a non-existent device.
224 .RE
226 .SH EXAMPLES
227 .LP
228 \fBExample 1 \fR\fIoprom_array\fR Data Allocation and Reuse
229 .sp
230 .LP
231 The following example shows how the \fIoprom_array\fR is allocated and reused
232 for data returned by the driver.
234 .sp
235 .in +2
236 .nf
237 /*
238 * This program opens the openprom device and prints the platform
239 * name (root node name property) and the prom version.
240 *
241 * NOTE: /dev/openprom is readable only by user 'root' or group 'sys'.
242 */
243 #include <stdio.h>
244 #include <string.h>
245 #include <fcntl.h>
246 #include <errno.h>
247 #include <unistd.h>
248 #include <stdlib.h>
249 #include <sys/openpromio.h>
250 #define min(a, b) (a < b ? a : b)
251 #define max(a, b) (a > b ? a : b)
252 #define MAXNAMESZ 32 /* Maximum property *name* size */
253 #define BUFSZ 1024 /* A Handly default buffer size */
254 #define MAXVALSZ (BUFSZ - sizeof (int))
255 static char *promdev = "/dev/openprom";
256 /*
257 * Allocate an openpromio structure big enough to contain
258 * a bufsize'd oprom_array. Zero out the structure and
259 * set the oprom_size field to bufsize.
260 */
261 static struct openpromio *
262 opp_zalloc(size_t bufsize)
263 {
264 struct openpromio *opp;
265 opp = malloc(sizeof (struct openpromio) + bufsize);
266 (void) memset(opp, 0, sizeof (struct openpromio) + bufsize);
267 opp->oprom_size = bufsize;
268 return (opp);
269 }
270 /*
271 * Free a 'struct openpromio' allocated by opp_zalloc
272 */
273 static void
274 opp_free(struct openpromio *opp)
275 {
276 free(opp);
277 }
278 /*
279 * Get the peer node of the given node. The root node is the peer of zero.
280 * After changing nodes, property lookups apply to that node. The driver
281 * 'remembers' what node you are in.
282 */
283 static int
284 peer(int nodeid, int fd)
285 {
286 struct openpromio *opp;
287 int i;
288 opp = opp_zalloc(sizeof (int));
289 opp->oprom_node = nodeid;
290 if (ioctl(fd, OPROMNEXT, opp) < 0) {
291 perror("OPROMNEXT");
292 exit(1);
293 }
294 i = opp->oprom_node;
295 opp_free(opp);
296 return(i);
297 }
298 int
299 main(void)
300 {
301 struct openpromio *opp;
302 int fd, proplen;
303 size_t buflen;
304 if ((fd = open(promdev, O_RDONLY)) < 0) {
305 fprintf(stderr, "Cannot open openprom device\en");
306 exit(1);
307 }
308 /*
309 * Get and print the length and value of the
310 * root node 'name' property
311 */
312 (void) peer(0, fd); /* Navigate to the root node */
313 /*
314 * Allocate an openpromio structure sized big enough to
315 * take the string "name" as input and return the int-sized
316 * length of the 'name' property.
317 * Then, get the length of the 'name' property.
318 */
319 buflen = max(sizeof (int), strlen("name") + 1);
320 opp = opp_zalloc(buflen);
321 (void) strcpy(opp->oprom_array, "name");
322 if (ioctl(fd, OPROMGETPROPLEN, opp) < 0) {
323 perror("OPROMGETPROPLEN");
324 /* exit(1); */
325 proplen = 0; /* down-rev driver? */
326 } else
327 proplen = opp->oprom_len;
328 opp_free(opp);
329 if (proplen == -1) {
330 printf("'name' property does not exist!\en");
331 exit (1);
332 }
333 /*
334 * Allocate an openpromio structure sized big enough
335 * to take the string 'name' as input and to return
336 * 'proplen + 1' bytes. Then, get the value of the
337 * 'name' property. Note how we make sure to size the
338 * array at least one byte more than the returned length
339 * to guarantee NULL termination.
340 */
341 buflen = (proplen ? proplen + 1 : MAXVALSZ);
342 buflen = max(buflen, strlen("name") + 1);
343 opp = opp_zalloc(buflen);
344 (void) strcpy(opp->oprom_array, "name");
345 if (ioctl(fd, OPROMGETPROP, opp) < 0) {
346 perror("OPROMGETPROP");
347 exit(1);
348 }
349 if (opp->oprom_size != 0)
350 printf("Platform name <%s> property len <%d>\en",
351 opp->oprom_array, proplen);
352 opp_free(opp);
353 /*
354 * Allocate an openpromio structure assumed to be
355 * big enough to get the 'prom version string'.
356 * Get and print the prom version.
357 */
358 opp_zalloc(MAXVALSZ);
359 opp->oprom_size = MAXVALSZ;
360 if (ioctl(fd, OPROMGETVERSION, opp) < 0) {
361 perror("OPROMGETVERSION");
362 exit(1);
363 }
364 printf("Prom version <%s>\en", opp->oprom_array);
365 opp_free(opp);
366 (void) close(fd);
367 return (0);
368 }
369 .fi
370 .in -2
372 .SH FILES
373 .sp
374 .ne 2
375 .na
376 \fB\fB/dev/openprom\fR\fR
377 .ad
378 .RS 17n
379 PROM monitor configuration interface
380 .RE
382 .SH SEE ALSO
383 .sp
384 .LP
385 \fBeeprom\fR(8), \fBmonitor\fR(8), \fBprtconf\fR(8), \fBioctl\fR(2),
386 \fBmem\fR(7D)
387 .SH BUGS
388 .sp
389 .LP
390 There should be separate return values for non-existent properties as opposed
391 to not enough space for the value.
392 .sp
393 .LP
394 An attempt to set a property to an illegal value results in the \fBPROM\fR
395 setting it to some legal value, with no error being returned. An
396 \fBOPROMGETOPT\fR should be performed after an \fBOPROMSETOPT\fR to verify that
397 the set worked.
398 .sp
399 .LP
400 Some \fBPROMS\fR \fIlie\fR about the property length of some string properties,
401 omitting the \fBNULL\fR terminator from the property length. The
402 \fBopenprom\fR driver attempts to \fItransparently\fR compensate for these bugs
403 when returning property values by \fBNULL\fR terminating an extra character in
404 the user buffer if space is available in the user buffer. This extra character
405 is excluded from the \fIoprom_size\fR field returned from \fBOPROMGETPROP\fR
406 and \fBOPROMGETOPT\fR and excluded in the \fIoprom_len\fR field returned from
407 \fBOPROMGETPROPLEN\fR but is returned in the user buffer from the calls that
408 return data, if the user buffer is allocated at least one byte larger than the
409 property length.