usr/src/man/man9f/pci_ereport_setup.9f

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PCI_EREPORT_SETUP 9F "Mar 27, 2016"
   7 .SH NAME
   8 pci_ereport_setup, pci_ereport_teardown, pci_ereport_post \- post error reports
   9 for the generic PCI errors logged in the PCI Configuration Status register.
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/sunddi.h>
  14
  15 \fBvoid\fR \fBpci_ereport_setup\fR(\fBdev_info_t\fR *\fIdip\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBvoid\fR \fBpci_ereport_teardown\fR(\fBdev_info_t\fR *\fIdip\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBvoid\fR \fBpci_ereport_post\fR(\fBdev_info_t\fR *\fIdip\fR, \fBddi_fm_error_t\fR *\fIdep\fR,
  26      \fBuin16_t\fR *\fIstatus\fR);
  27 .fi
  28
  29 .SH INTERFACE LEVEL
  30 .LP
  31 Solaris DDI specific (Solaris DDI)
  32 .SH PARAMETERS
  33 .ne 2
  34 .na
  35 \fB\fIdip\fR\fR
  36 .ad
  37 .RS 10n
  38 Pointer to the \fBdev_info\fR structure of the devices
  39 .RE
  40
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fIdep\fR\fR
  45 .ad
  46 .RS 10n
  47 Pointer to DDI error status
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fIstatus\fR\fR
  54 .ad
  55 .RS 10n
  56 Pointer to status bit storage location
  57 .RE
  58
  59 .SH DESCRIPTION
  60 .LP
  61 The \fBpci_ereport_setup()\fR function initializes support for error report
  62 generation and sets up the resources for subsequent access to \fBPCI\fR,
  63 \fBPCI/X\fR or \fBPCI Express Configuration\fR space. The caller must have
  64 established a fault management capability level of at least
  65 \fBDDI_FM_EREPORT_CAPABLE\fR with a previous call to \fBddi_fm_init()\fR for
  66 \fIdip\fR.
  67 .sp
  68 .LP
  69 The \fBpci_ereport_teardown()\fR function releases any resources allocated and
  70 set up by \fBpci_ereport_setup()\fR and associated with \fIdip\fR.
  71 .sp
  72 .LP
  73 The \fBpci_ereport_post()\fR function is called to scan for and post any
  74 \fBPCI\fR, \fBPCI/X\fR or \fBPCI Express Bus\fR errors. On a \fBPCI\fR bus, for
  75 example, the errors detected include:
  76 .RS +4
  77 .TP
  78 .ie t \(bu
  79 .el o
  80 Detected Parity Error
  81 .RE
  82 .RS +4
  83 .TP
  84 .ie t \(bu
  85 .el o
  86 Master Data Parity Error
  87 .RE
  88 .RS +4
  89 .TP
  90 .ie t \(bu
  91 .el o
  92 Target Abort
  93 .RE
  94 .RS +4
  95 .TP
  96 .ie t \(bu
  97 .el o
  98 Master Abort
  99 .RE
 100 .RS +4
 101 .TP
 102 .ie t \(bu
 103 .el o
 104 System Error
 105 .RE
 106 .RS +4
 107 .TP
 108 .ie t \(bu
 109 .el o
 110 Discard Timeout
 111 .RE
 112 .sp
 113 .LP
 114 The \fBpci_ereport_post()\fR function must be called only from a driver's error
 115 handler callback function. See \fBddi_fm_handler_register\fR(9F). The
 116 \fIerror_status\fR argument to the error handler callback function should be
 117 passed through as the \fIdep\fR argument to \fBpci_ereport_post()\fR as it may
 118 contain bus specific information that might be useful for handling any errors
 119 that are discovered.
 120 .sp
 121 .LP
 122 The \fBfme_flag\fR in the \fBerror_status\fR argument to the error handler
 123 callback function will contain one of the following:
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBDDI_FM_ERR_UNEXPECTED()\fR\fR
 128 .ad
 129 .RS 27n
 130 Any errors discovered are unexpected.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBDDI_FM_ERR_EXPECTED()\fR\fR
 137 .ad
 138 .RS 25n
 139 Errors discovered were the result of a \fBDDI_ACC_CAUTIOUS\fR operation.
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBDDI_FM_ERR_POKE()\fR\fR
 146 .ad
 147 .RS 25n
 148 Errors discovered are the result of a \fBddi_poke\fR(9F) operation.
 149 .RE
 150
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fBDDI_FM_ERR_PEEK()\fR\fR
 155 .ad
 156 .RS 25n
 157 Errors discovered are the result of a \fBddi_peek\fR(9F) operation.
 158 .RE
 159
 160 .sp
 161 .LP
 162 Error report events are generated automatically if \fBfme_flag\fR is set to
 163 \fBDDI_FM_ERR_UNEXPECTED\fR and the corresponding error bits are set in the
 164 various \fBPCI\fR, \fBPCI/X\fR or \fBPCI Express Bus\fR error registers of the
 165 device associated with \fIdip\fR. The generated error report events are posted
 166 to the Solaris Fault Manager, \fBfmd\fR(1M), for diagnosis.
 167 .sp
 168 .LP
 169 If the status argument is non-null, \fBpci_ereport_post()\fR saves the contents
 170 of the \fBPCI Configuration Status Register\fR to \fB*status\fR. If it is not
 171 possible to read the \fBPCI Configuration Status Register\fR, \fB-1\fR is
 172 returned in \fB*status\fR instead.
 173 .sp
 174 .LP
 175 On return from the call to \fBpci_ereport_post()\fR, the \fBddi_fm_error_t\fR
 176 structure pointed at by \fIdep\fR will have been updated, and the
 177 \fBfme_status\fR field contains one of the following values:
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fBDDI_FM_OK\fR\fR
 182 .ad
 183 .RS 19n
 184 No errors were detected which might affect this device instance.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBDDI_FM_FATAL\fR\fR
 191 .ad
 192 .RS 19n
 193 An error which is considered fatal to the operational state of the system was
 194 detected.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fBDDI_FM_NONFATAL\fR\fR
 201 .ad
 202 .RS 19n
 203 An error which is not considered fatal to the operational state of the system
 204 was detected. The \fBfme_acc_handle\fR or \fBfme_dma_handle\fR fields in the
 205 returned \fBddi_fm_error_t\fR structure will typically reference a handle that
 206 belongs to the device instance that has been affected.
 207 .RE
 208
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fBDDI_FM_UNKNOWN\fR\fR
 213 .ad
 214 .RS 19n
 215 An error was detected, but the call was unable to determine the impact of the
 216 error on the operational state of the system. This is treated the same way as
 217 \fBDDI_FM_FATAL\fR unless some other device is able to evaluate the fault to be
 218 \fBDDI_FM_NONFATAL\fR.
 219 .RE
 220
 221 .SH CONTEXT
 222 .LP
 223 The \fBpci_ereport_setup()\fR and \fBpci_ereport_teardown()\fR functions must
 224 be called from user or kernel context.
 225 .sp
 226 .LP
 227 The \fBpci_ereport_post()\fR function can be called in any context.
 228 .SH EXAMPLES
 229 .in +2
 230 .nf
 231 int xxx_fmcap = DDI_FM_EREPORT_CAPABLE | DDI_FM_ERRCB_CAPABLE;
 232
 233 xxx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd) {
 234
 235       ddi_fm_init(dip, &xxx_fmcap, &xxx_ibc);
 236       if (xxx_fmcap & DDI_FM_ERRCB_CAPABLE)
 237          ddi_fm_handler_register(dip, xxx_err_cb);
 238       if (xxx_fmcap & DDI_FM_EREPORT_CAPABLE)
 239          pci_ereport_setup(dip);
 240
 241 }
 242
 243 xxx_err_cb(dev_info_t *dip, ddi_fm_error_t *errp) {
 244      uint16_t status;
 245
 246      pci_ereport_post(dip, errp, &status);
 247      return (errp->fme_status);
 248 }
 249
 250 xxx_detach(dev_info_t *dip, ddi_attach_cmd_t cmd) {
 251
 252      if (xxx_fmcap & DDI_FM_EREPORT_CAPABLE)
 253          pci_ereport_teardown(dip);
 254      if (xxx_fmcap & DDI_FM_ERRCB_CAPABLE)
 255          ddi_fm_handler_unregister(dip);
 256      ddi_fm_fini(dip);
 257
 258 }
 259 .fi
 260 .in -2
 261
 262 .SH ATTRIBUTES
 263 .LP
 264 See \fBattributes\fR(5) for descriptions of the following attributes:
 265 .sp
 266
 267 .sp
 268 .TS
 269 box;
 270 c | c
 271 l | l .
 272 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 273 _
 274 Interface Stability     Committed
 275 .TE
 276
 277 .SH SEE ALSO
 278 .LP
 279 \fBfmd\fR(1M), \fBattributes\fR(5), \fBddi_fm_handler_register\fR(9F),
 280 \fBddi_fm_init\fR(9F), \fBddi_peek\fR(9F), \fBddi_poke\fR(9F),
 281 \fBddi_fm_error\fR(9S)