OPENPROM(4D) Devices OPENPROM(4D)
NAME
openprom - PROM monitor configuration interface
SYNOPSIS
#include <sys/fcntl.h>
#include <sys/types.h>
#include <sys/openpromio.h>
open("/dev/openprom",
mode);
DESCRIPTION
The internal encoding of the configuration information stored in
EEPROM 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
<sys/openpromio.h>:
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) */
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
ASCII 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, informing
the user that the tree has changed.
IOCTLS
OPROMGETOPT This ioctl takes the null-terminated name of a
property in the
oprom_array and returns its null-
terminated value (overlaying its name).
oprom_size should be set to the size of
oprom_array; 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
oprom_size will
be set to zero. See
BUGS below.
OPROMSETOPT This ioctl takes two adjacent strings in
oprom_array;
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
oprom_array and on return it is
replaced with the null-terminated name of the next
property in the sequence, with
oprom_size set to its
length. A null string on input means return the name
of the first property; an
oprom_size of zero on output
means there are no more properties.
OPROMNXT OPROMCHILD OPROMGETPROP OPROMNXTPROP These ioctls provide an interface to the raw
config_ops operations in the
PROM monitor. One can use
them to traverse the system device tree; see
prtconf(8).
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 the property as reported by the
PROM monitor. See
BUGS below.
OPROMGETVERSION This ioctl returns an arbitrary and platform-dependent
NULL-terminated string in
oprom_array, representing
the underlying version of the firmware.
ERRORS
EAGAIN There are too many opens of the
/dev/openprom device.
EFAULT A bad address has been passed to an
ioctl(2) routine.
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 supported 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: oprom_array Data Allocation and Reuse
The following example shows how the
oprom_array 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 <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\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 = 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!\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 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>\n",
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>\n", opp->oprom_array);
opp_free(opp);
(void) close(fd);
return (0);
}
FILES
/dev/openprom PROM monitor configuration interface
SEE ALSO
ioctl(2),
mem(4D),
eeprom(8),
prtconf(8)BUGS
There should be separate return values for non-existent properties 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
OPROMSETOPT to verify that the
set worked.
Some
PROMS lie about the property length of some string properties,
omitting the
NULL terminator from the property length. The
openprom driver attempts to
transparently compensate for these bugs when returning
property values by
NULL terminating an extra character in the user
buffer if space is available in the user buffer. This extra character is
excluded from the
oprom_size field returned from
OPROMGETPROP and
OPROMGETOPT and excluded in the
oprom_len 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 property length.
March 6, 2023
OPENPROM(4D)