Kernel Functions for Drivers ddipropop(9F)
NAME
ddipropop, ddigetprop, ddigetlongprop,
ddigetlongpropbuf, ddigetproplen - get property informa-
tion for leaf device drivers
SYNOPSIS
#include
#include
#include
int ddipropop(devt dev, devinfot *dip, ddipropopt propop,
int flags, char *name, caddrt valuep, int *lengthp);
int ddigetprop(devt dev, devinfot *dip, int flags, char *name,
int defvalue);
int ddigetlongprop(devt dev, devinfot *dip, int flags, char *name,
caddrt valuep, int *lengthp);
int ddigetlongpropbuf(devt dev, devinfot *dip, int flags, char *name,
caddrt valuep, int *lengthp);
int ddigetproplen(devt dev, devinfot *dip, int flags, char *name,
int *lengthp);
INTERFACE LEVEL
Solaris DI specific (Solaris DI). The ddigetlongprop(),
ddigetlongpropbuf(), ddigetprop(), and ddigetproplen()
functions are obsolete. Use ddiproplookup(9F) instead of
ddigetlongprop(), ddigetlongpropbuf(), and
ddigetproplen(). Use ddipropgetint(9F) instead of
ddigetprop()
PARAMETERS
dev Device number associated with property or
DIDEVTANY as the wildcard device number.
dip Pointer to a device info node.
propop Property operator.
SunOS 5.11 Last change: 16 Jan 2006 1
Kernel Functions for Drivers ddipropop(9F)
flags Possible flag values are some combination of:
DIPROPDONTPAS do not pass request to
parent device information
node if property not found
DIPROPCANSLEP the routine may sleep while
allocating memory
DIPROPNOTPROM do not look at PROM proper-
ties (ignored on architec-
tures that do not support
PROM properties)
name String containing the name of the property.
valuep If propop is PROPLENANDVALBUF, this should
be a pointer to the users buffer. If propop is
PROPLENANDVALALOC, this should be the
address of a pointer.
lengthp On exit, *lengthp will contain the property
length. If propop is PROPLENANDVALBUF then
before calling ddipropop(), lengthp should
point to an int that contains the length of
callers buffer.
defvalue The value that ddigetprop() returns if the pro-
perty is not found.
DESCRIPTION
The ddipropop() function gets arbitrary-size properties
for leaf devices. The routine searches the device's property
list. If it does not find the property at the device level,
it examines the flags argument, and if DIPROPDONTPAS is
set, then ddipropop() returns DIPROPNOTFOUND. Other-
wise, it passes the request to the next level of the device
info tree. If it does find the property, but the property
has been explicitly undefined, it returns
DIPROPUNDEFINED. Otherwise it returns either the property
length, or both the length and value of the property to the
caller via the valuep and lengthp pointers, depending on the
value of propop, as described below, and returns
DIPROPSUCES. If a property cannot be found at all,
SunOS 5.11 Last change: 16 Jan 2006 2
Kernel Functions for Drivers ddipropop(9F)
DIPROPNOTFOUND is returned.
Usually, the dev argument should be set to the actual device
number that this property applies to. However, if the dev
argument is DIDEVTANY, the wildcard dev, then
ddipropop() will match the request based on name only
(regardless of the actual dev the property was created
with). This property/dev match is done according to the pro-
perty search order which is to first search software proper-
ties created by the driver in last-in, first-out (LIFO)
order, next search software properties created by the system
in LIFO order, then search PROM properties if they exist in
the system architecture.
Property operations are specified by the propop argument.
If propop is PROPLEN, then ddipropop() just sets the
callers length, *lengthp, to the property length and returns
the value DIPROPSUCES to the caller. The valuep argu-
ment is not used in this case. Property lengths are 0 for
boolean properties, sizeof(int) for integer properties, and
size in bytes for long (variable size) properties.
If propop is PROPLENANDVALBUF, then valuep should be a
pointer to a user-supplied buffer whose length should be
given in *lengthp by the caller. If the requested property
exists, ddipropop() first sets *lengthp to the property
length. It then examines the size of the buffer supplied by
the caller, and if it is large enough, copies the property
value into that buffer, and returns DIPROPSUCES. If the
named property exists but the buffer supplied is too small
to hold it, it returns DIPROPBUFTOSMAL.
If propop is PROPLENANDVALALOC, and the property is
found, ddipropop() sets *lengthp to the property length.
It then attempts to allocate a buffer to return to the
caller using the kmemalloc(9F) routine, so that memory can
be later recycled using kmemfree(9F). The driver is
expected to call kmemfree() with the returned address and
size when it is done using the allocated buffer. If the
allocation is successful, it sets *valuep to point to the
allocated buffer, copies the property value into the buffer
and returns DIPROPSUCES. Otherwise, it returns
DIPROPNOMEMORY. Note that the flags argument may affect
the behavior of memory allocation in ddipropop(). In par-
ticular, if DIPROPCANSLEP is set, then the routine will
wait until memory is available to copy the requested pro-
perty.
SunOS 5.11 Last change: 16 Jan 2006 3
Kernel Functions for Drivers ddipropop(9F)
The ddigetprop() function returns boolean and integer-size
properties. It is a convenience wrapper for ddipropop()
with propop set to PROPLENANDVALBUF, and the buffer is
provided by the wrapper. By convention, this function
returns a 1 for boolean (zero-length) properties.
The ddigetlongprop() function returns arbitrary-size pro-
perties. It is a convenience wrapper for ddipropop() with
propop set to PROPLENANDVALALOC, so that the routine
will allocate space to hold the buffer that will be returned
to the caller via *valuep.
The ddigetlongpropbuf() function returns arbitrary-size
properties. It is a convenience wrapper for ddipropop()
with propop set to PROPLENANDVALBUF so the user must
supply a buffer.
The ddigetproplen() function returns the length of a given
property. It is a convenience wrapper for ddipropop() with
propop set to PROPLEN.
RETURN VALUES
The ddipropop(), ddigetlongprop(), ddigetlongpropbuf(),
and ddigetproplen() functions return:
DIPROPSUCES Property found and returned.
DIPROPNOTFOUND Property not found.
DIPROPUNDEFINED Property already explicitly unde-
fined.
DIPROPNOMEMORY Property found, but unable to
allocate memory. lengthp points to
the correct property length.
DIPROPBUFTOSMAL Property found, but the supplied
buffer is too small. lengthp
points to the correct property
length.
The ddigetprop() function returns:
SunOS 5.11 Last change: 16 Jan 2006 4
Kernel Functions for Drivers ddipropop(9F)
The value of the property or the value passed into the rou-
tine as defvalue if the property is not found. By conven-
tion, the value of zero length properties (boolean proper-
ties) are returned as the integer value 1.
CONTEXT
These functions can be called from user, interrupt, or ker-
nel context, provided DIPROPCANSLEP is not set; if it is
set, they cannot be called from interrupt context.
ATRIBUTES
See attributes(5) for a description of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Stability Level ddigetlongprop(),
ddigetlongpropbuf(),
ddigetprop(), and
ddigetproplen() functions are
Obsolete
SEE ALSO
attributes(5), ddipropcreate(9F), ddipropgetint(9F),
ddiproplookup(9F), kmemalloc(9F), kmemfree(9F)
Writing Device Drivers
SunOS 5.11 Last change: 16 Jan 2006 5
|
