ddi_prop_lookup_int64_array(9f)

1ddi_prop_lookup(9F)      Kernel Functions for Drivers      ddi_prop_lookup(9F)
2
3
4

NAME

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

SYNOPSIS

12       #include <sys/ddi.h>
13       #include <sys/sunddi.h>
14
15
16
17       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
20
21       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
24
25       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
28
29       int ddi_prop_lookup_string(dev_t match_dev, dev_info_t *dip, uint_t flags,
30            char *name, char **datap);
31
32
33       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
36
37       void ddi_prop_free(void *data);
38
39

PARAMETERS

41       match_dev     Device number associated with property or DDI_DEV_T_ANY.
42
43
44       dip           Pointer to the device info node of device whose  property
45                     list should be searched.
46
47
48       flags         Possible flag values are some combination of:
49
50                     DDI_PROP_DONTPASS    Do not pass request to parent device
51                                          information node if the property  is
52                                          not found.
53
54
55                     DDI_PROP_NOTPROM     Do   not  look  at  PROM  properties
56                                          (ignored on platforms  that  do  not
57                                          support PROM properties).
58
59
60
61       name          String containing the name of the property.
62
63
64       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
70
71       datap
72                     ddi_prop_lookup_int_array()
73
74                         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
78
79                     ddi_prop_lookup_int64_array()
80
81                         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
85
86                     ddi_prop_lookup_string_array()
87
88                         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
95
96                     ddi_prop_lookup_string()
97
98                         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
102
103                     ddi_prop_lookup_byte_array()
104
105                         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
109
110

INTERFACE LEVEL

112       Solaris DDI specific (Solaris DDI).
113

DESCRIPTION

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
120           1.     Search software properties created by the driver.
121
122           2.     Search  the  software  properties  created by the system (or
123                  nexus nodes in the device info tree).
124
125           3.     Search the driver global properties list.
126
127           4.     If DDI_PROP_NOTPROM is not set, search the  PROM  properties
128                  (if they exist).
129
130           5.     If  DDI_PROP_DONTPASS  is  not set, pass this request to the
131                  parent device information node.
132
133           6.     Return DDI_PROP_NOT_FOUND.
134
135
136       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
145
146       name must always be set to the name of the property being looked up.
147
148
149       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
160
161       All of the property look up  routines  may  block  to  allocate  memory
162       needed to hold the value of the property.
163
164
165       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
173       ddi_prop_lookup_int_array()
174
175           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
181
182       ddi_prop_lookup_int64_array()
183
184           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
191
192       ddi_prop_lookup_string_array()
193
194           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
201
202       ddi_prop_lookup_string()
203
204           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
209
210       ddi_prop_lookup_byte_array()
211
212           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
217
218       ddi_prop_free()
219
220           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
225

RETURN VALUES

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
232       DDI_PROP_SUCCESS          Upon success.
233
234
235       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
239
240       DDI_PROP_NOT_FOUND        Property not found.
241
242
243       DDI_PROP_UNDEFINED        Property    explicitly   not   defined   (see
244                                 ddi_prop_undefine(9F)).
245
246
247       DDI_PROP_CANNOT_DECODE    The value of the property cannot be decoded.
248
249

CONTEXT

251       These functions can be called from user or kernel context.
252

EXAMPLES

254       Example 1 Using ddi_prop_lookup_int_array()
255
256
257       The     following     example     demonstrates     the      use      of
258       ddi_prop_lookup_int_array().
259
260
261
262         int  *options;
263         int  noptions;
264
265         /*
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
276              /*
277               * Free the memory allocated for the property data
278               */
279              ddi_prop_free(options);
280         }
281
282