'\" te .\" Copyright (c) 2006, Sun Microsystems, Inc. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH DDI_PROP_OP 9F "Jan 16, 2006" .SH NAME ddi_prop_op, ddi_getprop, ddi_getlongprop, ddi_getlongprop_buf, ddi_getproplen \- get property information for leaf device drivers .SH SYNOPSIS .nf #include #include #include \fBint\fR \fBddi_prop_op\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBddi_prop_op_t\fR \fIprop_op\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBcaddr_t\fR \fIvaluep\fR, \fBint *\fR\fIlengthp\fR); .fi .LP .nf \fBint\fR \fBddi_getprop\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBint\fR \fIdefvalue\fR); .fi .LP .nf \fBint\fR \fBddi_getlongprop\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBcaddr_t\fR \fIvaluep\fR, \fBint *\fR\fIlengthp\fR); .fi .LP .nf \fBint\fR \fBddi_getlongprop_buf\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBcaddr_t\fR \fIvaluep\fR, \fBint *\fR\fIlengthp\fR); .fi .LP .nf \fBint\fR \fBddi_getproplen\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBint *\fR\fIlengthp\fR); .fi .SH INTERFACE LEVEL illumos DDI specific (illumos DDI). The \fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR, \fBddi_getprop()\fR, and \fBddi_getproplen()\fR functions are obsolete. Use \fBddi_prop_lookup\fR(9F) instead of \fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR, and \fBddi_getproplen()\fR. Use \fBddi_prop_get_int\fR(9F) instead of \fBddi_getprop()\fR .SH PARAMETERS .ne 2 .na \fB\fIdev\fR\fR .ad .RS 12n Device number associated with property or \fBDDI_DEV_T_ANY\fR as the \fIwildcard\fR device number. .RE .sp .ne 2 .na \fB\fIdip\fR\fR .ad .RS 12n Pointer to a device info node. .RE .sp .ne 2 .na \fB\fIprop_op\fR\fR .ad .RS 12n Property operator. .RE .sp .ne 2 .na \fB\fIflags\fR\fR .ad .RS 12n Possible flag values are some combination of: .sp .ne 2 .na \fB\fBDDI_PROP_DONTPASS\fR\fR .ad .RS 21n do not pass request to parent device information node if property not found .RE .sp .ne 2 .na \fB\fBDDI_PROP_CANSLEEP\fR\fR .ad .RS 21n the routine may sleep while allocating memory .RE .sp .ne 2 .na \fB\fBDDI_PROP_NOTPROM\fR\fR .ad .RS 21n do not look at PROM properties (ignored on architectures that do not support PROM properties) .RE .RE .sp .ne 2 .na \fB\fIname\fR\fR .ad .RS 12n String containing the name of the property. .RE .sp .ne 2 .na \fB\fIvaluep\fR\fR .ad .RS 12n If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_BUF\fR, this should be a pointer to the users buffer. If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_ALLOC,\fR this should be the \fIaddress\fR of a pointer. .RE .sp .ne 2 .na \fB\fIlengthp\fR\fR .ad .RS 12n On exit, \fI*lengthp\fR will contain the property length. If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_BUF\fR then before calling \fBddi_prop_op()\fR, \fIlengthp\fR should point to an \fBint\fR that contains the length of callers buffer. .RE .sp .ne 2 .na \fB\fIdefvalue\fR\fR .ad .RS 12n The value that \fBddi_getprop()\fR returns if the property is not found. .RE .SH DESCRIPTION The \fBddi_prop_op()\fR 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 \fIflags\fR argument, and if \fBDDI_PROP_DONTPASS\fR is set, then \fBddi_prop_op()\fR returns \fBDDI_PROP_NOT_FOUND.\fR 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 \fBDDI_PROP_UNDEFINED.\fR Otherwise it returns either the property length, or both the length and value of the property to the caller via the \fIvaluep\fR and \fIlengthp\fR pointers, depending on the value of \fIprop_op\fR, as described below, and returns \fBDDI_PROP_SUCCESS.\fR If a property cannot be found at all, \fBDDI_PROP_NOT_FOUND\fR is returned. .sp .LP Usually, the \fIdev\fR argument should be set to the actual device number that this property applies to. However, if the \fIdev\fR argument is \fBDDI_DEV_T_ANY,\fR the \fIwildcard dev\fR, then \fBddi_prop_op()\fR will match the request based on \fIname\fR only (regardless of the actual \fIdev\fR 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 \fIlast-in, first-out\fR (LIFO) order, next search software properties created by the \fIsystem\fR in LIFO order, then search PROM properties if they exist in the system architecture. .sp .LP Property operations are specified by the \fIprop_op\fR argument. If \fIprop_op\fR is \fBPROP_LEN,\fR then \fBddi_prop_op()\fR just sets the callers length, \fI*lengthp,\fR to the property length and returns the value \fBDDI_PROP_SUCCESS\fR to the caller. The \fIvaluep\fR argument is not used in this case. Property lengths are \fB0\fR for boolean properties, \fBsizeof\|(int)\fR for integer properties, and size in bytes for long (variable size) properties. .sp .LP If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_BUF,\fR then \fIvaluep\fR should be a pointer to a user-supplied buffer whose length should be given in \fI*lengthp\fR by the caller. If the requested property exists, \fBddi_prop_op()\fR first sets \fI*lengthp\fR 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 \fBDDI_PROP_SUCCESS.\fR If the named property exists but the buffer supplied is too small to hold it, it returns \fBDDI_PROP_BUF_TOO_SMALL.\fR .sp .LP If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_ALLOC,\fR and the property is found, \fBddi_prop_op()\fR sets \fI*lengthp\fR to the property length. It then attempts to allocate a buffer to return to the caller using the \fBkmem_alloc\fR(9F) routine, so that memory can be later recycled using \fBkmem_free\fR(9F). The driver is expected to call \fBkmem_free()\fR with the returned address and size when it is done using the allocated buffer. If the allocation is successful, it sets \fI*valuep\fR to point to the allocated buffer, copies the property value into the buffer and returns \fBDDI_PROP_SUCCESS.\fR Otherwise, it returns \fBDDI_PROP_NO_MEMORY.\fR Note that the \fIflags\fR argument may affect the behavior of memory allocation in \fBddi_prop_op()\fR. In particular, if \fBDDI_PROP_CANSLEEP\fR is set, then the routine will wait until memory is available to copy the requested property. .sp .LP The \fBddi_getprop()\fR function returns boolean and integer-size properties. It is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to \fBPROP_LEN_AND_VAL_BUF\fR, and the buffer is provided by the wrapper. By convention, this function returns a \fB1\fR for boolean (zero-length) properties. .sp .LP The \fBddi_getlongprop()\fR function returns arbitrary-size properties. It is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to \fBPROP_LEN_AND_VAL_ALLOC,\fR so that the routine will allocate space to hold the buffer that will be returned to the caller via \fI*valuep\fR. .sp .LP The \fBddi_getlongprop_buf()\fR function returns arbitrary-size properties. It is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to \fBPROP_LEN_AND_VAL_BUF\fR so the user must supply a buffer. .sp .LP The \fBddi_getproplen()\fR function returns the length of a given property. It is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to \fBPROP_LEN\fR. .SH RETURN VALUES The \fBddi_prop_op()\fR, \fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR, and \fBddi_getproplen()\fR functions return: .sp .ne 2 .na \fB\fBDDI_PROP_SUCCESS\fR\fR .ad .RS 26n Property found and returned. .RE .sp .ne 2 .na \fB\fBDDI_PROP_NOT_FOUND\fR\fR .ad .RS 26n Property not found. .RE .sp .ne 2 .na \fB\fBDDI_PROP_UNDEFINED\fR\fR .ad .RS 26n Property already explicitly undefined. .RE .sp .ne 2 .na \fB\fBDDI_PROP_NO_MEMORY\fR\fR .ad .RS 26n Property found, but unable to allocate memory. \fIlengthp\fR points to the correct property length. .RE .sp .ne 2 .na \fB\fBDDI_PROP_BUF_TOO_SMALL\fR\fR .ad .RS 26n Property found, but the supplied buffer is too small. \fIlengthp\fR points to the correct property length. .RE .sp .LP The \fBddi_getprop()\fR function returns: .sp .LP The value of the property or the value passed into the routine as \fIdefvalue\fR if the property is not found. By convention, the value of zero length properties (boolean properties) are returned as the integer value 1. .SH CONTEXT These functions can be called from user, interrupt, or kernel context, provided \fBDDI_PROP_CANSLEEP\fR is not set; if it is set, they cannot be called from interrupt context. .SH ATTRIBUTES See \fBattributes\fR(5) for a description of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Stability Level T{ \fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR, \fBddi_getprop()\fR, and \fBddi_getproplen()\fR functions are Obsolete T} .TE .SH SEE ALSO \fBattributes\fR(5), \fBddi_prop_create\fR(9F), \fBddi_prop_get_int\fR(9F), \fBddi_prop_lookup\fR(9F), \fBkmem_alloc\fR(9F), \fBkmem_free\fR(9F) .sp .LP \fIWriting Device Drivers\fR