pci_ereport_teardown(9f)

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

NAME

6       pci_ereport_setup,  pci_ereport_teardown, pci_ereport_post - post error
7       reports for the generic PCI errors logged in the PCI Configuration Sta‐
8       tus register.
9

SYNOPSIS

11       #include <sys/sunddi.h>
12
13       void pci_ereport_setup(dev_info_t *dip, int);
14
15
16       void pci_ereport_teardown(dev_info_t *dip);
17
18
19       void pci_ereport_post(dev_info_t *dip, ddi_fm_error_t *dep,
20            uin16_t *status);
21
22

INTERFACE LEVEL

24       Solaris DDI specific (Solaris DDI)
25

PARAMETERS

27       dip       Pointer to the dev_info structure of the devices
28
29
30       dep       Pointer to DDI error status
31
32
33       status    Pointer to status bit storage location
34
35

DESCRIPTION

37       The  pci_ereport_setup()  function initializes support for error report
38       generation and sets up the resources  for  subsequent  access  to  PCI,
39       PCI/X  or  PCI Express Configuration space. The caller must have estab‐
40       lished a fault management capability  level  of  at  least  DDI_FM_ERE‐
41       PORT_CAPABLE with a previous call to ddi_fm_init() for dip.
42
43
44       The  pci_ereport_teardown()  function  releases any resources allocated
45       and set up by pci_ereport_setup() and associated with dip.
46
47
48       The pci_ereport_post() function is called to scan for and post any PCI,
49       PCI/X  or PCI Express Bus errors. On a PCI bus, for example, the errors
50       detected include:
51
52           o      Detected Parity Error
53
54           o      Master Data Parity Error
55
56           o      Target Abort
57
58           o      Master Abort
59
60           o      System Error
61
62           o      Discard Timeout
63
64
65       The pci_ereport_post() function must be called  only  from  a  driver's
66       error  handler  callback function. See ddi_fm_handler_register(9F). The
67       error_status argument to the error handler callback function should  be
68       passed through as the dep argument to pci_ereport_post() as it may con‐
69       tain bus specific information that might be  useful  for  handling  any
70       errors that are discovered.
71
72
73       The fme_flag in the error_status argument to the error handler callback
74       function will contain one of the following:
75
76       DDI_FM_ERR_UNEXPECTED()    Any errors discovered are unexpected.
77
78
79       DDI_FM_ERR_EXPECTED()    Errors  discovered  were  the  result   of   a
80                                DDI_ACC_CAUTIOUS operation.
81
82
83       DDI_FM_ERR_POKE()        Errors   discovered   are   the  result  of  a
84                                ddi_poke(9F) operation.
85
86
87       DDI_FM_ERR_PEEK()        Errors  discovered  are  the   result   of   a
88                                ddi_peek(9F) operation.
89
90
91
92       Error  report  events are generated automatically if fme_flag is set to
93       DDI_FM_ERR_UNEXPECTED and the corresponding error bits are set  in  the
94       various  PCI,  PCI/X  or  PCI Express Bus error registers of the device
95       associated with dip. The generated error report events  are  posted  to
96       the Solaris Fault Manager, fmd(1M), for diagnosis.
97
98
99       If  the  status argument is non-null, pci_ereport_post() saves the con‐
100       tents of the PCI Configuration Status Register to *status. If it is not
101       possible  to read the PCI Configuration Status Register, -1 is returned
102       in *status instead.
103
104
105       On return from  the  call  to  pci_ereport_post(),  the  ddi_fm_error_t
106       structure  pointed at by dep will have been updated, and the fme_status
107       field contains one of the following values:
108
109       DDI_FM_OK          No errors were  detected  which  might  affect  this
110                          device instance.
111
112
113       DDI_FM_FATAL       An  error  which  is  considered fatal to the opera‐
114                          tional state of the system was detected.
115
116
117       DDI_FM_NONFATAL    An error which is not considered fatal to the opera‐
118                          tional   state  of  the  system  was  detected.  The
119                          fme_acc_handle  or  fme_dma_handle  fields  in   the
120                          returned  ddi_fm_error_t  structure  will  typically
121                          reference  a  handle  that  belongs  to  the  device
122                          instance that has been affected.
123
124
125       DDI_FM_UNKNOWN     An  error  was  detected, but the call was unable to
126                          determine the impact of the error on the operational
127                          state of the system. This is treated the same way as
128                          DDI_FM_FATAL unless some other  device  is  able  to
129                          evaluate the fault to be DDI_FM_NONFATAL.
130
131

CONTEXT

133       The  pci_ereport_setup()  and  pci_ereport_teardown() functions must be
134       called from user or kernel context.
135
136
137       The pci_ereport_post() function can be called in any context.
138

EXAMPLES

140         int xxx_fmcap = DDI_FM_EREPORT_CAPABLE | DDI_FM_ERRCB_CAPABLE;
141
142         xxx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd) {
143
144               ddi_fm_init(dip, &xxx_fmcap, &xxx_ibc);
145                   if (xxx_fmcap & DDI_FM_ERRCB_CAPABLE)
146               ddi_fm_handler_register(dip, xxx_err_cb);
147                   if (xxx_fmcap & DDI_FM_EREPORT_CAPABLE)
148                       pci_ereport_setup(dip);
149
150         }
151
152         xxx_err_cb(dev_info_t *dip, ddi_fm_error_t *errp) {
153         uint16_t status;
154
155              pci_ereport_post(dip, errp, &status);
156         return (errp->fme_status);
157         }
158
159         xxx_detach(dev_info_t *dip, ddi_attach_cmd_t cmd) {
160
161              if (xxx_fmcap & DDI_FM_EREPORT_CAPABLE)
162                  pci_ereport_teardown(dip);
163              if (xxx_fmcap & DDI_FM_ERRCB_CAPABLE)
164                  ddi_fm_handler_unregister(dip);
165         ddi_fm_fini(dip);
166
167         }
168
169

ATTRIBUTES

171       See attributes(5) for descriptions of the following attributes:
172
173
174
175
176       ┌─────────────────────────────┬─────────────────────────────┐
177       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
178       ├─────────────────────────────┼─────────────────────────────┤
179       │Interface Stability          │Committed                    │
180       └─────────────────────────────┴─────────────────────────────┘
181