|DDI_PROP_OP(9F)||Kernel Functions for Drivers||DDI_PROP_OP(9F)|
#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);
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.
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.
|ATTRIBUTE TYPE||ATTRIBUTE VALUE|
|Stability Level||ddi_getlongprop(), ddi_getlongprop_buf(), ddi_getprop(), and ddi_getproplen() functions are Obsolete|
Writing Device Drivers
|January 16, 2006||OmniOS|