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

NAME

6       ddi_prop_create, ddi_prop_modify, ddi_prop_remove, ddi_prop_remove_all,
7       ddi_prop_undefine - create,  remove,  or  modify  properties  for  leaf
8       device drivers
9

SYNOPSIS

11       #include <sys/conf.h>
12       #include <sys/ddi.h>
13       #include <sys/sunddi.h>
14
15       int ddi_prop_create(dev_t dev, dev_info_t *dip, int flags,
16            char *name, caddr_t valuep, int length);
17
18
19       int ddi_prop_undefine(dev_t dev, dev_info_t *dip, int flags,
20            char *name);
21
22
23       int ddi_prop_modify(dev_t dev, dev_info_t *dip, int flags,
24            char *name, caddr_t valuep, int length);
25
26
27       int ddi_prop_remove(dev_t dev, dev_info_t *dip, char *name);
28
29
30       void ddi_prop_remove_all(dev_info_t *dip);
31
32

INTERFACE LEVEL

34       Solaris   DDI   specific   (Solaris  DDI).  The  ddi_prop_create()  and
35       ddi_prop_modify()  functions  are  obsolete.  Use   ddi_prop_update(9F)
36       instead of these functions.
37

PARAMETERS

39       ddi_prop_create()
40
41       dev       dev_t of the device.
42
43
44       dip       dev_info_t pointer of the device.
45
46
47       flags     flag   modifiers.   The   only   possible   flag   value   is
48                 DDI_PROP_CANSLEEP: Memory allocation may sleep.
49
50
51       name      name of property.
52
53
54       valuep    pointer to property value.
55
56
57       length    property length.
58
59
60
61       ddi_prop_undefine()
62
63       dev      dev_t of the device.
64
65
66       dip      dev_info_t pointer of the device.
67
68
69       flags    flag   modifiers.   The   only   possible   flag   value    is
70                DDI_PROP_CANSLEEP: Memory allocation may sleep.
71
72
73       name     name of property.
74
75
76
77       ddi_prop_modify()
78
79       dev       dev_t of the device.
80
81
82       dip       dev_info_t pointer of the device.
83
84
85       flags     flag   modifiers.   The   only   possible   flag   value   is
86                 DDI_PROP_CANSLEEP: Memory allocation may sleep.
87
88
89       name      name of property.
90
91
92       valuep    pointer to property value.
93
94
95       length    property length.
96
97
98
99       ddi_prop_remove()
100
101       dev     dev_t of the device.
102
103
104       dip     dev_info_t pointer of the device.
105
106
107       name    name of property.
108
109
110
111       ddi_prop_remove_all()
112
113       dip    dev_info_t pointer of the device.
114
115

DESCRIPTION

117       Device drivers have the ability to create and manage their own  proper‐
118       ties  as  well  as gain access to properties that the system creates on
119       behalf of the driver. A driver uses ddi_getproplen(9F) to query whether
120       or not a specific property exists.
121
122
123       Property  creation is done by creating a new property definition in the
124       driver's property list associated with dip.
125
126
127       Property definitions are stacked; they are added to  the  beginning  of
128       the  driver's  property list when created. Thus, when searched for, the
129       most recent matching property definition will be found  and  its  value
130       will be return to the caller.
131
132
133       The individual functions are described as follows:
134
135       ddi_prop_create()        ddi_prop_create()   adds  a  property  to  the
136                                device's property list. If the property is not
137                                associated  with  any  particular  dev  but is
138                                associated with the  physical  device  itself,
139                                then  the  argument  dev should be the special
140                                device DDI_DEV_T_NONE. If you do  not  have  a
141                                dev   for  your  device  (for  example  during
142                                attach(9E) time), you  can  create  one  using
143                                makedevice(9F)   with   a   major   number  of
144                                DDI_MAJOR_T_UNKNOWN.  ddi_prop_create()   will
145                                then make the correct dev for your device.
146
147                                For boolean properties, you must set length to
148                                0. For all other properties, the length  argu‐
149                                ment  must  be set to the number of bytes used
150                                by the data structure representing  the  prop‐
151                                erty being created.
152
153                                Note  that  creating a property involves allo‐
154                                cating memory for the property list, the prop‐
155                                erty  name  and  the  property value. If flags
156                                does    not     contain     DDI_PROP_CANSLEEP,
157                                ddi_prop_create()  returns  DDI_PROP_NO_MEMORY
158                                on memory allocation failure or  DDI_PROP_SUC‐
159                                CESS   if   the   allocation   succeeded.   If
160                                DDI_PROP_CANSLEEP  was  set,  the  caller  may
161                                sleep until memory becomes available.
162
163
164       ddi_prop_undefine()      ddi_prop_undefine() is a special case of prop‐
165                                erty creation where the value of the  property
166                                is  set  to  undefined.  This property has the
167                                effect of terminating a property search at the
168                                current devinfo node, rather than allowing the
169                                search  to  proceed  up  to  ancestor  devinfo
170                                nodes.  However,  ddi_prop_undefine() will not
171                                terminate     a      search      when      the
172                                ddi_prop_get_int(9F)   or  ddi_prop_lookup(9F)
173                                routines are used for lookup of  64-bit  prop‐
174                                erty value. See ddi_prop_op(9F).
175
176                                Note  that  undefining properties does involve
177                                memory allocation, and therefore,  is  subject
178                                to  the  same memory allocation constraints as
179                                ddi_prop_create().
180
181
182       ddi_prop_modify()        ddi_prop_modify() modifies the length and  the
183                                value  of  a  property.  If  ddi_prop_modify()
184                                finds the property in  the  driver's  property
185                                list,  allocates memory for the property value
186                                and returns DDI_PROP_SUCCESS. If the  property
187                                was    not   found,   the   function   returns
188                                DDI_PROP_NOT_FOUND.
189
190                                Note that modifying  properties  does  involve
191                                memory  allocation,  and therefore, is subject
192                                to the same memory allocation  constraints  as
193                                ddi_prop_create().
194
195
196       ddi_prop_remove()        ddi_prop_remove()  unlinks a property from the
197                                device's property list.  If  ddi_prop_remove()
198                                finds  the  property  (an  exact match of both
199                                nameand dev), it unlinks the  property,  frees
200                                its memory, and returns DDI_PROP_SUCCESS, oth‐
201                                erwise, it returns DDI_PROP_NOT_FOUND.
202
203
204       ddi_prop_remove_all()    ddi_prop_remove_all() removes  the  properties
205                                of all the dev_t's associated with the dip. It
206                                is called before unloading a driver.
207
208

