ddi_fm_handler_register(9f)

1ddi_fm_handler_register(9FK)ernel Functions for Driverdsdi_fm_handler_register(9F)
2
3
4

NAME

6       ddi_fm_handler_register, ddi_fm_handler_unregister - register or unreg‐
7       ister an error handling callback
8

SYNOPSIS

10       #include <sys/ddifm.h>
11
12       void ddi_fm_handler_register(dev_info_t *dip,
13            ddi_err_func_t error_handler, void *impl_data);
14
15
16       void ddi_fm_handler_unregister(dev_info_t *dip);
17
18

INTERFACE LEVEL

20       Solaris DDI specific (Solaris DDI)
21

PARAMETERS

23       dip              Pointer to the dev_info structure
24
25
26       error_handler    Pointer to an error handler callback function
27
28
29       impl_data        Pointer to private data for use by the caller
30
31

DESCRIPTION

33       The ddi_fm_handler_register() function registers an error handler call‐
34       back routine with the I/O Fault Management framework. The error handler
35       callback, error_handler, is called to process error conditions detected
36       by  the system. In addition to its device instance, dip, the error han‐
37       dler is called with a pointer to a fault management error status struc‐
38       ture, ddi_fm_error_t. For example:
39
40         int (*ddi_err_func_t)(dev_info_t *dip, ddi_fm_error_t *error_status);
41
42
43
44       A driver error handling callback is passed the following arguments:
45
46           o      a  pointer  to the device instance registered for this call‐
47                  back.
48
49           o      a data structure containing common fault management data and
50                  status for error handling.
51
52
53       The primary responsibilities of the error handler include:
54
55           o      to check for outstanding hardware or software errors.
56
57           o      where possible, to isolate the device that might have caused
58                  the errors.
59
60           o      to report errors that were detected.
61
62
63       During the invocation of an error handler, a device driver  might  need
64       to  quiesce  or  suspend all I/O activities in order to check for error
65       conditions or status in:
66
67           o      hardware control and status registers.
68
69           o      outstanding I/O transactions.
70
71           o      access or DMA handles.
72
73
74       For each error detected, the driver must formulate and  post  an  error
75       report  via  ddi_fm_ereport_post()  for problem analysis by the Solaris
76       Fault Manager fmd(1M).
77
78
79       For a PCI, PCI/X, or PCI Express leaf  device,  the  pci_ereport_post()
80       function  is provided to carry out reporting responsibilities on behalf
81       of the driver. In many cases, an error handler callback function of the
82       following form can be used:
83
84         xxx_err_cb(dev_info_t *dip, ddi_fm_error_t *errp) {
85               pci_ereport_post(dip, errp, NULL);
86               return (errp->fme_status);
87         }
88
89
90
91       In  addition, the driver might be able to carry out further device spe‐
92       cific checks within the error handler.
93
94
95       Error handlers can be called  from  kernel,  interrupt,  or  high-level
96       interrupt   context.   The   interrupt   block   cookie  returned  from
97       ddi_fm_init() should be used to allocate and  initialize  any  synchro‐
98       nization  variables  and locks that might be used within the error han‐
99       dler callback function. Such locks may not be held by the driver when a
100       device  register  is  accessed  with functions such as ddi_get8(9F) and
101       ddi_put8(9F).
102
103
104       The data structure, ddi_fm_error_t, contains an FMA protocol (format 1)
105       ENA  for  the  current error propagation chain, the status of the error
106       handler callback, an error expectation flag, and any  potential  access
107       or DMA handles associated with an error detected by the parent nexus.
108
109
110       The  ddi_fm_handler_unregister()  function  removes a previously regis‐
111       tered error handling callback for the device instance specified by  the
112       dip.
113

CONTEXT

115       The ddi_fm_handler_register() and ddi_fm_handler_unregister() functions
116       must be called from kernel context in an attach(9E) or detach(9E) entry
117       point.  The  registered  error  handler, error_handler, callback can be
118       called from kernel, interrupt, or high level interrupt context.
119

ATTRIBUTES

121       See attributes(5) for descriptions of the following attributes:
122
123
124
125
126       ┌─────────────────────────────┬─────────────────────────────┐
127       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
128       ├─────────────────────────────┼─────────────────────────────┤
129       │Interface Stability          │Committed                    │
130       └─────────────────────────────┴─────────────────────────────┘
131