Kernel Functions for Drivers ldiproplookupintarray(9F)
NAME
ldiproplookupintarray, ldiproplookupint64array,
ldiproplookupstringarray, ldiproplookupstring,
ldiproplookupbytearray - Lookup property information
SYNOPSIS
#include
int ldiproplookupintarray(ldihandlet lh, uintt flags, char *name,
int **datap, uintt *nelementsp);
int ldiproplookupint64array(ldihandlet lh, uintt flags, char *name,
int64t **datap, uintt *nelementsp);
int ldiproplookupstringarray(ldihandlet lh, uintt flags,
char *name, char ***datap, uintt *nelementsp);
int ldiproplookupstring(ldihandlet lh, uintt flags, char *name,
char **datap);
int ldiproplookupbytearray(ldihandlet lh, uintt flags, char *name,
uchart **datap, uintt *nelements);
PARAMETERS
lh Layered handle.
flags Possible flag values are some combination of:
LDIDEVTANY Match the lookup request
independent of the actual
devt value that was used when
the property was created. The
flag indicates any devt value
(including DIDEVTNONE)
associated with a possible
property match will satisfy
the matching criteria.
DIPROPDONTPAS Do not pass request to parent
device information node if the
property is not found.
DIPROPNOTPROM Do not look at PROM properties
(ignored on platforms that do
SunOS 5.11 Last change: 3 June 2003 1
Kernel Functions for Drivers ldiproplookupintarray(9F)
not support PROM properties).
name String containing the property name.
nelements The address of an unsigned integer which, upon
successful return, contains the number of ele-
ments accounted for in the memory pointed at by
datap. Depending on the interface you use, the
elements are either integers, strings or bytes.
datap
ldiproplookupintarray()
Pointer address to an array of integers which, upon suc-
cessful return, point to memory containing the integer
array property value.
ldiproplookupint64array()
Pointer address to an array of 64-bit integers which,
upon successful return, point to memory containing the
integer array property value.
ldiproplookupstringarray()
Pointer address to an array of strings which, upon suc-
cessful return, point to memory containing the array of
strings. The string array is formatted as an array of
pointers to NUL terminated strings, much like the argv
argument to execve(2).
ldiproplookupstring()
Pointer address to a string which, upon successful
return, points to memory containing the NUL terminated
string value of the property.
ldiproplookupbytearray()
Pointer address to an array of bytes which, upon suc-
cessful return, point to memory containing the property
byte array value.
SunOS 5.11 Last change: 3 June 2003 2
Kernel Functions for Drivers ldiproplookupintarray(9F)
INTERFACE LEVEL
Solaris DI specific (Solaris DI).
DESCRIPTION
The property look up functions search for and, if found,
return the value of a given property. Properties are
searched for based on the dip and devt values associated
with the layered handle, the property name, and 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 of the device
represented by the layered handle.
6. Return DIPROPNOTFOUND.
Typically, the specific devt value associated with the dev-
ice represented by the layered handle (ldihandlet) is used
as a part of the property match criteria. This association
is handled by the layered driver infrastructure on behalf of
the consumers of the ldi property look up functions.
However, if the LDIDEVTANY flag is used, the ldi property
lookup functions match the request regardless of the devt
value associated with the property at the time of its crea-
tion. If a property was created with a devt set to
DIDEVTNONE, then the only way to look up this property
is with the LDIDEVTANY flag. PROM properties are always
created with a devt set to DIDEVTNONE.
name must always be set to the name of the property being
looked up.
For the ldiproplookupintarray(),
ldiproplookupint64array(),
SunOS 5.11 Last change: 3 June 2003 3
Kernel Functions for Drivers ldiproplookupintarray(9F)
ldiproplookupstringarray(), ldiproplookupstring(),
and ldiproplookupbytearray() functions, datap is the
address of a pointer which, upon successful return, points
to memory containing the value of the property. In each case
*datap points to a different type of property value. See the
individual descriptions of the functions below for details
on the different return values. nelementsp is the address of
an unsigned integer which, upon successful return, contains
the number of integer, string or byte elements accounted for
in the memory pointed at by *datap.
All of the property look up functions may block to allocate
memory needed to hold the value of the property.
When a driver has obtained a property with any look up func-
tion and is finished with that property, it must be freed by
call ddipropfree(). ddipropfree() must be called with
the address of the allocated property. For instance, if you
call ldiproplookupintarray() with datap set to the
address of a pointer to an integer, &my-int-ptr, the compan-
ion free call is ddipropfree(my-int-ptr).
Property look up functions are described below:
ldiproplookupintarray()
This function 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.
ldiproplookupint64array()
This function searches for and returns an array of
integer property values. An array of integers is defined
to *nelementsp number of 8 byte long integer ele-
ments. 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 This function does not search the PROM
for 64-bit property values.
ldiproplookupstringarray()
SunOS 5.11 Last change: 3 June 2003 4
Kernel Functions for Drivers ldiproplookupintarray(9F)
This function searches for and returns a property that
is an array of strings. datap should be set to an
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 formatted as
an array of pointers to null-terminated strings, much
like the argv argument to execve(2).
ldiproplookupstring()
This function searches for and returns a property that
is a null-terminated string. datap should be set to the
address of a pointer to a string which, upon successful
return, points to memory containing the string value of
the property.
ldiproplookupbytearray()
This function 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, points to memory containing the byte
array value of the property.
ddipropfree()
Frees the resources associated with a property previ-
ously allocated using ldiproplookupintarray(),
ldiproplookupint64array(),
ldiproplookupstringarray(),
ldiproplookupstring(), and
ldiproplookupbytearray().
RETURN VALUES
The functions ldiproplookupintarray(),
ldiproplookupint64array(),
ldiproplookupstringarray(), ldiproplookupstring(),
and ldiproplookupbytearray() return the following
values:
DIPROPSUCES Property found and returned.
DIPROPINVALARG If an attempt is made to look up a
property with a NUL ldi handle,
name is NUL or name is a the null
string.
SunOS 5.11 Last change: 3 June 2003 5
Kernel Functions for Drivers ldiproplookupintarray(9F)
DIPROPNOTFOUND Property not found.
DIPROPUNDEFINED Prop explicitly undefined (see
ddipropundefine(9F)).
DIPROPCANOTDECODE Property value cannot be decoded.
CONTEXT
These functions may be called from user or kernel context.
EXAMPLE
Using ldiproplookupint64array().
The following example demonstrates the use of
ldiproplookupint64array().
int64t *options;
uintt noptions;
/*
* Get the data associated with the integer "options" property
* array, along with the number of option integers
*/
if (ldiproplookupint64array(lh,
LDIDEVTANYDIPROPNOTPROM, "options",
&options, &noptions) == DIPROPSUCES) {
/*
* Process the options data from the property
* we just received. Let's do "our thing" with data.
*/
xxprocessoptions(options, noptions);
/*
* Free the memory allocated for the property data
*/
ddipropfree(options);
}
SEE ALSO
execve(2), ddipropfree(9F), ddiproplookup(9F),
ldipropexists(9F) .
Writing Device Drivers
SunOS 5.11 Last change: 3 June 2003 6
|
