prop_op(9e) - osol9

1prop_op(9E)                   Driver Entry Points                  prop_op(9E)
2
3
4

NAME

6       prop_op - report driver property information
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/ddi.h>
11       #include <sys/sunddi.h>
12
13
14
15       int prefixprop_op(dev_t dev, dev_info_t *dip,
16            ddi_prop_op_t prop_op, int flags, char *name, caddr_t valuep,
17            int *lengthp);
18
19

INTERFACE LEVEL

21       Solaris  DDI  specific (Solaris DDI). This entry point is required, but
22       it can be ddi_prop_op(9F).
23

ARGUMENTS

25       dev         Device number associated with this device.
26
27
28       dip         A pointer to the  device  information  structure  for  this
29                   device.
30
31
32       prop_op     Property operator. Valid operators are:
33
34                   PROP_LEN                  Get property length only. (valuep
35                                             unaffected).
36
37
38                   PROP_LEN_AND_VAL_BUF      Get length and value  into  call‐
39                                             er's   buffer.  (valuep  used  as
40                                             input).
41
42
43                   PROP_LEN_AND_VAL_ALLOC    Get length and value  into  allo‐
44                                             cated buffer. (valuep returned as
45                                             pointer to pointer  to  allocated
46                                             buffer).
47
48
49
50       flags       The only possible flag value is:
51
52                   DDI_PROP_DONTPASS    Do not pass request to parent if prop‐
53                                        erty not found.
54
55
56
57       name        Pointer to name of property to be interrogated.
58
59
60       valuep      If  prop_op is   PROP_LEN_AND_VAL_BUF,  this  should  be  a
61                   pointer    to   the   user's   buffer.    If   prop_op   is
62                   PROP_LEN_AND_VAL_ALLOC, this should be  the  address  of  a
63                   pointer.
64
65
66       lengthp     On  exit,   *lengthp  will contain the property length.  If
67                   prop_op is  PROP_LEN_AND_VAL_BUF then lengthp should  point
68                   to  an  int  that  contains  the length of caller's buffer,
69                   before calling prop_op().
70
71

DESCRIPTION

73       prop_op() is an entry point which reports the values of certain proper‐
74       ties  of  the  driver  or device to the system. Each driver must have a
75       prefix prop_op entry point, but most drivers that do not need to create
76       or  manage  their  own  properties can use ddi_prop_op() for this entry
77       point.  Then the driver can use ddi_prop_update(9F) to  create  proper‐
78       ties for its device.
79

RETURN VALUES

81       prop_op() should return:
82
83       DDI_PROP_SUCCESS           Property found and returned.
84
85
86       DDI_PROP_NOT_FOUND         Property not found.
87
88
89       DDI_PROP_UNDEFINED         Prop explicitly undefined.
90
91
92       DDI_PROP_NO_MEMORY         Property  found, but unable to allocate mem‐
93                                  ory.  lengthp  has  the   correct   property
94                                  length.
95
96
97       DDI_PROP_BUF_TOO_SMALL     Property  found,  but the supplied buffer is
98                                  too small. lengthp has the correct  property
99                                  length.
100
101

EXAMPLES

103       Example 1 Using prop_op() to Report Property Information
104
105
106       In the following example, prop_op() intercepts requests for the temper‐
107       ature property. The driver tracks changes to temperature using a  vari‐
108       able  in  the  state  structure  in  order  to  avoid frequent calls to
109       ddi_prop_update(9F). The temperature property is only  updated  when  a
110       request  is  made  for  this property.  It then uses the system routine
111       ddi_prop_op(9F) to process  the  property  request.   If  the  property
112       request  is not specific to a device, the driver does not intercept the
113       request. This is indicated when the value  of  the   dev  parameter  is
114       equal to DDI_DEV_T_ANY.
115
116
117         int temperature;    /* current device temperature */
118          .
119          .
120          .
121         static int
122         xxprop_op(dev_t dev, dev_info_t *dip, ddi_prop_op_t prop_op,
123              int flags, char *name, caddr_t valuep, int *lengthp)
124         {
125                        int  instance;
126                        struct xxstate *xsp;
127              if (dev == DDI_DEV_T_ANY)
128                             goto skip;
129              instance = getminor(dev);
130              xsp = ddi_get_soft_state(statep, instance);
131              if (xsp == NULL)
132                             return (DDI_PROP_NOT_FOUND);
133              if (strcmp(name, "temperature") == 0) {
134                             ddi_prop_update_int(dev, dip,\
135                    "temperature", temperature);
136              }
137                          /* other cases... */
138              skip:
139              return (ddi_prop_op(dev, dip, prop_op, flags,\
140                      name, valuep, lengthp));
141         }
142
143