Devices openprom(7D)
NAME
openprom - PROM monitor configuration interface
SYNOPSIS
#include
#include
#include
open("/dev/openprom", mode);
DESCRIPTION
The internal encoding of the configuration information
stored in EPROM or NVRAM varies from model to model, and on
some systems the encoding is "hidden" by the firmware. The
openprom driver provides a consistent interface that allows
a user or program to inspect and modify that configuration,
using ioctl(2) requests. These requests are defined in
:
struct openpromio {
uintt opromsize; /* real size of following data */
union {
char b[1]; /* NB: Adjacent, Null terminated */
int i;
} opiou;
};
#define opromarray opiou.b /* property name/value array */
#define opromnode opiou.i /* nodeid from navigation config-ops */
#define opromlen opiou.i /* property len from OPROMGETPROPLEN */
#define OPROMAXPARAM 32768 /* max size of array (advisory) */
For all ioctl(2) requests, the third parameter is a pointer
to a struct openpromio. All property names and values are
null-terminated strings; the value of a numeric option is
its ASCI representation.
For the raw ioctl(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, inform-
ing the user that the tree has changed.
SunOS 5.11 Last change: 13 Jan 1997 1
Devices openprom(7D)
IOCTLS
OPROMGETOPT This ioctl takes the null-terminated name
of a property in the opromarray and
returns its null-terminated value (over-
laying its name). opromsize should be
set to the size of opromarray; 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 opromsize will be
set to zero. See BUGS below.
OPROMSETOPT This ioctl takes two adjacent strings in
opromarray; the null-terminated property
name followed by the null-terminated
value.
OPROMSETOPT2 This ioctl is similar to OPROMSETOPT,
except that it uses the difference
between the actual user array size and
the length of the property name plus its
null terminator.
OPROMNXTOPT This ioctl is used to retrieve properties
sequentially. The null-terminated name of
a property is placed into opromarray and
on return it is replaced with the null-
terminated name of the next property in
the sequence, with opromsize set to its
length. A null string on input means
return the name of the first property; an
opromsize of zero on output means there
are no more properties.
OPROMNXT These ioctls provide an interface to the
OPROMCHILD raw configops operations in the PROM
OPROMGETPROP monitor. One can use them to traverse the
OPROMNXTPROP system device tree; see prtconf(1M).
OPROMGETPROPLEN This ioctl provides an interface to the
property length raw config op. It takes
the name of a property in the buffer, and
returns an integer in the buffer. It
returns the integer -1 if the property
does not exist; 0 if the property exists,
but has no value (a boolean property); or
a positive integer which is the length of
SunOS 5.11 Last change: 13 Jan 1997 2
Devices openprom(7D)
the property as reported by the PROM mon-
itor. See BUGS below.
OPROMGETVERSION This ioctl returns an arbitrary and
platform-dependent NUL-terminated string
in opromarray, representing the underly-
ing version of the firmware.
ERORS
EAGAIN There are too many opens of the /dev/openprom dev-
ice.
EFAULT A bad address has been passed to an ioctl(2) rou-
tine.
EINVAL The size value was invalid, or (for OPROMSETOPT)
the property does not exist, or an invalid
ioctl is being issued, or the ioctl is not sup-
ported by the firmware, or the nodeid specified
does not exist in the firmware device tree.
ENOMEM The kernel could not allocate space to copy the
user's structure.
EPERM Attempts have been made to write to a read-only
entity, or read from a write only entity.
ENXIO Attempting to open a non-existent device.
EXAMPLES
Example 1 opromarray Data Allocation and Reuse
The following example shows how the opromarray is allocated
and reused for data returned by the driver.
/*
* 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
SunOS 5.11 Last change: 13 Jan 1997 3
Devices openprom(7D)
#include
#include
#include
#include
#include
#include
#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 opromarray. Zero out the structure and
* set the opromsize field to bufsize.
*/
static struct openpromio *
oppzalloc(sizet bufsize)
{
struct openpromio *opp;
opp = malloc(sizeof (struct openpromio) ] bufsize);
(void) memset(opp, 0, sizeof (struct openpromio) ] bufsize);
opp->opromsize = bufsize;
return (opp);
}
/*
* Free a 'struct openpromio' allocated by oppzalloc
*/
static void
oppfree(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 = oppzalloc(sizeof (int));
opp->opromnode = nodeid;
if (ioctl(fd, OPROMNEXT, opp) < 0) {
perror("OPROMNEXT");
exit(1);
}
i = opp->opromnode;
oppfree(opp);
SunOS 5.11 Last change: 13 Jan 1997 4
Devices openprom(7D)
return(i);
}
int
main(void)
{
struct openpromio *opp;
int fd, proplen;
sizet buflen;
if ((fd = open(promdev, ORDONLY)) < 0) {
fprintf(stderr, "Cannot open openprom device\n");
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 = oppzalloc(buflen);
(void) strcpy(opp->opromarray, "name");
if (ioctl(fd, OPROMGETPROPLEN, opp) < 0) {
perror("OPROMGETPROPLEN");
/* exit(1); */
proplen = 0; /* down-rev driver? */
} else
proplen = opp->opromlen;
oppfree(opp);
if (proplen == -1) {
printf("'name' property does not exist!\n");
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 NUL termination.
*/
buflen = (proplen ? proplen ] 1 : MAXVALSZ);
buflen = max(buflen, strlen("name") ] 1);
opp = oppzalloc(buflen);
(void) strcpy(opp->opromarray, "name");
if (ioctl(fd, OPROMGETPROP, opp) < 0) {
perror("OPROMGETPROP");
exit(1);
SunOS 5.11 Last change: 13 Jan 1997 5
Devices openprom(7D)
}
if (opp->opromsize != 0)
printf("Platform name <%s> property len <%d>\n",
opp->opromarray, proplen);
oppfree(opp);
/*
* Allocate an openpromio structure assumed to be
* big enough to get the 'prom version string'.
* Get and print the prom version.
*/
oppzalloc(MAXVALSZ);
opp->opromsize = MAXVALSZ;
if (ioctl(fd, OPROMGETVERSION, opp) < 0) {
perror("OPROMGETVERSION");
exit(1);
}
printf("Prom version <%s>\n", opp->opromarray);
oppfree(opp);
(void) close(fd);
return (0);
}
FILES
/dev/openprom PROM monitor configuration interface
SEE ALSO
eeprom(1M), monitor(1M), prtconf(1M), ioctl(2), mem(7D)
BUGS
There should be separate return values for non-existent pro-
perties as opposed to not enough space for the value.
An attempt to set a property to an illegal value results in
the PROM setting it to some legal value, with no error being
returned. An OPROMGETOPT should be performed after an OPROM-
SETOPT to verify that the set worked.
Some PROMS lie about the property length of some string pro-
perties, omitting the NUL terminator from the property
length. The openprom driver attempts to transparently com-
pensate for these bugs when returning property values by
NUL terminating an extra character in the user buffer if
space is available in the user buffer. This extra character
is excluded from the opromsize field returned from
OPROMGETPROP and OPROMGETOPT and excluded in the opromlen
field returned from OPROMGETPROPLEN 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
SunOS 5.11 Last change: 13 Jan 1997 6
Devices openprom(7D)
property length.
SunOS 5.11 Last change: 13 Jan 1997 7
|