RETURN VALUES

210       The ddi_prop_create() function returns the following values:
211
212       DDI_PROP_SUCCESS      On success.
213
214
215       DDI_PROP_NO_MEMORY    On memory allocation failure.
216
217
218       DDI_PROP_INVAL_ARG    If an attempt is made to create a  property  with
219                             dev  equal to DDI_DEV_T_ANY or if name is NULL or
220                             name is the NULL string.
221
222
223
224       The ddi_prop_ undefine() function returns the following values:
225
226       DDI_PROP_SUCCESS      On success.
227
228
229       DDI_PROP_NO_MEMORY    On memory allocation failure.
230
231
232       DDI_PROP_INVAL_ARG    If an attempt is made to create a  property  with
233                             dev  DDI_DEV_T_ANY  or if name is NULL or name is
234                             the NULL string.
235
236
237
238       The ddi_prop_modify() function returns the following values:
239
240       DDI_PROP_SUCCESS      On success.
241
242
243       DDI_PROP_NO_MEMORY    On memory allocation failure.
244
245
246       DDI_PROP_INVAL_ARG    If an attempt is made to create a  property  with
247                             dev  equal to DDI_DEV_T_ANY or if name is NULL or
248                             name is the NULL string.
249
250
251       DDI_PROP_NOT_FOUND    On property search failure.
252
253
254
255       The ddi_prop_remove() function returns the following values:
256
257       DDI_PROP_SUCCESS      On success.
258
259
260       DDI_PROP_INVAL_ARG    If an attempt is made to create a  property  with
261                             dev  equal to DDI_DEV_T_ANY or if name is NULL or
262                             name is the NULL string.
263
264
265       DDI_PROP_NOT_FOUND    On property search failure.
266
267

CONTEXT

269       If DDI_PROP_CANSLEEP is set, these functions can cannot be called  from
270       interrupt  context. Otherwise, they can be called from user, interrupt,
271       or kernel context.
272

EXAMPLES

274       Example 1 Creating a Property
275
276
277       The following example creates a property called nblocks for each parti‐
278       tion on a disk.
279
280
281         int propval = 8192;
282
283         for (minor = 0; minor < 8; minor ++) {
284                 (void) ddi_prop_create(makedevice(DDI_MAJOR_T_UNKNOWN, minor),
285                     dev, DDI_PROP_CANSLEEP, "nblocks", (caddr_t) &propval,
286                     sizeof (int));
287                     ...
288         }
289
290

ATTRIBUTES

292       See attributes(5) for a description of the following attributes:
293
294
295
296
297       ┌────────────────────────────┬──────────────────────────────┐
298ATTRIBUTE TYPE        ATTRIBUTE VALUE        
299       ├────────────────────────────┼──────────────────────────────┤
300       │Stability Level             │ ddi_prop_create()        and │
301       │                            │ ddi_prop_modify() are  Obso‐ │
302       │                            │ lete                         │
303       └────────────────────────────┴──────────────────────────────┘
304

SEE ALSO

306       driver.conf(4),    attributes(5),    attach(9E),    ddi_getproplen(9F),
307       ddi_prop_op(9F), ddi_prop_update(9F), makedevice(9F)
308
309
310       Writing Device Drivers
311
312
313
314SunOS 5.11                        16 Jan 2006              ddi_prop_create(9F)
Impressum