1ddi_prop_lookup(9F) Kernel Functions for Drivers ddi_prop_lookup(9F)
2
6 ddi_prop_lookup, ddi_prop_lookup_int_array,
7 ddi_prop_lookup_int64_array, ddi_prop_lookup_string_array,
8 ddi_prop_lookup_string, ddi_prop_lookup_byte_array, ddi_prop_free -
9 look up property information
10
12 #include <sys/ddi.h>
13 #include <sys/sunddi.h>
14 int ddi_prop_lookup_int_array(dev_t match_dev, dev_info_t *dip,
18 uint_t flags, char *name, int **datap, uint_t *nelementsp);
19 int ddi_prop_lookup_int64_array(dev_t match_dev, dev_info_t *dip,
22 uint_t flags, char *name, int64_t **datap, uint_t *nelementsp);
23 int ddi_prop_lookup_string_array(dev_t match_dev, dev_info_t *dip,
26 uint_t flags, char *name, char ***datap, uint_t *nelementsp);
27 int ddi_prop_lookup_string(dev_t match_dev, dev_info_t *dip, uint_t flags,
30 char *name, char **datap);
31 int ddi_prop_lookup_byte_array(dev_t match_dev, dev_info_t *dip,
34 uint_t flags, char *name, uchar_t **datap, uint_t *nelementsp);
35 void ddi_prop_free(void *data);
38
41 match_dev Device number associated with property or DDI_DEV_T_ANY.
42 dip Pointer to the device info node of device whose property
45 list should be searched.
46 flags Possible flag values are some combination of:
49 DDI_PROP_DONTPASS Do not pass request to parent device
51 information node if the property is
52 not found.
53 DDI_PROP_NOTPROM Do not look at PROM properties
56 (ignored on platforms that do not
57 support PROM properties).
58 name String containing the name of the property.
62 nelementsp The address of an unsigned integer which, upon successful
65 return, will contain the number of elements accounted for
66 in the memory pointed at by datap. The elements are
67 either integers, strings or bytes depending on the inter‐
68 face used.
69 datap
72 ddi_prop_lookup_int_array()
73 The address of a pointer to an array of integers
75 which, upon successful return, will point to memory
76 containing the integer array property value.
77 ddi_prop_lookup_int64_array()
80 The address of a pointer to an array of 64-bit inte‐
82 gers which, upon successful return, will point to
83 memory containing the integer array property value.
84 ddi_prop_lookup_string_array()
87 The address of a pointer to an array of strings
89 which, upon successful return, will point to memory
90 containing the array of strings. The array of strings
91 is formatted as an array of pointers to NULL termi‐
92 nated strings, much like the argv argument to
93 execve(2).
94 ddi_prop_lookup_string()
97 The address of a pointer to a string which, upon suc‐
99 cessful return, will point to memory containing the
100 NULL terminated string value of the property.
101 ddi_prop_lookup_byte_array()
104 The address of pointer to an array of bytes which,
106 upon successful return, will point to memory contain‐
107 ing the byte array value of the property.
108
112 Solaris DDI specific (Solaris DDI).
113
115 The property look up routines search for and, if found, return the
116 value of a given property. Properties are searched for based on the
117 dip, name, match_dev, and the type of the data (integer, string, or
118 byte). The property search order is as follows:
119 1. Search software properties created by the driver.
121 2. Search the software properties created by the system (or
123 nexus nodes in the device info tree).
124 3. Search the driver global properties list.
126 4. If DDI_PROP_NOTPROM is not set, search the PROM properties
128 (if they exist).
129 5. If DDI_PROP_DONTPASS is not set, pass this request to the
131 parent device information node.
132 6. Return DDI_PROP_NOT_FOUND.
134 Usually, the match_dev argument should be set to the actual device num‐
137 ber that this property is associated with. However, if the match_dev
138 argument is DDI_DEV_T_ANY, the property look up routines will match the
139 request regardless of the actual match_dev the property was created
140 with. If a property was created with match_dev set to DDI_DEV_T_NONE,
141 then the only way to look up this property is with a match_dev set to
142 DDI_DEV_T_ANY. PROM properties are always created with match_dev set to
143 DDI_DEV_T_NONE.
144 name must always be set to the name of the property being looked up.
147 For the routines ddi_prop_lookup_int_array(),
150 ddi_prop_lookup_int64_array(), ddi_prop_lookup_string_array(),
151 ddi_prop_lookup_string(), and ddi_prop_lookup_byte_array(), datap is
152 the address of a pointer which, upon successful return, will point to
153 memory containing the value of the property. In each case *datap points
154 to a different type of property value. See the individual descriptions
155 of the routines below for details on the different return values. nele‐
156 mentsp is the address of an unsigned integer which, upon successful
157 return, will contain the number of integer, string or byte elements
158 accounted for in the memory pointed at by *datap.
159 All of the property look up routines may block to allocate memory
162 needed to hold the value of the property.
163 When a driver has obtained a property with any look up routine and is
166 finished with that property, it must be freed by calling
167 ddi_prop_free(). ddi_prop_free() must be called with the address of the
168 allocated property. For instance, if one called
169 ddi_prop_lookup_int_array() with datap set to the address of a pointer
170 to an integer, &my_int_ptr, then the companion free call would be
171 ddi_prop_free(my_int_ptr).
172 ddi_prop_lookup_int_array()
174 This routine searches for and returns an array of integer property
176 values. An array of integers is defined to *nelementsp number of 4
177 byte long integer elements. datap should be set to the address of a
178 pointer to an array of integers which, upon successful return, will
179 point to memory containing the integer array value of the property.
180 ddi_prop_lookup_int64_array()
183 This routine searches for and returns an array of 64-bit integer
185 property values. The array is defined to be *nelementsp number of
186 int64_t elements. datap should be set to the address of a pointer
187 to an array of int64_t's which, upon successful return, will point
188 to memory containing the integer array value of the property. This
189 routine will not search the PROM for 64-bit property values.
190 ddi_prop_lookup_string_array()
193 This routine searches for and returns a property that is an array
195 of strings. datap should be set to address of a pointer to an array
196 of strings which, upon successful return, will point to memory con‐
197 taining the array of strings. The array of strings is formatted as
198 an array of pointers to null-terminated strings, much like the argv
199 argument to execve(2).
200 ddi_prop_lookup_string()
203 This routine searches for and returns a property that is a null-
205 terminated string. datap should be set to the address of a pointer
206 to string which, upon successful return, will point to memory con‐
207 taining the string value of the property.
208 ddi_prop_lookup_byte_array()
211 This routine searches for and returns a property that is an array
213 of bytes. datap should be set to the address of a pointer to an
214 array of bytes which, upon successful return, will point to memory
215 containing the byte array value of the property.
216 ddi_prop_free()
219 Frees the resources associated with a property previously allocated
221 using ddi_prop_lookup_int_array(), ddi_prop_lookup_int64_array(),
222 ddi_prop_lookup_string_array(), ddi_prop_lookup_string(), or
223 ddi_prop_lookup_byte_array().
224
227 The functions ddi_prop_lookup_int_array(),
228 ddi_prop_lookup_int64_array(), ddi_prop_lookup_string_array(),
229 ddi_prop_lookup_string(), and ddi_prop_lookup_byte_array() return the
230 following values:
231 DDI_PROP_SUCCESS Upon success.
233 DDI_PROP_INVAL_ARG If an attempt is made to look up a property
236 with match_dev equal to DDI_DEV_T_NONE, name
237 is NULL or name is the null string.
238 DDI_PROP_NOT_FOUND Property not found.
241 DDI_PROP_UNDEFINED Property explicitly not defined (see
244 ddi_prop_undefine(9F)).
245 DDI_PROP_CANNOT_DECODE The value of the property cannot be decoded.
248
251 These functions can be called from user or kernel context.
252
254 Example 1 Using ddi_prop_lookup_int_array()
255 The following example demonstrates the use of
258 ddi_prop_lookup_int_array().
259 int *options;
263 int noptions;
264 /*
266 * Get the data associated with the integer "options" property
267 * array, along with the number of option integers
268 */
269 if (ddi_prop_lookup_int_array(DDI_DEV_T_ANY, xx_dip, 0,
270 "options", &options, &noptions) == DDI_PROP_SUCCESS) {
271 /*
272 * Do "our thing" with the options data from the property
273 */
274 xx_process_options(options, noptions);
275 /*
277 * Free the memory allocated for the property data
278 */
279 ddi_prop_free(options);
280 }
281
284 execve(2), ddi_prop_exists(9F), ddi_prop_get_int(9F),
285 ddi_prop_remove(9F), ddi_prop_undefine(9F), ddi_prop_update(9F)
286 Writing Device Drivers
289SunOS 5.11 11 Apr 2001 ddi_prop_lookup(9F)