pm_trans_check(9F)

NAME

     pm_trans_check -  Device power cycle advisory check

SYNOPSIS

     #include <sys/sunddi.h>

     int  pm_trans_check(struct  pm_trans_data   *datap,   time_t
     *intervalp);

INTERFACE LEVEL

     Solaris DDI specific (Solaris DDI)

PARAMETERS

      datap
           Pointer to a pm_trans_data structure

      intervalp
           Pointer to time difference when next power cycle  will
           be advised

DESCRIPTION

     The pm_trans_check(9F) function checks if a  power-cycle  is
     currently advised based on data in the pm_trans_data  struc-
     ture.  This function is provided to prevent damage  to  dev-
     ices  from excess power cycles; drivers for devices that are
     sensitive  to  the  number  of  power  cycles  should   call
     pm_trans_check(9F)  from  their  power(9E)  function  before
     powering-off a device. If pm_trans_check(9F) indicates  that
     the device should not be power cycled, the driver should not
     attempt to power cycle the device and should fail  the  call
     to power(9E) entry point.

     If pm_trans_check(9F) returns that  it  is  not  advised  to
     power  cycle  the  device, it attempts to calculate when the
     next power cycle is advised, based on the  supplied  parame-
     ters.  In  such case, intervalp  returns the time difference
     (in seconds) from the current time to when  the  next  power
     cycle  is advised. If the time for the next power cycle can-
     not be determined, intervalp  indicates 0.

     To avoid excessive calls to the power(9E) entry point during
     a  period  when  power  cycling  is  not advised, the driver
     should mark the corresponding device component busy for  the
     intervalp    time  period  (if  interval  is  not  0).  Con-
     veniently, the driver can utilize the  fact  that  calls  to
     pm_busy_component(9F)  are  stacked. If power cycling is not
     advised, the driver can call pm_busy_component(9F)
      and issue a  timeout(9F)  for  the  intervalp    time.  The
     timeout()    handler    can    issue    the    corresponding
     pm_idle_component(9F) call.

     When  the  format  field  of   pm_trans_data   is   set   to
     DC_SCSI_FORMAT,  the  caller  must   provide  valid  data in
     svc_date[], lifemax, and ncycles. Currently,  flag  must  be
     set to 0.

     struct pm_scsi_cycles {
               int lifemax;                       /* lifetime max power cycles */
               int ncycles;                       /* number of cycles so far */
               char svc_date[DC_SCSI_MFR_LEN];    /* service date YYYYWW */
               int flag;                          /* reserved for future */
          };

          struct pm_trans_data {
               int format;                        /* data format */
               union {
                    struct pm_scsi_cycles scsi_cycles;
               } un;
          };

RETURN VALUES

     1      Power cycle is advised

     0      Power cycle is not advised

     -1     Error due to invalid argument.

ATTRIBUTES

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Evolving                    |
    |_____________________________|_____________________________|

SEE ALSO

       power.conf(4),  attributes(5),  power(9E)

     Writing Device Drivers

     Using Power Management