Manual Pages for UNIX Operating System command usage for man ddi_getlongprop_buf

Kernel Functions for Drivers                      ddi_prop_op(9F)



NAME
     ddi_prop_op,          ddi_getprop,          ddi_getlongprop,
     ddi_getlongprop_buf,  ddi_getproplen - get property informa-
     tion for leaf device drivers

SYNOPSIS
     #include 
     #include 
     #include 



     int ddi_prop_op(dev_t dev, dev_info_t *dip, ddi_prop_op_t prop_op,
          int flags, char *name, caddr_t valuep, int *lengthp);


     int ddi_getprop(dev_t dev, dev_info_t *dip, int flags, char *name,
           int defvalue);


     int ddi_getlongprop(dev_t dev, dev_info_t *dip, int flags, char *name,
           caddr_t valuep, int *lengthp);


     int ddi_getlongprop_buf(dev_t dev, dev_info_t *dip, int flags, char *name,
          caddr_t valuep, int *lengthp);


     int ddi_getproplen(dev_t dev, dev_info_t *dip, int flags, char *name,
           int *lengthp);


INTERFACE LEVEL
     Solaris DDI specific (Solaris DDI).  The  ddi_getlongprop(),
     ddi_getlongprop_buf(),  ddi_getprop(),  and ddi_getproplen()
     functions are obsolete. Use ddi_prop_lookup(9F)  instead  of
     ddi_getlongprop(),         ddi_getlongprop_buf(),        and
     ddi_getproplen().  Use   ddi_prop_get_int(9F)   instead   of
     ddi_getprop()

PARAMETERS
     dev         Device  number  associated  with   property   or
                 DDI_DEV_T_ANY as the wildcard device number.


     dip         Pointer to a device info node.


     prop_op     Property operator.






SunOS 5.11          Last change: 16 Jan 2006                    1






Kernel Functions for Drivers                      ddi_prop_op(9F)



     flags       Possible flag values are some combination of:

                 DDI_PROP_DONTPASS    do  not  pass  request   to
                                      parent  device  information
                                      node if property not found


                 DDI_PROP_CANSLEEP    the routine may sleep while
                                      allocating memory


                 DDI_PROP_NOTPROM     do not look at PROM proper-
                                      ties  (ignored on architec-
                                      tures that do  not  support
                                      PROM properties)



     name        String containing the name of the property.


     valuep      If prop_op is PROP_LEN_AND_VAL_BUF, this  should
                 be  a pointer to the users buffer. If prop_op is
                 PROP_LEN_AND_VAL_ALLOC,  this  should   be   the
                 address of a pointer.


     lengthp     On exit,  *lengthp  will  contain  the  property
                 length.  If prop_op is PROP_LEN_AND_VAL_BUF then
                 before  calling  ddi_prop_op(),  lengthp  should
                 point  to  an  int  that  contains the length of
                 callers buffer.


     defvalue    The value that ddi_getprop() returns if the pro-
                 perty is not found.


DESCRIPTION
     The ddi_prop_op() function  gets  arbitrary-size  properties
     for leaf devices. The routine searches the device's property
     list. If it does not find the property at the device  level,
     it  examines the flags argument, and if DDI_PROP_DONTPASS is
     set, then ddi_prop_op() returns  DDI_PROP_NOT_FOUND.  Other-
     wise,  it passes the request to the next level of the device
     info tree. If it does find the property,  but  the  property
     has     been     explicitly     undefined,     it    returns
     DDI_PROP_UNDEFINED. Otherwise it returns either the property
     length,  or both the length and value of the property to the
     caller via the valuep and lengthp pointers, depending on the
     value   of   prop_op,   as   described  below,  and  returns
     DDI_PROP_SUCCESS. If a property  cannot  be  found  at  all,



SunOS 5.11          Last change: 16 Jan 2006                    2






