DDI_PROP_OP(9F) Kernel Functions for Drivers DDI_PROP_OP(9F)
NAME
ddi_prop_op, ddi_getprop, ddi_getlongprop, ddi_getlongprop_buf,
ddi_getproplen - get property information for leaf device drivers
SYNOPSIS
#include <sys/types.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>
int ddi_prop_op(
dev_t dev,
dev_info_t *dip,
ddi_prop_op_t prop_op,
int flags,
char *name,
caddr_t valuep,
int *lengthp);
int ddi_getprop(
dev_t dev,
dev_info_t *dip,
int flags,
char *name,
int defvalue);
int ddi_getlongprop(
dev_t dev,
dev_info_t *dip,
int flags,
char *name,
caddr_t valuep,
int *lengthp);
int ddi_getlongprop_buf(
dev_t dev,
dev_info_t *dip,
int flags,
char *name,
caddr_t valuep,
int *lengthp);
int ddi_getproplen(
dev_t dev,
dev_info_t *dip,
int flags,
char *name,
int *lengthp);
INTERFACE LEVEL
illumos DDI specific (illumos DDI). The
ddi_getlongprop(),
ddi_getlongprop_buf(),
ddi_getprop(), and
ddi_getproplen() functions are
obsolete. Use
ddi_prop_lookup(9F) instead of
ddi_getlongprop(),
ddi_getlongprop_buf(), and
ddi_getproplen(). Use
ddi_prop_get_int(9F) instead of
ddi_getprop()PARAMETERS
dev Device number associated with property or
DDI_DEV_T_ANY as
the
wildcard device number.
dip Pointer to a device info node.
prop_op Property operator.
flags Possible flag values are some combination of:
DDI_PROP_DONTPASS do not pass request to parent device
information node if property not found
DDI_PROP_CANSLEEP the routine may sleep while allocating
memory
DDI_PROP_NOTPROM do not look at PROM properties (ignored
on architectures that do not support
PROM properties)
name String containing the name of the property.
valuep If
prop_op is
PROP_LEN_AND_VAL_BUF, this should be a pointer
to the users buffer. If
prop_op is
PROP_LEN_AND_VAL_ALLOC, this should be the
address of a pointer.
lengthp On exit,
*lengthp will contain the property length. If
prop_op is
PROP_LEN_AND_VAL_BUF then before calling
ddi_prop_op(),
lengthp should point to an
int that contains
the length of callers buffer.
defvalue The value that
ddi_getprop() returns if the property is not
found.
DESCRIPTION
The
ddi_prop_op() 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
DDI_PROP_DONTPASS is set, then
ddi_prop_op() returns
DDI_PROP_NOT_FOUND. Otherwise, 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
DDI_PROP_UNDEFINED. 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
prop_op, as described below, and returns
DDI_PROP_SUCCESS. If a property cannot be found at all,
DDI_PROP_NOT_FOUND 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
DDI_DEV_T_ANY, the
wildcard dev, then
ddi_prop_op() 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 property search order which
is to first search software properties 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
prop_op argument. If
prop_op is
PROP_LEN, then
ddi_prop_op() just sets the callers length,
*lengthp, to
the property length and returns the value
DDI_PROP_SUCCESS to the caller.
The
valuep argument 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
prop_op is
PROP_LEN_AND_VAL_BUF, 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,
ddi_prop_op() 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
DDI_PROP_SUCCESS. If the named
property exists but the buffer supplied is too small to hold it, it
returns
DDI_PROP_BUF_TOO_SMALL. If
prop_op is
PROP_LEN_AND_VAL_ALLOC, and the property is found,
ddi_prop_op() sets
*lengthp to the property length. It then attempts to
allocate a buffer to return to the caller using the
kmem_alloc(9F) routine, so that memory can be later recycled using
kmem_free(9F). The
driver is expected to call
kmem_free() 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
DDI_PROP_SUCCESS. Otherwise,
it returns
DDI_PROP_NO_MEMORY. Note that the
flags argument may affect
the behavior of memory allocation in
ddi_prop_op(). In particular, if
DDI_PROP_CANSLEEP is set, then the routine will wait until memory is
available to copy the requested property.
The
ddi_getprop() function returns boolean and integer-size properties.
It is a convenience wrapper for
ddi_prop_op() with
prop_op set to
PROP_LEN_AND_VAL_BUF, and the buffer is provided by the wrapper. By
convention, this function returns a
1 for boolean (zero-length)
properties.
The
ddi_getlongprop() function returns arbitrary-size properties. It is a
convenience wrapper for
ddi_prop_op() with
prop_op set to
PROP_LEN_AND_VAL_ALLOC, so that the routine will allocate space to hold
the buffer that will be returned to the caller via
*valuep.
The
ddi_getlongprop_buf() function returns arbitrary-size properties. It
is a convenience wrapper for
ddi_prop_op() with
prop_op set to
PROP_LEN_AND_VAL_BUF so the user must supply a buffer.
The
ddi_getproplen() function returns the length of a given property. It
is a convenience wrapper for
ddi_prop_op() with
prop_op set to
PROP_LEN.
RETURN VALUES
The
ddi_prop_op(),
ddi_getlongprop(),
ddi_getlongprop_buf(), and
ddi_getproplen() functions return:
DDI_PROP_SUCCESS Property found and returned.
DDI_PROP_NOT_FOUND Property not found.
DDI_PROP_UNDEFINED Property already explicitly undefined.
DDI_PROP_NO_MEMORY Property found, but unable to allocate memory.
lengthp points to the correct property length.
DDI_PROP_BUF_TOO_SMALL Property found, but the supplied buffer is too
small.
lengthp points to the correct property
length.
The
ddi_getprop() function returns:
The value of the property or the value passed into the routine as
defvalue if the property is not found. By convention, the value of zero
length properties (boolean properties) are returned as the integer value
1.
CONTEXT
These functions can be called from user, interrupt, or kernel context,
provided
DDI_PROP_CANSLEEP is not set; if it is set, they cannot be
called from interrupt context.
ATTRIBUTES
See
attributes(7) for a description of the following attributes:
+----------------+----------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+----------------+----------------------------+
|Stability Level |
ddi_getlongprop(), |
| |
ddi_getlongprop_buf(), |
| |
ddi_getprop(), and |
| |
ddi_getproplen() functions |
| | are Obsolete |
+----------------+----------------------------+
SEE ALSO
attributes(7),
ddi_prop_create(9F),
ddi_prop_get_int(9F),
ddi_prop_lookup(9F),
kmem_alloc(9F),
kmem_free(9F) Writing Device Drivers January 16, 2006
DDI_PROP_OP(9F)