ddi_dev_is_needed(9F)

NAME

     ddi_dev_is_needed - inform the system that a  device's  com-
     ponent is required

SYNOPSIS

     #include <sys/ddi.h>
     #include <sys/sunddi.h>

     int ddi_dev_is_needed(dev_info_t *dip,  int  component,  int
     level);

INTERFACE LEVEL

     Solaris DDI specific (Solaris DDI)

PARAMETERS

      dip  Pointer to the device's dev_info structure.

     component
           Component of the driver which is needed.

     level Power level at which the component is needed.

DESCRIPTION

     The ddi_dev_is_needed() function is  obsolete  and  will  be
     removed  in  a future release. It is recommended that device
     drivers use pm_raise_power(9F) and pm_lower_power(9F).

     The ddi_dev_is_needed() function informs the system  that  a
     device component is needed at the specified power level. The
     level argument must be non-zero.

     This function sets a component to  the  required  level  and
     sets  all devices which depend on this to their normal power
     levels. If component 0 of  a  device  using  original  Power
     Management  interfaces  (calls  pm_create_components(9F)) is
     at power level 0, the ddi_dev_is_needed() call  will  result
     in component 0 being returned to normal power and the device
     being  resumed  via  attach(9E)  before  ddi_dev_is_needed()
     returns.

     The state of the device should be examined before each  phy-
     sical  access.   The  ddi_dev_is_needed() function should be
     called to set a component to the required power level if the
     operation  to be performed requires the component to be at a
     power level other than its current level.

     The ddi_dev_is_needed() function might cause re-entry of the
     driver.  Deadlock may result if driver locks are held across
     the call to ddi_dev_is_needed().

RETURN VALUES

     The ddi_dev_is_needed() function returns:

     DDI_SUCCESS
           Power successfully set to the requested level.

     DDI_FAILURE
           An error occurred.

EXAMPLES

     Example 1: disk driver code

     A hypothetical disk driver might include this code:

          static int
     xxdisk_spun_down(struct xxstate *xsp)
     {
               return (xsp->power_level[DISK_COMPONENT] < POWER_SPUN_UP);
     }
     static int
     xxdisk_strategy(struct buf *bp)
     {

     ...

               mutex_enter(&xxstate_lock);
               /*
               * Since we have to drop the mutex, we have to do this in a loop
               * in case we get preempted and the device gets taken away from
               * us again
               */
               while (device_spun_down(sp)) {
                    mutex_exit(&xxstate_lock);
                    if (ddi_dev_is_needed(xsp->mydip,
                         XXDISK_COMPONENT, XXPOWER_SPUN_UP) != DDI_SUCCESS) {
                              bioerror(bp,EIO);
                              biodone(bp);
                              return (0);
                    }
                    mutex_enter(&xxstate_lock);
               }
               xsp->device_busy++;
               mutex_exit(&xxstate_lock);

     ...

     }

CONTEXT

     This function can be called from user or kernel context.

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |      ATTRIBUTE TYPE      |         ATTRIBUTE VALUE        |
    |__________________________|________________________________|
    | Interface stability      |  Obsolete                      |
    |__________________________|________________________________|

SEE ALSO

     pm(7D),    pm-components(9P),    attach(9E),     detach(9E),
     power(9E),                           pm_busy_components(9F),
     pm_create_components(9F),         pm_destroy_components(9F),
     pm_idle_component(9F)

     Writing Device Drivers