path: root/usr/src/man/man7d/openprom.7d

'\" te
.\"  Copyright (c) 1997, Sun Microsystems, Inc.
.\"  All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH OPENPROM 7D "Jan 13, 1997"
.SH NAME
openprom \- PROM monitor configuration interface
.SH SYNOPSIS
.LP
.nf
#include <sys/fcntl.h>
.fi

.LP
.nf
#include <sys/types.h>
.fi

.LP
.nf
#include <sys/openpromio.h>
.fi

.LP
.nf
open("/dev/openprom", \fImode\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The internal encoding of the configuration information stored in \fBEEPROM\fR
or \fBNVRAM\fR varies from model to model, and on some systems the encoding is
"hidden" by the firmware. The \fBopenprom\fR driver provides a consistent
interface that allows a user or program to inspect and modify that
configuration, using \fBioctl\fR(2) requests. These requests are defined in
\fB<sys/openpromio.h>\fR:
.sp
.in +2
.nf
struct openpromio {
    uint_t  oprom_size;       /* real size of following data */
    union {
         char  b[1];          /* NB: Adjacent, Null terminated */
         int   i;
				} opio_u;
};
#define oprom_array opio_u.b  /* property name/value array */
#define oprom_node opio_u.i   /* nodeid from navigation config-ops */
#define oprom_len opio_u.i    /* property len from OPROMGETPROPLEN */
#define OPROMMAXPARAM 32768   /* max size of array (advisory) */
.fi
.in -2

.sp
.LP
For all \fBioctl\fR(2) requests, the third parameter is a pointer to a
\fBstruct openpromio\fR. All property names and values are null-terminated
strings; the value of a numeric option is its \fBASCII\fR representation.
.sp
.LP
For the raw \fBioctl\fR(2) operations shown below that explicitly or implicitly
specify a nodeid, an error may be returned. This is due to the removal of the
node from the firmware device tree by a Dynamic Reconfiguration operation.
Programs should decide if the appropriate response is to restart the scanning
operation from the beginning or terminate, informing the user that the tree has
changed.
.SH IOCTLS
.sp
.ne 2
.na
\fB\fBOPROMGETOPT\fR\fR
.ad
.RS 19n
This ioctl takes the null-terminated name of a property in the
\fIoprom_array\fR and returns its null-terminated value (overlaying its name).
\fIoprom_size\fR should be set to the size of \fIoprom_array\fR; on return it
will contain the size of the returned value. If the named property does not
exist, or if there is not enough space to hold its value, then \fIoprom_size\fR
will be set to zero. See \fBBUGS\fR below.
.RE

.sp
.ne 2
.na
\fB\fBOPROMSETOPT\fR\fR
.ad
.RS 19n
This ioctl takes two adjacent strings in \fIoprom_array\fR; the null-terminated
property name followed by the null-terminated value.
.RE

.sp
.ne 2
.na
\fB\fBOPROMSETOPT2\fR\fR
.ad
.RS 19n
This ioctl is similar to  \fBOPROMSETOPT,\fR except that it uses the difference
between the actual user array size and the length of the property name plus its
null terminator.
.RE

.sp
.ne 2
.na
\fB\fBOPROMNXTOPT\fR\fR
.ad
.RS 19n
This ioctl is used to retrieve properties sequentially. The null-terminated
name of a property is placed into \fIoprom_array\fR and on return it is
replaced with the null-terminated name of the next property in the sequence,
with \fIoprom_size\fR set to its length. A null string on input means return
the name of the first property; an \fIoprom_size\fR of zero on output means
there are no more properties.
.RE

.sp
.ne 2
.na
\fB\fBOPROMNXT\fR\fR
.ad
.br
.na
\fB\fBOPROMCHILD\fR\fR
.ad
.br
.na
\fB\fBOPROMGETPROP\fR\fR
.ad
.br
.na
\fB\fBOPROMNXTPROP\fR\fR
.ad
.RS 19n
These ioctls provide an interface to the raw \fIconfig_ops\fR operations in the
\fBPROM\fR monitor. One can use them to traverse the system device tree; see
\fBprtconf\fR(1M).
.RE

.sp
.ne 2
.na
\fB\fBOPROMGETPROPLEN\fR\fR
.ad
.RS 19n
This ioctl provides an interface to the \fIproperty length\fR raw config op. It
takes the name of a property in the buffer, and returns an integer in the
buffer. It returns the integer \fB-1\fR if the property does not exist; \fB0\fR
if the property exists, but has no value (a boolean property); or a positive
integer which is the length of the property as reported by the \fBPROM\fR
monitor. See \fBBUGS\fR below.
.RE

.sp
.ne 2
.na
\fB\fBOPROMGETVERSION\fR\fR
.ad
.RS 19n
This ioctl returns an arbitrary and platform-dependent NULL-terminated string
in \fIoprom_array\fR, representing the underlying version of the firmware.
.RE

.SH ERRORS
.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
There are too many opens of the \fB/dev/openprom\fR device.
.RE

.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
A bad address has been passed to an \fBioctl\fR(2) routine.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The size value was invalid, or (for \fBOPROMSETOPT\fR) the       property does
not exist, or an invalid ioctl is being issued, or the ioctl is not supported
by the firmware, or the nodeid specified does not exist in the firmware device
tree.
.RE

.sp
.ne 2
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
The kernel could not allocate space to copy the user's structure.
.RE

.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 10n
Attempts have been made to write to a read-only entity, or read from a write
only entity.
.RE

.sp
.ne 2
.na
\fB\fBENXIO\fR\fR
.ad
.RS 10n
Attempting to open a non-existent device.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fR\fIoprom_array\fR Data Allocation and Reuse
.sp
.LP
The following example shows how the \fIoprom_array\fR is allocated and reused
for data returned by the driver.

.sp
.in +2
.nf
/*
 * This program opens the openprom device and prints the platform
 * name (root node name property) and the prom version.
 *
 * NOTE: /dev/openprom is readable only by user 'root' or group 'sys'.
 */
#include <stdio.h>
#include <string.h>
#include <fcntl.h>
#include <errno.h>
#include <unistd.h>
#include <stdlib.h>
#include <sys/openpromio.h>
#define    min(a, b)    (a < b ? a : b)
#define    max(a, b)    (a > b ? a : b)
#define MAXNAMESZ 32          /* Maximum property *name* size */
#define BUFSZ 1024            /* A Handly default buffer size */
#define MAXVALSZ    (BUFSZ - sizeof (int))
static char *promdev = "/dev/openprom";
/*
 * Allocate an openpromio structure big enough to contain
 * a bufsize'd oprom_array. Zero out the structure and
 * set the oprom_size field to bufsize.
 */
static struct openpromio *
opp_zalloc(size_t bufsize)
{
    struct openpromio *opp;
    opp = malloc(sizeof (struct openpromio) + bufsize);
    (void) memset(opp, 0, sizeof (struct openpromio) + bufsize);
    opp->oprom_size = bufsize;
    return (opp);
}
/*
 * Free a 'struct openpromio' allocated by opp_zalloc
 */
static void
opp_free(struct openpromio *opp)
{
    free(opp);
}
/*
 * Get the peer node of the given node.  The root node is the peer of zero.
 * After changing nodes, property lookups apply to that node.  The driver
 * 'remembers' what node you are in.
 */
static int
peer(int nodeid, int fd)
{
    struct openpromio *opp;
    int i;
    opp = opp_zalloc(sizeof (int));
    opp->oprom_node = nodeid;
    if (ioctl(fd, OPROMNEXT, opp) < 0) {
        perror("OPROMNEXT");
        exit(1);
    }
    i = opp->oprom_node;
    opp_free(opp);
    return(i);
}
int
main(void)
{
    struct openpromio *opp;
    int fd, proplen;
    size_t buflen;
    if ((fd = open(promdev, O_RDONLY)) < 0)  {
        fprintf(stderr, "Cannot open openprom device\en");
        exit(1);
    }
    /*
     * Get and print the length and value of the
     * root node 'name' property
     */
    (void) peer(0, fd);        /* Navigate to the root node */
    /*
     * Allocate an openpromio structure sized big enough to
     * take the string "name" as input and return the int-sized
     * length of the 'name' property.
     * Then, get the length of the 'name' property.
     */
    buflen = max(sizeof (int), strlen("name") + 1);
    opp = opp_zalloc(buflen);
    (void) strcpy(opp->oprom_array, "name");
    if (ioctl(fd, OPROMGETPROPLEN, opp) < 0) {
        perror("OPROMGETPROPLEN");
        /* exit(1); */
        proplen = 0;    /* down-rev driver? */
    } else
        proplen = opp->oprom_len;
    opp_free(opp);
    if (proplen == -1) {
        printf("'name' property does not exist!\en");
        exit (1);
    }
    /*
     * Allocate an openpromio structure sized big enough
     * to take the string 'name' as input and to return
     * 'proplen + 1' bytes.  Then, get the value of the
     * 'name' property. Note how we make sure to size the
     * array at least one byte more than the returned length
     * to guarantee NULL termination.
     */
    buflen = (proplen ? proplen + 1 : MAXVALSZ);
    buflen = max(buflen, strlen("name") + 1);
    opp = opp_zalloc(buflen);
    (void) strcpy(opp->oprom_array, "name");
    if (ioctl(fd, OPROMGETPROP, opp) < 0) {
        perror("OPROMGETPROP");
        exit(1);
    }
    if (opp->oprom_size != 0)
        printf("Platform name <%s> property len <%d>\en",
            opp->oprom_array, proplen);
    opp_free(opp);
    /*
     * Allocate an openpromio structure assumed to be
     * big enough to get the 'prom version string'.
     * Get and print the prom version.
     */
    opp_zalloc(MAXVALSZ);
    opp->oprom_size = MAXVALSZ;
    if (ioctl(fd, OPROMGETVERSION, opp) < 0) {
        perror("OPROMGETVERSION");
        exit(1);
    }
    printf("Prom version <%s>\en", opp->oprom_array);
    opp_free(opp);
    (void) close(fd);
    return (0);
}
.fi
.in -2

.SH FILES
.sp
.ne 2
.na
\fB\fB/dev/openprom\fR\fR
.ad
.RS 17n
PROM monitor configuration interface
.RE

.SH SEE ALSO
.sp
.LP
\fBeeprom\fR(1M), \fBmonitor\fR(1M), \fBprtconf\fR(1M), \fBioctl\fR(2),
\fBmem\fR(7D)
.SH BUGS
.sp
.LP
There should be separate return values for non-existent properties as opposed
to not enough space for the value.
.sp
.LP
An attempt to set a property to an illegal value results in the \fBPROM\fR
setting it to some legal value, with no error being returned. An
\fBOPROMGETOPT\fR should be performed after an \fBOPROMSETOPT\fR to verify that
the set worked.
.sp
.LP
Some \fBPROMS\fR \fIlie\fR about the property length of some string properties,
omitting the  \fBNULL\fR terminator from the property length.  The
\fBopenprom\fR driver attempts to \fItransparently\fR compensate for these bugs
when returning property values by  \fBNULL\fR terminating an extra character in
the user buffer if space is available in the user buffer. This extra character
is excluded from the \fIoprom_size\fR field returned from \fBOPROMGETPROP\fR
and \fBOPROMGETOPT\fR and excluded in the \fIoprom_len\fR field returned from
\fBOPROMGETPROPLEN\fR but is returned in the user buffer from the calls that
return data, if the user buffer is allocated at least one byte larger than the
property length.