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]
 PCI_EREPORT_SETUP 9F "Mar 27, 2016"
 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.

 SYNOPSIS
#include <sys/sunddi.h>

void pci_ereport_setup(dev_info_t *dip);






void pci_ereport_teardown(dev_info_t *dip);






void pci_ereport_post(dev_info_t *dip, ddi_fm_error_t *dep,
 uin16_t *status);




 INTERFACE LEVEL
illumos DDI specific (illumos DDI)

 PARAMETERS
dip


Pointer to the dev_info structure of the devices



dep


Pointer to DDI error status



status


Pointer to status bit storage location




 DESCRIPTION
The pci_ereport_setup() function initializes support for error report
generation and sets up the resources for subsequent access to PCI,
PCI/X or PCI Express Configuration space. The caller must have
established a fault management capability level of at least
DDI_FM_EREPORT_CAPABLE with a previous call to ddi_fm_init() for
dip.


The pci_ereport_teardown() function releases any resources allocated and
set up by pci_ereport_setup() and associated with dip.


The pci_ereport_post() function is called to scan for and post any
PCI, PCI/X or PCI Express Bus errors. On a PCI bus, for
example, the errors detected include:




Detected Parity Error






Master Data Parity Error






Target Abort






Master Abort






System Error






Discard Timeout




The pci_ereport_post() function must be called only from a driver's error
handler callback function. See ddi_fm_handler_register(9F). The
error_status argument to the error handler callback function should be
passed through as the dep argument to pci_ereport_post() as it may
contain bus specific information that might be useful for handling any errors
that are discovered.


The fme_flag in the error_status argument to the error handler
callback function will contain one of the following:
DDI_FM_ERR_UNEXPECTED()


Any errors discovered are unexpected.



DDI_FM_ERR_EXPECTED()


Errors discovered were the result of a DDI_ACC_CAUTIOUS operation.



DDI_FM_ERR_POKE()


Errors discovered are the result of a ddi_poke(9F) operation.



DDI_FM_ERR_PEEK()


Errors discovered are the result of a ddi_peek(9F) operation.





Error report events are generated automatically if fme_flag is set to
DDI_FM_ERR_UNEXPECTED and the corresponding error bits are set in the
various PCI, PCI/X or PCI Express Bus error registers of the
device associated with dip. The generated error report events are posted
to the illumos Fault Manager, fmd(8), for diagnosis.


If the status argument is non-null, pci_ereport_post() saves the contents
of the PCI Configuration Status Register to *status. If it is not
possible to read the PCI Configuration Status Register, -1 is
returned in *status instead.


On return from the call to pci_ereport_post(), the ddi_fm_error_t
structure pointed at by dep will have been updated, and the
fme_status field contains one of the following values:
DDI_FM_OK


No errors were detected which might affect this device instance.



DDI_FM_FATAL


An error which is considered fatal to the operational state of the system was
detected.



DDI_FM_NONFATAL


An error which is not considered fatal to the operational state of the system
was detected. The fme_acc_handle or fme_dma_handle fields in the
returned ddi_fm_error_t structure will typically reference a handle that
belongs to the device instance that has been affected.



DDI_FM_UNKNOWN


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
DDI_FM_FATAL unless some other device is able to evaluate the fault to be
DDI_FM_NONFATAL.




 CONTEXT
The pci_ereport_setup() and pci_ereport_teardown() functions must
be called from user or kernel context.


The pci_ereport_post() function can be called in any context.

 EXAMPLES
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);

}




 ATTRIBUTES
See attributes(7) for descriptions of the following attributes:






ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Committed



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