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

NAME

6       ddi_dev_report_fault - Report a hardware failure
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12
13
14       void  ddi_dev_report_fault (dev_info_t   *dip,
15            ddi_fault_impact_t impact,  ddi_fault_location_t location,
16            const char   *message );
17
18

INTERFACE LEVEL

20       Solaris DDI specific (Solaris DDI)
21

PARAMETERS

23       dip          Pointer  to  the  driver's dev_info structure to which the
24                    fault report relates. (Normally the caller's own  dev_info
25                    pointer).
26
27
28       impact       One of a set of enumerated values indicating the impact of
29                    the fault on the device's ability to provide  normal  ser‐
30                    vice.
31
32
33       location     One  of a set of enumerated values indicating the location
34                    of the fault, relative to the hardware controlled  by  the
35                    driver specified by dip.
36
37
38       message      Text of the message describing the fault being reported.
39
40

DESCRIPTION

42       This  function  provides  a standardized mechanism through which device
43       drivers can report hardware faults.  Use of  this  reporting  mechanism
44       enables  systems  equipped with a fault management system to respond to
45       faults discovered by a driver. On  a  suitably  equipped  system,  this
46       might include automatic failover to an alternative device and/or sched‐
47       uling replacement of the faulty hardware.
48
49
50       The driver must indicate the impact of the fault being reported on  its
51       ability  to  provide service by passing one of the following values for
52       the impact parameter:
53
54       DDI_SERVICE_LOST          Indicates a total loss of service. The driver
55                                 is  unable  to implement the normal functions
56                                 of its hardware.
57
58
59       DDI_SERVICE_DEGRADED      The driver is unable to provide  normal  ser‐
60                                 vice,  but  can provide a partial or degraded
61                                 level of service. The driver may have to make
62                                 repeated  attempts  to  perform  an operation
63                                 before it succeeds, or it may be  running  at
64                                 less  than its configured speed. A driver may
65                                 use this value to indicate that  an  alterna‐
66                                 tive  device should be used if available, but
67                                 that it can continue operation if no alterna‐
68                                 tive exists.
69
70
71       DDI_SERVICE_UNAFFECTED    The  service  provided  by the device is cur‐
72                                 rently unaffected by the reported fault. This
73                                 value  may be used to report recovered errors
74                                 for predictive failure analysis.
75
76
77       DDI_SERVICE_RESTORED      The driver has resumed normal  service,  fol‐
78                                 lowing  a  previous  report  that service was
79                                 lost or degraded.  This message implies  that
80                                 any  previously  reported  fault condition no
81                                 longer exists.
82
83
84
85       The location parameter should be one of the following values:
86
87       DDI_DATAPATH_FAULT    The fault lies in the datapath between the driver
88                             and the device. The device may be unplugged, or a
89                             problem may exist in the bus on which the  device
90                             resides.  This value is appropriate if the device
91                             is not responding to accesses, (for example,  the
92                             device  may  not  be  present)  or  if  a call to
93                             ddi_check_acc_handle(9F) returns DDI_FAILURE.
94
95
96       DDI_DEVICE_FAULT      The fault lies in the device  controlled  by  the
97                             driver.  This  value is appropriate if the device
98                             returns an error from a selftest function, or  if
99                             the  driver  is  able to determine that device is
100                             present and accessible, but  is  not  functioning
101                             correctly.
102
103
104       DDI_EXTERNAL_FAULT    The  fault  is external to the device.  For exam‐
105                             ple, an Ethernet driver would use this value when
106                             reporting a cable fault.
107
108                             If  a  device  returns detectably bad data during
109                             normal operation (an "impossible" value in a reg‐
110                             ister  or  DMA  status  area,  for  example), the
111                             driver should check the associated  handle  using
112                             ddi_check_acc_handle(9F)   or  ddi_check_dma_han‐
113                             dle(9F) before reporting the fault. If the  fault
114                             is  associated with the handle, the driver should
115                             specify     DDI_DATAPATH_FAULT    rather     than
116                             DDI_DEVICE_FAULT.  As a consequence of this call,
117                             the device's state may be updated to reflect  the
118                             level   of   service   currently  available.  See
119                             ddi_get_devstate(9F).
120
121                             Note that if a driver calls  ddi_get_devstate(9F)
122                             and  discovers  that  its device is down, a fault
123                             should not be reported- the device is down as the
124                             result of a fault that has already been reported.
125                             Additionally, a driver should avoid incurring  or
126                             reporting  additional  faults  when the device is
127                             already    known    to    be    unusable.     The
128                             ddi_dev_report_fault()  call  should only be used
129                             to report hardware (device) problems  and  should
130                             not  be  used  to report purely software problems
131                             such as memory (or other resource) exhaustion.
132
133

EXAMPLES

135       An Ethernet driver receives an error interrupt from its device if vari‐
136       ous  fault conditions occur.  The driver must read an error status reg‐
137       ister to determine the nature of the fault,  and  report  it  appropri‐
138       ately:
139
140         static int
141         xx_error_intr(xx_soft_state *ssp)
142         {
143             ...
144             error_status = ddi_get32(ssp->handle, &ssp->regs->xx_err_status);
145             if (ddi_check_acc_handle(ssp->handle) != DDI_SUCCESS) {
146                 ddi_dev_report_fault(ssp->dip, DDI_SERVICE_LOST,
147                     DDI_DATAPATH_FAULT, "register access fault");
148                 return DDI_INTR_UNCLAIMED;
149             }
150             if (ssp->error_status & XX_CABLE_FAULT) {
151                 ddi_dev_report_fault(ssp->dip, DDI_SERVICE_LOST,
152                     DDI_EXTERNAL_FAULT, "cable fault")
153                 return DDI_INTR_CLAIMED;
154             }
155             if (ssp->error_status & XX_JABBER) {
156                 ddi_dev_report_fault(ssp->dip, DDI_SERVICE_DEGRADED,
157                     DDI_EXTERNAL_FAULT, "jabbering detected")
158                 return DDI_INTR_CLAIMED;
159             }
160             ...
161         }
162
163

CONTEXT

165       The ddi_dev_report_fault() function may be called from user, kernel, or
166       interrupt context.
167

SEE ALSO

169       ddi_check_acc_handle(9F),    ddi_check_dma_handle(9F),    ddi_get_devs‐
170       tate(9F)
171
172
173
174SunOS 5.11                      13 August 1999        ddi_dev_report_fault(9F)
Impressum