pm_trans_check(9f)

1pm_trans_check(9F)       Kernel Functions for Drivers       pm_trans_check(9F)
2
3
4

NAME

6       pm_trans_check - Device power cycle advisory check
7

SYNOPSIS

9       #include <sys/sunddi.h>
10
11       int pm_trans_check(struct pm_trans_data *datap, time_t *intervalp);
12
13

INTERFACE LEVEL

15       Solaris DDI specific (Solaris DDI)
16

PARAMETERS

18       datap    Pointer to a pm_trans_data structure
19
20
21       intervalp    Pointer  to  time difference when next power cycle will be
22                    advised
23
24

DESCRIPTION

26       The pm_trans_check() function checks  if  a  power-cycle  is  currently
27       advised based on data in the pm_trans_data  structure. This function is
28       provided to prevent damage to devices from excess power cycles; drivers
29       for  devices  that  are  sensitive to the number of power cycles should
30       call pm_trans_check() from their power(9E) function before powering-off
31       a  device.  If pm_trans_check() indicates that the device should not be
32       power cycled, the driver should not attempt to power cycle  the  device
33       and should fail the call to power(9E) entry point.
34
35
36       If  pm_trans_check()  returns that it is not advised to power cycle the
37       device, it attempts to calculate when the  next power cycle is advised,
38       based  on  the supplied parameters. In such case, intervalp returns the
39       time difference (in seconds) from the current time  to  when  the  next
40       power  cycle is advised. If the time for the next power cycle cannot be
41       determined, intervalp indicates 0.
42
43
44       To avoid excessive calls to the power(9E) entry point during  a  period
45       when  power  cycling  is not advised, the driver should mark the corre‐
46       sponding device component busy  for  the   intervalp  time  period  (if
47       interval  is not 0). Conveniently, the driver can utilize the fact that
48       calls to pm_busy_component(9F) are stacked. If  power  cycling  is  not
49       advised,  the  driver can call pm_busy_component(9F)  and issue a time‐
50       out(9F) for the intervalp time. The timeout()  handler  can  issue  the
51       corresponding pm_idle_component(9F) call.
52
53
54       The  format  field  of  pm_trans_data  accepts either DC_SCSI_FORMAT or
55       DC_SMART_FORMAT. If the caller provides information  from  a  SCSI  Log
56       Page,  it  should  set  the format field to DC_SCSI_FORMAT, and provide
57       valid  data  in  svc_date[],  lifemax,  ncycles   and   flag   in   the
58       pm_scsi_cycles  structure.  If  the  caller provides information from a
59       SMART  feature  attribute,  it  should  set   the   format   field   to
60       DC_SMART_FORMAT  and  provide valid data in allowed, usedup and flag in
61       the pm_smart_count structure, where allowed  indicates  the  normalized
62       cycle  count  before reaching the borderline threshold cycle count, and
63       usedup indicates the normalized consumed cycle count.
64
65
66       The flag field in both pm_scsi_cycles and pm_smart_count structures  is
67       reserved for future use and must be set to 0.
68
69         struct pm_trans_data {
70                int format;            /* data format */
71                union {
72                      struct pm_scsi_cycles scsi_cycles;
73                      struct pm_smart_count smart_count;
74                } un;
75         };
76
77

RETURN VALUES

79       1     Power cycle is advised.
80
81
82       0     Power cycle is not advised.
83
84
85       -1    Error due to invalid argument.
86
87

ATTRIBUTES

89       See attributes(5) for descriptions of the following attributes:
90
91
92
93
94       ┌─────────────────────────────┬─────────────────────────────┐
95       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
96       ├─────────────────────────────┼─────────────────────────────┤
97       │Interface Stability          │Committed                    │
98       └─────────────────────────────┴─────────────────────────────┘
99