Manual Pages for UNIX Operating System command usage for man pci_ereport_setup

Kernel Functions for Drivers                pci_ereport_setup(9F)



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 

     void pci_ereport_setup(dev_info_t *dip, int);


     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
     Solaris DDI specific (Solaris 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 subse-
     quent 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:

         o    Detected Parity Error

         o    Master Data Parity Error



SunOS 5.11          Last change: 10 May 2007                    1






Kernel Functions for Drivers                pci_ereport_setup(9F)



         o    Target Abort

         o    Master Abort

         o    System Error

         o    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  unex-
                                pected.


     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 gen-
     erated error report events are posted to the  Solaris  Fault
     Manager, fmd(1M), 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.





SunOS 5.11          Last change: 10 May 2007                    2






Kernel Functions for Drivers                pci_ereport_setup(9F)



     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  fol-
     lowing 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  con-
     text.

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

       }



SunOS 5.11          Last change: 10 May 2007                    3






Kernel Functions for Drivers                pci_ereport_setup(9F)



       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(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|


SEE ALSO
     fmd(1M),     attributes(5),     ddi_fm_handler_register(9F),
     ddi_fm_init(9F),         ddi_peek(9F),         ddi_poke(9F),
     ddi_fm_error(9S)




















SunOS 5.11          Last change: 10 May 2007                    4