| blob | 64b7b3958ed51a1d3fa148c475d807c32511b7bf |
1 '\" te
2 .\" Copyright (c) 2006, Sun Microsystems, Inc.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH DDI_PROP_OP 9F "Jan 16, 2006"
7 .SH NAME
8 ddi_prop_op, ddi_getprop, ddi_getlongprop, ddi_getlongprop_buf, ddi_getproplen
9 \- get property information for leaf device drivers
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <sys/types.h>
14 #include <sys/ddi.h>
15 #include <sys/sunddi.h>
19 \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,
20 \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBcaddr_t\fR \fIvaluep\fR, \fBint *\fR\fIlengthp\fR);
21 .fi
23 .LP
24 .nf
25 \fBint\fR \fBddi_getprop\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR,
26 \fBint\fR \fIdefvalue\fR);
27 .fi
29 .LP
30 .nf
31 \fBint\fR \fBddi_getlongprop\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR,
32 \fBcaddr_t\fR \fIvaluep\fR, \fBint *\fR\fIlengthp\fR);
33 .fi
35 .LP
36 .nf
37 \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,
38 \fBcaddr_t\fR \fIvaluep\fR, \fBint *\fR\fIlengthp\fR);
39 .fi
41 .LP
42 .nf
43 \fBint\fR \fBddi_getproplen\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR,
44 \fBint *\fR\fIlengthp\fR);
45 .fi
47 .SH INTERFACE LEVEL
48 .sp
49 .LP
50 Solaris DDI specific (Solaris DDI). The \fBddi_getlongprop()\fR,
51 \fBddi_getlongprop_buf()\fR, \fBddi_getprop()\fR, and \fBddi_getproplen()\fR
52 functions are obsolete. Use \fBddi_prop_lookup\fR(9F) instead of
53 \fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR, and
54 \fBddi_getproplen()\fR. Use \fBddi_prop_get_int\fR(9F) instead of
55 \fBddi_getprop()\fR
56 .SH PARAMETERS
57 .sp
58 .ne 2
59 .na
60 \fB\fIdev\fR\fR
61 .ad
62 .RS 12n
63 Device number associated with property or \fBDDI_DEV_T_ANY\fR as the
64 \fIwildcard\fR device number.
65 .RE
67 .sp
68 .ne 2
69 .na
70 \fB\fIdip\fR\fR
71 .ad
72 .RS 12n
73 Pointer to a device info node.
74 .RE
76 .sp
77 .ne 2
78 .na
79 \fB\fIprop_op\fR\fR
80 .ad
81 .RS 12n
82 Property operator.
83 .RE
85 .sp
86 .ne 2
87 .na
88 \fB\fIflags\fR\fR
89 .ad
90 .RS 12n
91 Possible flag values are some combination of:
92 .sp
93 .ne 2
94 .na
95 \fB\fBDDI_PROP_DONTPASS\fR\fR
96 .ad
97 .RS 21n
98 do not pass request to parent device information node if property not found
99 .RE
101 .sp
102 .ne 2
103 .na
104 \fB\fBDDI_PROP_CANSLEEP\fR\fR
105 .ad
106 .RS 21n
107 the routine may sleep while allocating memory
108 .RE
110 .sp
111 .ne 2
112 .na
113 \fB\fBDDI_PROP_NOTPROM\fR\fR
114 .ad
115 .RS 21n
116 do not look at PROM properties (ignored on architectures that do not support
117 PROM properties)
118 .RE
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fIname\fR\fR
126 .ad
127 .RS 12n
128 String containing the name of the property.
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB\fIvaluep\fR\fR
135 .ad
136 .RS 12n
137 If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_BUF\fR, this should be a pointer to the
138 users buffer. If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_ALLOC,\fR this should be
139 the \fIaddress\fR of a pointer.
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fB\fIlengthp\fR\fR
146 .ad
147 .RS 12n
148 On exit, \fI*lengthp\fR will contain the property length. If \fIprop_op\fR is
149 \fBPROP_LEN_AND_VAL_BUF\fR then before calling \fBddi_prop_op()\fR,
150 \fIlengthp\fR should point to an \fBint\fR that contains the length of callers
151 buffer.
152 .RE
154 .sp
155 .ne 2
156 .na
157 \fB\fIdefvalue\fR\fR
158 .ad
159 .RS 12n
160 The value that \fBddi_getprop()\fR returns if the property is not found.
161 .RE
163 .SH DESCRIPTION
164 .sp
165 .LP
166 The \fBddi_prop_op()\fR function gets arbitrary-size properties for leaf
167 devices. The routine searches the device's property list. If it does not find
168 the property at the device level, it examines the \fIflags\fR argument, and if
169 \fBDDI_PROP_DONTPASS\fR is set, then \fBddi_prop_op()\fR returns
170 \fBDDI_PROP_NOT_FOUND.\fR Otherwise, it passes the request to the next level of
171 the device info tree. If it does find the property, but the property has been
172 explicitly undefined, it returns \fBDDI_PROP_UNDEFINED.\fR Otherwise it returns
173 either the property length, or both the length and value of the property to the
174 caller via the \fIvaluep\fR and \fIlengthp\fR pointers, depending on the value
175 of \fIprop_op\fR, as described below, and returns \fBDDI_PROP_SUCCESS.\fR If a
176 property cannot be found at all, \fBDDI_PROP_NOT_FOUND\fR is returned.
177 .sp
178 .LP
179 Usually, the \fIdev\fR argument should be set to the actual device number that
180 this property applies to. However, if the \fIdev\fR argument is
181 \fBDDI_DEV_T_ANY,\fR the \fIwildcard dev\fR, then \fBddi_prop_op()\fR will
182 match the request based on \fIname\fR only (regardless of the actual \fIdev\fR
183 the property was created with). This property/dev match is done according to
184 the property search order which is to first search software properties created
185 by the driver in \fIlast-in, first-out\fR (LIFO) order, next search software
186 properties created by the \fIsystem\fR in LIFO order, then search PROM
187 properties if they exist in the system architecture.
188 .sp
189 .LP
190 Property operations are specified by the \fIprop_op\fR argument. If
191 \fIprop_op\fR is \fBPROP_LEN,\fR then \fBddi_prop_op()\fR just sets the callers
192 length, \fI*lengthp,\fR to the property length and returns the value
193 \fBDDI_PROP_SUCCESS\fR to the caller. The \fIvaluep\fR argument is not used in
194 this case. Property lengths are \fB0\fR for boolean properties,
195 \fBsizeof\|(int)\fR for integer properties, and size in bytes for long
196 (variable size) properties.
197 .sp
198 .LP
199 If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_BUF,\fR then \fIvaluep\fR should be a
200 pointer to a user-supplied buffer whose length should be given in
201 \fI*lengthp\fR by the caller. If the requested property exists,
202 \fBddi_prop_op()\fR first sets \fI*lengthp\fR to the property length. It then
203 examines the size of the buffer supplied by the caller, and if it is large
204 enough, copies the property value into that buffer, and returns
205 \fBDDI_PROP_SUCCESS.\fR If the named property exists but the buffer supplied is
206 too small to hold it, it returns \fBDDI_PROP_BUF_TOO_SMALL.\fR
207 .sp
208 .LP
209 If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_ALLOC,\fR and the property is found,
210 \fBddi_prop_op()\fR sets \fI*lengthp\fR to the property length. It then
211 attempts to allocate a buffer to return to the caller using the
212 \fBkmem_alloc\fR(9F) routine, so that memory can be later recycled using
213 \fBkmem_free\fR(9F). The driver is expected to call \fBkmem_free()\fR with the
214 returned address and size when it is done using the allocated buffer. If the
215 allocation is successful, it sets \fI*valuep\fR to point to the allocated
216 buffer, copies the property value into the buffer and returns
217 \fBDDI_PROP_SUCCESS.\fR Otherwise, it returns \fBDDI_PROP_NO_MEMORY.\fR Note
218 that the \fIflags\fR argument may affect the behavior of memory allocation in
219 \fBddi_prop_op()\fR. In particular, if \fBDDI_PROP_CANSLEEP\fR is set, then the
220 routine will wait until memory is available to copy the requested property.
221 .sp
222 .LP
223 The \fBddi_getprop()\fR function returns boolean and integer-size properties.
224 It is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to
225 \fBPROP_LEN_AND_VAL_BUF\fR, and the buffer is provided by the wrapper. By
226 convention, this function returns a \fB1\fR for boolean (zero-length)
227 properties.
228 .sp
229 .LP
230 The \fBddi_getlongprop()\fR function returns arbitrary-size properties. It is a
231 convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to
232 \fBPROP_LEN_AND_VAL_ALLOC,\fR so that the routine will allocate space to hold
233 the buffer that will be returned to the caller via \fI*valuep\fR.
234 .sp
235 .LP
236 The \fBddi_getlongprop_buf()\fR function returns arbitrary-size properties. It
237 is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to
238 \fBPROP_LEN_AND_VAL_BUF\fR so the user must supply a buffer.
239 .sp
240 .LP
241 The \fBddi_getproplen()\fR function returns the length of a given property. It
242 is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to
243 \fBPROP_LEN\fR.
244 .SH RETURN VALUES
245 .sp
246 .LP
247 The \fBddi_prop_op()\fR, \fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR,
248 and \fBddi_getproplen()\fR functions return:
249 .sp
250 .ne 2
251 .na
252 \fB\fBDDI_PROP_SUCCESS\fR\fR
253 .ad
254 .RS 26n
255 Property found and returned.
256 .RE
258 .sp
259 .ne 2
260 .na
261 \fB\fBDDI_PROP_NOT_FOUND\fR\fR
262 .ad
263 .RS 26n
264 Property not found.
265 .RE
267 .sp
268 .ne 2
269 .na
270 \fB\fBDDI_PROP_UNDEFINED\fR\fR
271 .ad
272 .RS 26n
273 Property already explicitly undefined.
274 .RE
276 .sp
277 .ne 2
278 .na
279 \fB\fBDDI_PROP_NO_MEMORY\fR\fR
280 .ad
281 .RS 26n
282 Property found, but unable to allocate memory. \fIlengthp\fR points to the
283 correct property length.
284 .RE
286 .sp
287 .ne 2
288 .na
289 \fB\fBDDI_PROP_BUF_TOO_SMALL\fR\fR
290 .ad
291 .RS 26n
292 Property found, but the supplied buffer is too small. \fIlengthp\fR points to
293 the correct property length.
294 .RE
296 .sp
297 .LP
298 The \fBddi_getprop()\fR function returns:
299 .sp
300 .LP
301 The value of the property or the value passed into the routine as
302 \fIdefvalue\fR if the property is not found. By convention, the value of zero
303 length properties (boolean properties) are returned as the integer value 1.
304 .SH CONTEXT
305 .sp
306 .LP
307 These functions can be called from user, interrupt, or kernel context, provided
308 \fBDDI_PROP_CANSLEEP\fR is not set; if it is set, they cannot be called from
309 interrupt context.
310 .SH ATTRIBUTES
311 .sp
312 .LP
313 See \fBattributes\fR(5) for a description of the following attributes:
314 .sp
316 .sp
317 .TS
318 box;
319 c | c
320 l | l .
321 ATTRIBUTE TYPE ATTRIBUTE VALUE
322 _
323 Stability Level T{
324 \fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR, \fBddi_getprop()\fR, and \fBddi_getproplen()\fR functions are Obsolete
325 T}
326 .TE
328 .SH SEE ALSO
329 .sp
330 .LP
331 \fBattributes\fR(5), \fBddi_prop_create\fR(9F), \fBddi_prop_get_int\fR(9F),
332 \fBddi_prop_lookup\fR(9F), \fBkmem_alloc\fR(9F), \fBkmem_free\fR(9F)
333 .sp
334 .LP
335 \fIWriting Device Drivers\fR