'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH PCI_EREPORT_SETUP 9F "Mar 27, 2016"
.SH NAME
pci_ereport_setup, pci_ereport_teardown, pci_ereport_post \- post error reports
for the generic PCI errors logged in the PCI Configuration Status register.
.SH SYNOPSIS
.nf
#include <sys/sunddi.h>

\fBvoid\fR \fBpci_ereport_setup\fR(\fBdev_info_t\fR *\fIdip\fR);
.fi

.LP
.nf
\fBvoid\fR \fBpci_ereport_teardown\fR(\fBdev_info_t\fR *\fIdip\fR);
.fi

.LP
.nf
\fBvoid\fR \fBpci_ereport_post\fR(\fBdev_info_t\fR *\fIdip\fR, \fBddi_fm_error_t\fR *\fIdep\fR,
     \fBuin16_t\fR *\fIstatus\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI)
.SH PARAMETERS
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 10n
Pointer to the \fBdev_info\fR structure of the devices
.RE

.sp
.ne 2
.na
\fB\fIdep\fR\fR
.ad
.RS 10n
Pointer to DDI error status
.RE

.sp
.ne 2
.na
\fB\fIstatus\fR\fR
.ad
.RS 10n
Pointer to status bit storage location
.RE

.SH DESCRIPTION
The \fBpci_ereport_setup()\fR function initializes support for error report
generation and sets up the resources for subsequent access to \fBPCI\fR,
\fBPCI/X\fR or \fBPCI Express Configuration\fR space. The caller must have
established a fault management capability level of at least
\fBDDI_FM_EREPORT_CAPABLE\fR with a previous call to \fBddi_fm_init()\fR for
\fIdip\fR.
.sp
.LP
The \fBpci_ereport_teardown()\fR function releases any resources allocated and
set up by \fBpci_ereport_setup()\fR and associated with \fIdip\fR.
.sp
.LP
The \fBpci_ereport_post()\fR function is called to scan for and post any
\fBPCI\fR, \fBPCI/X\fR or \fBPCI Express Bus\fR errors. On a \fBPCI\fR bus, for
example, the errors detected include:
.RS +4
.TP
.ie t \(bu
.el o
Detected Parity Error
.RE
.RS +4
.TP
.ie t \(bu
.el o
Master Data Parity Error
.RE
.RS +4
.TP
.ie t \(bu
.el o
Target Abort
.RE
.RS +4
.TP
.ie t \(bu
.el o
Master Abort
.RE
.RS +4
.TP
.ie t \(bu
.el o
System Error
.RE
.RS +4
.TP
.ie t \(bu
.el o
Discard Timeout
.RE
.sp
.LP
The \fBpci_ereport_post()\fR function must be called only from a driver's error
handler callback function. See \fBddi_fm_handler_register\fR(9F). The
\fIerror_status\fR argument to the error handler callback function should be
passed through as the \fIdep\fR argument to \fBpci_ereport_post()\fR as it may
contain bus specific information that might be useful for handling any errors
that are discovered.
.sp
.LP
The \fBfme_flag\fR in the \fBerror_status\fR argument to the error handler
callback function will contain one of the following:
.sp
.ne 2
.na
\fB\fBDDI_FM_ERR_UNEXPECTED()\fR\fR
.ad
.RS 27n
Any errors discovered are unexpected.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FM_ERR_EXPECTED()\fR\fR
.ad
.RS 25n
Errors discovered were the result of a \fBDDI_ACC_CAUTIOUS\fR operation.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FM_ERR_POKE()\fR\fR
.ad
.RS 25n
Errors discovered are the result of a \fBddi_poke\fR(9F) operation.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FM_ERR_PEEK()\fR\fR
.ad
.RS 25n
Errors discovered are the result of a \fBddi_peek\fR(9F) operation.
.RE

.sp
.LP
Error report events are generated automatically if \fBfme_flag\fR is set to
\fBDDI_FM_ERR_UNEXPECTED\fR and the corresponding error bits are set in the
various \fBPCI\fR, \fBPCI/X\fR or \fBPCI Express Bus\fR error registers of the
device associated with \fIdip\fR. The generated error report events are posted
to the illumos Fault Manager, \fBfmd\fR(8), for diagnosis.
.sp
.LP
If the status argument is non-null, \fBpci_ereport_post()\fR saves the contents
of the \fBPCI Configuration Status Register\fR to \fB*status\fR. If it is not
possible to read the \fBPCI Configuration Status Register\fR, \fB-1\fR is
returned in \fB*status\fR instead.
.sp
.LP
On return from the call to \fBpci_ereport_post()\fR, the \fBddi_fm_error_t\fR
structure pointed at by \fIdep\fR will have been updated, and the
\fBfme_status\fR field contains one of the following values:
.sp
.ne 2
.na
\fB\fBDDI_FM_OK\fR\fR
.ad
.RS 19n
No errors were detected which might affect this device instance.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FM_FATAL\fR\fR
.ad
.RS 19n
An error which is considered fatal to the operational state of the system was
detected.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FM_NONFATAL\fR\fR
.ad
.RS 19n
An error which is not considered fatal to the operational state of the system
was detected. The \fBfme_acc_handle\fR or \fBfme_dma_handle\fR fields in the
returned \fBddi_fm_error_t\fR structure will typically reference a handle that
belongs to the device instance that has been affected.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FM_UNKNOWN\fR\fR
.ad
.RS 19n
An error was detected, but the call was unable to determine the impact of the
error on the operational state of the system. This is treated the same way as
\fBDDI_FM_FATAL\fR unless some other device is able to evaluate the fault to be
\fBDDI_FM_NONFATAL\fR.
.RE

.SH CONTEXT
The \fBpci_ereport_setup()\fR and \fBpci_ereport_teardown()\fR functions must
be called from user or kernel context.
.sp
.LP
The \fBpci_ereport_post()\fR function can be called in any context.
.SH EXAMPLES
.in +2
.nf
int xxx_fmcap = DDI_FM_EREPORT_CAPABLE | DDI_FM_ERRCB_CAPABLE;

xxx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd) {

      ddi_fm_init(dip, &xxx_fmcap, &xxx_ibc);
      if (xxx_fmcap & DDI_FM_ERRCB_CAPABLE)
         ddi_fm_handler_register(dip, xxx_err_cb);
      if (xxx_fmcap & DDI_FM_EREPORT_CAPABLE)
         pci_ereport_setup(dip);

}

xxx_err_cb(dev_info_t *dip, ddi_fm_error_t *errp) {
     uint16_t status;

     pci_ereport_post(dip, errp, &status);
     return (errp->fme_status);
}

xxx_detach(dev_info_t *dip, ddi_attach_cmd_t cmd) {

     if (xxx_fmcap & DDI_FM_EREPORT_CAPABLE)
         pci_ereport_teardown(dip);
     if (xxx_fmcap & DDI_FM_ERRCB_CAPABLE)
         ddi_fm_handler_unregister(dip);
     ddi_fm_fini(dip);

}
.fi
.in -2

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.BR attributes (7),
.BR fmd (8),
.BR ddi_fm_handler_register (9F),
.BR ddi_fm_init (9F),
.BR ddi_peek (9F),
.BR ddi_poke (9F),
.BR ddi_fm_error (9S)