Kernel Functions for Drivers                      ddi_prop_op(9F)



     DDI_PROP_NOT_FOUND is returned.


     Usually, the dev argument should be set to the actual device
     number  that  this property applies to.  However, if the dev
     argument  is   DDI_DEV_T_ANY,   the   wildcard   dev,   then
     ddi_prop_op()  will  match  the  request  based on name only
     (regardless of the  actual  dev  the  property  was  created
     with). This property/dev match is done according to the pro-
     perty search order which is to first search software proper-
     ties  created  by  the  driver  in last-in, first-out (LIFO)
     order, next search software properties created by the system
     in  LIFO order, then search PROM properties if they exist in
     the system architecture.


     Property operations are specified by the  prop_op  argument.
     If  prop_op  is  PROP_LEN,  then ddi_prop_op() just sets the
     callers length, *lengthp, to the property length and returns
     the  value  DDI_PROP_SUCCESS to the caller. The valuep argu-
     ment is not used in this case.  Property lengths are  0  for
     boolean  properties, sizeof(int) for integer properties, and
     size in bytes for long (variable size) properties.


     If prop_op is PROP_LEN_AND_VAL_BUF, then valuep should be  a
     pointer  to  a  user-supplied  buffer whose length should be
     given in *lengthp by the caller.  If the requested  property
     exists,  ddi_prop_op()  first  sets *lengthp to the property
     length.  It then examines the size of the buffer supplied by
     the  caller,  and if it is large enough, copies the property
     value into that buffer, and returns DDI_PROP_SUCCESS. If the
     named  property  exists but the buffer supplied is too small
     to hold it, it returns DDI_PROP_BUF_TOO_SMALL.


     If prop_op is PROP_LEN_AND_VAL_ALLOC, and  the  property  is
     found,  ddi_prop_op()  sets *lengthp to the property length.
     It then attempts to allocate  a  buffer  to  return  to  the
     caller  using the kmem_alloc(9F) routine, so that memory can
     be  later  recycled  using  kmem_free(9F).  The  driver   is
     expected  to  call kmem_free() with the returned address and
     size when it is done using  the  allocated  buffer.  If  the
     allocation  is  successful,  it sets *valuep to point to the
     allocated buffer, copies the property value into the  buffer
     and   returns   DDI_PROP_SUCCESS.   Otherwise,   it  returns
     DDI_PROP_NO_MEMORY. Note that the flags argument may  affect
     the  behavior of memory allocation in ddi_prop_op(). In par-
     ticular, if DDI_PROP_CANSLEEP is set, then the routine  will
     wait  until  memory  is available to copy the requested pro-
     perty.




SunOS 5.11          Last change: 16 Jan 2006                    3






Kernel Functions for Drivers                      ddi_prop_op(9F)



     The ddi_getprop() function returns boolean and  integer-size
     properties.  It  is  a convenience wrapper for ddi_prop_op()
     with prop_op set to PROP_LEN_AND_VAL_BUF, and the buffer  is
     provided  by  the  wrapper.  By  convention,  this  function
     returns a 1 for boolean (zero-length) properties.


     The ddi_getlongprop() function returns  arbitrary-size  pro-
     perties.  It is a convenience wrapper for ddi_prop_op() with
     prop_op set to PROP_LEN_AND_VAL_ALLOC, so that  the  routine
     will allocate space to hold the buffer that will be returned
     to the caller via *valuep.


     The ddi_getlongprop_buf()  function  returns  arbitrary-size
     properties.  It  is  a convenience wrapper for ddi_prop_op()
     with prop_op set to PROP_LEN_AND_VAL_BUF so  the  user  must
     supply a buffer.


     The ddi_getproplen() function returns the length of a  given
     property. It is a convenience wrapper for ddi_prop_op() with
     prop_op set to PROP_LEN.

RETURN VALUES
     The ddi_prop_op(), ddi_getlongprop(), ddi_getlongprop_buf(),
     and ddi_getproplen() functions return:

     DDI_PROP_SUCCESS          Property found and returned.


     DDI_PROP_NOT_FOUND        Property not found.


     DDI_PROP_UNDEFINED        Property already explicitly  unde-
                               fined.


     DDI_PROP_NO_MEMORY        Property  found,  but  unable   to
                               allocate memory. lengthp points to
                               the correct property length.


     DDI_PROP_BUF_TOO_SMALL    Property found, but  the  supplied
                               buffer   is   too  small.  lengthp
                               points  to  the  correct  property
                               length.



     The ddi_getprop() function returns:




SunOS 5.11          Last change: 16 Jan 2006                    4






Kernel Functions for Drivers                      ddi_prop_op(9F)



     The value of the property or the value passed into the  rou-
     tine  as  defvalue  if the property is not found. By conven-
     tion, the value of zero length properties  (boolean  proper-
     ties) are returned as the integer value 1.

CONTEXT
     These functions can be called from user, interrupt, or  ker-
     nel context, provided DDI_PROP_CANSLEEP is not set; if it is
     set, they cannot be called from interrupt context.

ATTRIBUTES
     See attributes(5) for a description of the following  attri-
     butes:



     ____________________________________________________________
    |      ATTRIBUTE TYPE       |        ATTRIBUTE VALUE        |
    |___________________________|_______________________________|
    | Stability Level           | ddi_getlongprop(),            |
    |                           | ddi_getlongprop_buf(),        |
    |                           | ddi_getprop(),             and|
    |                           | ddi_getproplen() functions are|
    |                           | Obsolete                      |
    |___________________________|_______________________________|


SEE ALSO
     attributes(5),  ddi_prop_create(9F),   ddi_prop_get_int(9F),
     ddi_prop_lookup(9F), kmem_alloc(9F), kmem_free(9F)


     Writing Device Drivers






















SunOS 5.11          Last change: 16 Jan 2006                    5