Kernel Functions for Drivers ddiproplookup(9F)
NAME
ddiproplookup, ddiproplookupintarray,
ddiproplookupint64array, ddiproplookupstringarray,
ddiproplookupstring, ddiproplookupbytearray,
ddipropfree - look up property information
SYNOPSIS
#include
#include
int ddiproplookupintarray(devt matchdev, devinfot *dip,
uintt flags, char *name, int **datap, uintt *nelementsp);
int ddiproplookupint64array(devt matchdev, devinfot *dip,
uintt flags, char *name, int64t **datap, uintt *nelementsp);
int ddiproplookupstringarray(devt matchdev, devinfot *dip,
uintt flags, char *name, char ***datap, uintt *nelementsp);
int ddiproplookupstring(devt matchdev, devinfot *dip, uintt flags,
char *name, char **datap);
int ddiproplookupbytearray(devt matchdev, devinfot *dip,
uintt flags, char *name, uchart **datap, uintt *nelementsp);
void ddipropfree(void *data);
PARAMETERS
matchdev Device number associated with property or
DIDEVTANY.
dip Pointer to the device info node of device
whose property list should be searched.
flags Possible flag values are some combination of:
DIPROPDONTPAS Do not pass request to
parent device information
node if the property is
not found.
SunOS 5.11 Last change: 11 Apr 2001 1
Kernel Functions for Drivers ddiproplookup(9F)
DIPROPNOTPROM Do not look at PROM pro-
perties (ignored on plat-
forms that do not support
PROM properties).
name String containing the name of the property.
nelementsp The address of an unsigned integer which, upon
successful return, will contain the number of
elements accounted for in the memory pointed
at by datap. The elements are either integers,
strings or bytes depending on the interface
used.
datap
ddiproplookupintarray()
The address of a pointer to an array of
integers which, upon successful return,
will point to memory containing the
integer array property value.
ddiproplookupint64array()
The address of a pointer to an array of
64-bit integers which, upon successful
return, will point to memory containing
the integer array property value.
ddiproplookupstringarray()
The address of a pointer to an array of
strings which, upon successful return,
will point to memory containing the array
of strings. The array of strings is for-
matted as an array of pointers to NUL
terminated strings, much like the argv
argument to execve(2).
ddiproplookupstring()
The address of a pointer to a string
which, upon successful return, will point
to memory containing the NUL terminated
string value of the property.
SunOS 5.11 Last change: 11 Apr 2001 2
Kernel Functions for Drivers ddiproplookup(9F)
ddiproplookupbytearray()
The address of pointer to an array of
bytes which, upon successful return, will
point to memory containing the byte array
value of the property.
INTERFACE LEVEL
Solaris DI specific (Solaris DI).
DESCRIPTION
The property look up routines search for and, if found,
return the value of a given property. Properties are
searched for based on the dip, name, matchdev, and the type
of the data (integer, string, or byte). The property search
order is as follows:
1. Search software properties created by the driver.
2. Search the software properties created by the sys-
tem (or nexus nodes in the device info tree).
3. Search the driver global properties list.
4. If DIPROPNOTPROM is not set, search the PROM
properties (if they exist).
5. If DIPROPDONTPAS is not set, pass this request
to the parent device information node.
6. Return DIPROPNOTFOUND.
Usually, the matchdev argument should be set to the actual
device number that this property is associated with. How-
ever, if the matchdev argument is DIDEVTANY, the pro-
perty look up routines will match the request regardless of
the actual matchdev the property was created with. If a
property was created with matchdev set to DIDEVTNONE,
then the only way to look up this property is with a
matchdev set to DIDEVTANY. PROM properties are always
created with matchdev set to DIDEVTNONE.
name must always be set to the name of the property being
looked up.
For the routines ddiproplookupintarray(),
ddiproplookupint64array(),
SunOS 5.11 Last change: 11 Apr 2001 3
Kernel Functions for Drivers ddiproplookup(9F)
ddiproplookupstringarray(), ddiproplookupstring(),
and ddiproplookupbytearray(), datap is the address of a
pointer which, upon successful return, will point to memory
containing the value of the property. In each case *datap
points to a different type of property value. See the indi-
vidual descriptions of the routines below for details on the
different return values. nelementsp is the address of an
unsigned integer which, upon successful return, will contain
the number of integer, string or byte elements accounted for
in the memory pointed at by *datap.
All of the property look up routines may block to allocate
memory needed to hold the value of the property.
When a driver has obtained a property with any look up rou-
tine and is finished with that property, it must be freed by
calling ddipropfree(). ddipropfree() must be called with
the address of the allocated property. For instance, if one
called ddiproplookupintarray() with datap set to the
address of a pointer to an integer, &myintptr, then the
companion free call would be ddipropfree(myintptr).
ddiproplookupintarray()
This routine searches for and returns an array of
integer property values. An array of integers is defined
to *nelementsp number of 4 byte long integer elements.
datap should be set to the address of a pointer to an
array of integers which, upon successful return, will
point to memory containing the integer array value of
the property.
ddiproplookupint64array()
This routine searches for and returns an array of 64-bit
integer property values. The array is defined to be
*nelementsp number of int64t elements. datap should be
set to the address of a pointer to an array of int64t's
which, upon successful return, will point to memory con-
taining the integer array value of the property. This
routine will not search the PROM for 64-bit property
values.
ddiproplookupstringarray()
This routine searches for and returns a property that is
an array of strings. datap should be set to address of a
pointer to an array of strings which, upon successful
SunOS 5.11 Last change: 11 Apr 2001 4
Kernel Functions for Drivers ddiproplookup(9F)
return, will point to memory containing the array of
strings. The array of strings is formatted as an array
of pointers to null-terminated strings, much like the
argv argument to execve(2).
ddiproplookupstring()
This routine searches for and returns a property that is
a null-terminated string. datap should be set to the
address of a pointer to string which, upon successful
return, will point to memory containing the string value
of the property.
ddiproplookupbytearray()
This routine searches for and returns a property that is
an array of bytes. datap should be set to the address of
a pointer to an array of bytes which, upon successful
return, will point to memory containing the byte array
value of the property.
ddipropfree()
Frees the resources associated with a property previ-
ously allocated using ddiproplookupintarray(),
ddiproplookupint64array(),
ddiproplookupstringarray(),
ddiproplookupstring(), or
ddiproplookupbytearray().
RETURN VALUES
The functions ddiproplookupintarray(),
ddiproplookupint64array(),
ddiproplookupstringarray(), ddiproplookupstring(),
and ddiproplookupbytearray() return the following
values:
DIPROPSUCES Upon success.
DIPROPINVALARG If an attempt is made to look up a
property with matchdev equal to
DIDEVTNONE, name is NUL or
name is the null string.
DIPROPNOTFOUND Property not found.
SunOS 5.11 Last change: 11 Apr 2001 5
Kernel Functions for Drivers ddiproplookup(9F)
DIPROPUNDEFINED Property explicitly not defined
(see ddipropundefine(9F)).
DIPROPCANOTDECODE The value of the property cannot
be decoded.
CONTEXT
These functions can be called from user or kernel context.
EXAMPLES
Example 1 Using ddiproplookupintarray()
The following example demonstrates the use of
ddiproplookupintarray().
int *options;
int noptions;
/*
* Get the data associated with the integer "options" property
* array, along with the number of option integers
*/
if (ddiproplookupintarray(DIDEVTANY, xxdip, 0,
"options", &options, &noptions) == DIPROPSUCES) {
/*
* Do "our thing" with the options data from the property
*/
xxprocessoptions(options, noptions);
/*
* Free the memory allocated for the property data
*/
ddipropfree(options);
}
SEE ALSO
execve(2), ddipropexists(9F), ddipropgetint(9F),
ddipropremove(9F), ddipropundefine(9F),
ddipropupdate(9F)
Writing Device Drivers
SunOS 5.11 Last change: 11 Apr 2001 6
|
