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

NAME

6       ddi_prop_op,    ddi_getprop,    ddi_getlongprop,   ddi_getlongprop_buf,
7       ddi_getproplen - get property information for leaf device drivers
8

SYNOPSIS

10       #include <sys/types.h>
11       #include <sys/ddi.h>
12       #include <sys/sunddi.h>
13
14
15
16       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
19
20       int ddi_getprop(dev_t dev, dev_info_t *dip, int flags, char *name,
21             int defvalue);
22
23
24       int ddi_getlongprop(dev_t dev, dev_info_t *dip, int flags, char *name,
25             caddr_t valuep, int *lengthp);
26
27
28       int ddi_getlongprop_buf(dev_t dev, dev_info_t *dip, int flags, char *name,
29            caddr_t valuep, int *lengthp);
30
31
32       int ddi_getproplen(dev_t dev, dev_info_t *dip, int flags, char *name,
33             int *lengthp);
34
35

INTERFACE LEVEL

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

PARAMETERS

44       dev         Device number associated with property or DDI_DEV_T_ANY  as
45                   the wildcard device number.
46
47
48       dip         Pointer to a device info node.
49
50
51       prop_op     Property operator.
52
53
54       flags       Possible flag values are some combination of:
55
56                   DDI_PROP_DONTPASS    do  not  pass request to parent device
57                                        information node if property not found
58
59
60                   DDI_PROP_CANSLEEP    the routine may sleep while allocating
61                                        memory
62
63
64                   DDI_PROP_NOTPROM     do   not   look   at  PROM  properties
65                                        (ignored on architectures that do  not
66                                        support PROM properties)
67
68
69
70       name        String containing the name of the property.
71
72
73       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
78
79       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
84
85       defvalue    The value that ddi_getprop() returns if the property is not
86                   found.
87
88

DESCRIPTION

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
103
104       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
114
115       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
122
123       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
132
133       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
146
147       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
153
154       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
159
160       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
164
165       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

RETURN VALUES

170       The   ddi_prop_op(),   ddi_getlongprop(),   ddi_getlongprop_buf(),  and
171       ddi_getproplen() functions return:
172
173       DDI_PROP_SUCCESS          Property found and returned.
174
175
176       DDI_PROP_NOT_FOUND        Property not found.
177
178
179       DDI_PROP_UNDEFINED        Property already explicitly undefined.
180
181
182       DDI_PROP_NO_MEMORY        Property found, but unable to  allocate  mem‐
183                                 ory.  lengthp  points to the correct property
184                                 length.
185
186
187       DDI_PROP_BUF_TOO_SMALL    Property found, but the  supplied  buffer  is
188                                 too  small.  lengthp  points  to  the correct
189                                 property length.
190
191
192
193       The ddi_getprop() function returns:
194
195
196       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

CONTEXT

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

ATTRIBUTES

207       See attributes(5) for a description of the following attributes:
208
209
210
211
212       ┌───────────────────────────┬───────────────────────────────┐
213ATTRIBUTE 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

SEE ALSO

222       attributes(5),        ddi_prop_create(9F),        ddi_prop_get_int(9F),
223       ddi_prop_lookup(9F), kmem_alloc(9F), kmem_free(9F)
224
225
226       Writing Device Drivers
227
228
229
230SunOS 5.11                        16 Jan 2006                  ddi_prop_op(9F)
Impressum