power(9E)

NAME

     power - power a device attached to the system

SYNOPSIS

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

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

INTERFACE LEVEL

     Solaris DDI specific (Solaris  DDI).  This  entry  point  is
     required.  If  the  driver writer does not supply this entry
     point, the value NULL must be used in the cb_ops(9S)  struc-
     ture instead.

PARAMETERS

     dip   Pointer to the device's dev_info structure.

     component
           Component of the driver to be managed.

     level Desired component power level.

DESCRIPTION

     The power(9E) function is the device-specific Power  Manage-
     ment  entry  point.  This function is called when the system
     wants the driver to set the  power  level  of  component  to
     level.

     The power() entry  points  behave  as  described  under  NEW
     BEHAVIOR  if  the  device  driver  uses new automatic device
     Power   Management   interfaces    (driver    exports    pm-
     components(9P)  property). The power()entry point behaves as
     described under OBSOLETE BEHAVIOR if the device driver  uses
     original Power Management interfaces (driver does not export
     the    pm-components    property    but    instead     calls
     pm_create_components(9F)).   The  behavior  described  under
     OBSOLETE BEHAVIOR is obsolete  and  will  be  removed  in  a
     future release.

  NEW BEHAVIOR
     The level  argument is the  driver-defined  power  level  to
     which  the component needs to be set. Except for power level
     0, which is interpreted by the framework  to  mean  "powered
     off,"  the  interpretation  of  level  is entirely up to the
     driver.

     The component argument is the component of the device to  be
     power-managed.  The  interpretation of component is entirely
     up to the driver.

     When a requested power transition would cause the device  to
     lose  state, the driver must save the state of the device in
     memory. When a requested power transition requires state  to
     be restored, the driver must restore that state.

     If a requested power transition for one  component  requires
     another  component  to  change  power state before it can be
     completed, the driver must call  pm_raise_power(9F)  to  get
     the  other  component changed, and the power(9E) entry point
     must support being re-entered.

     If the system requests an inappropriate power transition for
     the  device  (for  example, a request to power down a device
     which has just become busy), then the power level should not
     be changed and power should return DDI_FAILURE.

  OBSOLETE BEHAVIOR
     The level argument is  the  driver-defined  power  level  to
     which  component must be set. Except for power level 0 which
     is defined by the  framework  to  mean  "powered  off,"  the
     interpretation of level is entirely up to the driver.

     The component argument is the component of the device to  be
     power-managed.  Except for component 0, which must represent
     the  entire  device,  the  interpretation  of  component  is
     entirely up to the driver.

     The power() function can assume  that  the  driver  will  be
     suspended  (using  detach(9E)  with command DDI_PM_SUSPEND),
     before a request is made to set component 0 to power level 0
     and  resumed  (using  attach(9E) with command DDI_PM_RESUME)
     after setting component 0 from power level 0 to  a  non-zero
     power level.

     If the system requests an inappropriate power transition for
     the  device  (for  example, a request to power down a device
     which has just become busy), then the power level should not
     be   changed   and  the  power(9E)  function  should  return
     DDI_FAILURE.

RETURN VALUES

     The power() function returns:

     DDI_SUCCESS
           Successfully set the power to the requested level.

     DDI_FAILURE
           Failed to set the power to the requested level.

CONTEXT

     The power() function is called from user or  kernel  context
     only.

ATTRIBUTES

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

     ____________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  Interface stability        |  Evolving (Interfaces  under|
   |                             |  OBSOLETE    BEHAVIOR    are|
   |                             |  obsolete.)                 |
   |_____________________________|_____________________________|

SEE ALSO

     attach(9E),       detach(9E),         pm_busy_component(9F),
     pm_create_components(9F),         pm_destroy_components(9F),
     pm_idle_component(9F),        pm_raise_power(9F),        pm-
     components(9P), cb_ops(9S)

     Writing Device Drivers

      Using Power Management