1ddi_prop_op(9F) Kernel Functions for Drivers ddi_prop_op(9F)
2
6 ddi_prop_op, ddi_getprop, ddi_getlongprop, ddi_getlongprop_buf,
7 ddi_getproplen - get property information for leaf device drivers
8
10 #include <sys/types.h>
11 #include <sys/ddi.h>
12 #include <sys/sunddi.h>
13 int ddi_prop_op(dev_t dev, dev_info_t *dip, ddi_prop_op_t prop_op,
17 int flags, char *name, caddr_t valuep, int *lengthp);
18 int ddi_getprop(dev_t dev, dev_info_t *dip, int flags, char *name,
21 int defvalue);
22 int ddi_getlongprop(dev_t dev, dev_info_t *dip, int flags, char *name,
25 caddr_t valuep, int *lengthp);
26 int ddi_getlongprop_buf(dev_t dev, dev_info_t *dip, int flags, char *name,
29 caddr_t valuep, int *lengthp);
30 int ddi_getproplen(dev_t dev, dev_info_t *dip, int flags, char *name,
33 int *lengthp);
34
37 Solaris DDI specific (Solaris DDI). The ddi_getlongprop(), ddi_getlong‐
38 prop_buf(), ddi_getprop(), and ddi_getproplen() functions are obsolete.
39 Use ddi_prop_lookup(9F) instead of ddi_getlongprop(), ddi_getlong‐
40 prop_buf(), and ddi_getproplen(). Use ddi_prop_get_int(9F) instead of
41 ddi_getprop()
42
44 dev Device number associated with property or DDI_DEV_T_ANY as
45 the wildcard device number.
46 dip Pointer to a device info node.
49 prop_op Property operator.
52 flags Possible flag values are some combination of:
55 DDI_PROP_DONTPASS do not pass request to parent device
57 information node if property not found
58 DDI_PROP_CANSLEEP the routine may sleep while allocating
61 memory
62 DDI_PROP_NOTPROM do not look at PROM properties
65 (ignored on architectures that do not
66 support PROM properties)
67 name String containing the name of the property.
71 valuep If prop_op is PROP_LEN_AND_VAL_BUF, this should be a
74 pointer to the users buffer. If prop_op is
75 PROP_LEN_AND_VAL_ALLOC, this should be the address of a
76 pointer.
77 lengthp On exit, *lengthp will contain the property length. If
80 prop_op is PROP_LEN_AND_VAL_BUF then before calling
81 ddi_prop_op(), lengthp should point to an int that contains
82 the length of callers buffer.
83 defvalue The value that ddi_getprop() returns if the property is not
86 found.
87
90 The ddi_prop_op() function gets arbitrary-size properties for leaf
91 devices. The routine searches the device's property list. If it does
92 not find the property at the device level, it examines the flags argu‐
93 ment, and if DDI_PROP_DONTPASS is set, then ddi_prop_op() returns
94 DDI_PROP_NOT_FOUND. Otherwise, it passes the request to the next level
95 of the device info tree. If it does find the property, but the property
96 has been explicitly undefined, it returns DDI_PROP_UNDEFINED. Otherwise
97 it returns either the property length, or both the length and value of
98 the property to the caller via the valuep and lengthp pointers, depend‐
99 ing on the value of prop_op, as described below, and returns
100 DDI_PROP_SUCCESS. If a property cannot be found at all,
101 DDI_PROP_NOT_FOUND is returned.
102 Usually, the dev argument should be set to the actual device number
105 that this property applies to. However, if the dev argument is
106 DDI_DEV_T_ANY, the wildcard dev, then ddi_prop_op() will match the
107 request based on name only (regardless of the actual dev the property
108 was created with). This property/dev match is done according to the
109 property search order which is to first search software properties cre‐
110 ated by the driver in last-in, first-out (LIFO) order, next search
111 software properties created by the system in LIFO order, then search
112 PROM properties if they exist in the system architecture.
113 Property operations are specified by the prop_op argument. If prop_op
116 is PROP_LEN, then ddi_prop_op() just sets the callers length, *lengthp,
117 to the property length and returns the value DDI_PROP_SUCCESS to the
118 caller. The valuep argument is not used in this case. Property lengths
119 are 0 for boolean properties, sizeof(int) for integer properties, and
120 size in bytes for long (variable size) properties.
121 If prop_op is PROP_LEN_AND_VAL_BUF, then valuep should be a pointer to
124 a user-supplied buffer whose length should be given in *lengthp by the
125 caller. If the requested property exists, ddi_prop_op() first sets
126 *lengthp to the property length. It then examines the size of the buf‐
127 fer supplied by the caller, and if it is large enough, copies the prop‐
128 erty value into that buffer, and returns DDI_PROP_SUCCESS. If the named
129 property exists but the buffer supplied is too small to hold it, it
130 returns DDI_PROP_BUF_TOO_SMALL.
131 If prop_op is PROP_LEN_AND_VAL_ALLOC, and the property is found,
134 ddi_prop_op() sets *lengthp to the property length. It then attempts to
135 allocate a buffer to return to the caller using the kmem_alloc(9F) rou‐
136 tine, so that memory can be later recycled using kmem_free(9F). The
137 driver is expected to call kmem_free() with the returned address and
138 size when it is done using the allocated buffer. If the allocation is
139 successful, it sets *valuep to point to the allocated buffer, copies
140 the property value into the buffer and returns DDI_PROP_SUCCESS. Other‐
141 wise, it returns DDI_PROP_NO_MEMORY. Note that the flags argument may
142 affect the behavior of memory allocation in ddi_prop_op(). In particu‐
143 lar, if DDI_PROP_CANSLEEP is set, then the routine will wait until mem‐
144 ory is available to copy the requested property.
145 The ddi_getprop() function returns boolean and integer-size properties.
148 It is a convenience wrapper for ddi_prop_op() with prop_op set to
149 PROP_LEN_AND_VAL_BUF, and the buffer is provided by the wrapper. By
150 convention, this function returns a 1 for boolean (zero-length) proper‐
151 ties.
152 The ddi_getlongprop() function returns arbitrary-size properties. It is
155 a convenience wrapper for ddi_prop_op() with prop_op set to
156 PROP_LEN_AND_VAL_ALLOC, so that the routine will allocate space to hold
157 the buffer that will be returned to the caller via *valuep.
158 The ddi_getlongprop_buf() function returns arbitrary-size properties.
161 It is a convenience wrapper for ddi_prop_op() with prop_op set to
162 PROP_LEN_AND_VAL_BUF so the user must supply a buffer.
163 The ddi_getproplen() function returns the length of a given property.
166 It is a convenience wrapper for ddi_prop_op() with prop_op set to
167 PROP_LEN.
168
170 The ddi_prop_op(), ddi_getlongprop(), ddi_getlongprop_buf(), and
171 ddi_getproplen() functions return:
172 DDI_PROP_SUCCESS Property found and returned.
174 DDI_PROP_NOT_FOUND Property not found.
177 DDI_PROP_UNDEFINED Property already explicitly undefined.
180 DDI_PROP_NO_MEMORY Property found, but unable to allocate mem‐
183 ory. lengthp points to the correct property
184 length.
185 DDI_PROP_BUF_TOO_SMALL Property found, but the supplied buffer is
188 too small. lengthp points to the correct
189 property length.
190 The ddi_getprop() function returns:
194 The value of the property or the value passed into the routine as def‐
197 value if the property is not found. By convention, the value of zero
198 length properties (boolean properties) are returned as the integer
199 value 1.
200
202 These functions can be called from user, interrupt, or kernel context,
203 provided DDI_PROP_CANSLEEP is not set; if it is set, they cannot be
204 called from interrupt context.
205
207 See attributes(5) for a description of the following attributes:
208 ┌───────────────────────────┬───────────────────────────────┐
213 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
214 ├───────────────────────────┼───────────────────────────────┤
215 │Stability Level │ddi_getlongprop(), ddi_get‐ │
216 │ │longprop_buf(), ddi_getprop(), │
217 │ │and ddi_getproplen() functions │
218 │ │are Obsolete │
219 └───────────────────────────┴───────────────────────────────┘
220
222 attributes(5), ddi_prop_create(9F), ddi_prop_get_int(9F),
223 ddi_prop_lookup(9F), kmem_alloc(9F), kmem_free(9F)
224 Writing Device Drivers
227SunOS 5.11 16 Jan 2006 ddi_prop_op(9F)