share/man/man9f/ddi_fm_handler_register.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 DDI_FM_HANDLER_REGISTER 9F "May 14, 2007"
   7 .SH NAME
   8 ddi_fm_handler_register, ddi_fm_handler_unregister \- register or unregister an
   9 error handling callback
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddifm.h>
  14
  15 \fBvoid\fR \fBddi_fm_handler_register\fR(\fBdev_info_t\fR *\fIdip\fR,
  16      \fBddi_err_func_t\fR \fIerror_handler\fR, \fBvoid\fR *\fIimpl_data\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid\fR \fBddi_fm_handler_unregister\fR(\fBdev_info_t\fR *\fIdip\fR);
  22 .fi
  23
  24 .SH INTERFACE LEVEL
  25 .sp
  26 .LP
  27 Solaris DDI specific (Solaris DDI)
  28 .SH PARAMETERS
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fIdip\fR\fR
  33 .ad
  34 .RS 17n
  35 Pointer to the \fBdev_info\fR structure
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIerror_handler\fR\fR
  42 .ad
  43 .RS 17n
  44 Pointer to an error handler callback function
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fIimpl_data\fR\fR
  51 .ad
  52 .RS 17n
  53 Pointer to private data for use by the caller
  54 .RE
  55
  56 .SH DESCRIPTION
  57 .sp
  58 .LP
  59 The \fBddi_fm_handler_register()\fR function registers an error handler
  60 callback routine with the \fBI/O\fR Fault Management framework. The error
  61 handler callback, \fIerror_handler\fR, is called to process error conditions
  62 detected by the system. In addition to its device instance, \fIdip\fR, the
  63 error handler is called with a pointer to a fault management error status
  64 structure, \fBddi_fm_error_t\fR. For example:
  65 .sp
  66 .in +2
  67 .nf
  68 int (*ddi_err_func_t)(dev_info_t *dip, ddi_fm_error_t *error_status);
  69 .fi
  70 .in -2
  71
  72 .sp
  73 .LP
  74 A driver error handling callback is passed the following arguments:
  75 .RS +4
  76 .TP
  77 .ie t \(bu
  78 .el o
  79 a pointer to the device instance registered for this callback.
  80 .RE
  81 .RS +4
  82 .TP
  83 .ie t \(bu
  84 .el o
  85 a data structure containing common fault management data and status for error
  86 handling.
  87 .RE
  88 .sp
  89 .LP
  90 The primary responsibilities of the error handler include:
  91 .RS +4
  92 .TP
  93 .ie t \(bu
  94 .el o
  95 to check for outstanding hardware or software errors.
  96 .RE
  97 .RS +4
  98 .TP
  99 .ie t \(bu
 100 .el o
 101 where possible, to isolate the device that might have caused the errors.
 102 .RE
 103 .RS +4
 104 .TP
 105 .ie t \(bu
 106 .el o
 107 to report errors that were detected.
 108 .RE
 109 .sp
 110 .LP
 111 During the invocation of an error handler, a device driver  might need to
 112 quiesce or suspend all \fBI/O\fR activities in order to check for error
 113 conditions or status in:
 114 .RS +4
 115 .TP
 116 .ie t \(bu
 117 .el o
 118 hardware control and status registers.
 119 .RE
 120 .RS +4
 121 .TP
 122 .ie t \(bu
 123 .el o
 124 outstanding \fBI/O\fR transactions.
 125 .RE
 126 .RS +4
 127 .TP
 128 .ie t \(bu
 129 .el o
 130 access or \fBDMA\fR handles.
 131 .RE
 132 .sp
 133 .LP
 134 For each error detected, the driver must formulate and post an error report via
 135 \fBddi_fm_ereport_post()\fR for problem analysis by the Solaris Fault Manager
 136 \fBfmd\fR(8).
 137 .sp
 138 .LP
 139 For a \fBPCI\fR, \fBPCI/X\fR, or \fBPCI Express\fR leaf device, the
 140 \fBpci_ereport_post()\fR function is provided to carry out reporting
 141 responsibilities on behalf of the driver. In many cases, an error handler
 142 callback function of the following form can be used:
 143 .sp
 144 .in +2
 145 .nf
 146 xxx_err_cb(dev_info_t *dip, ddi_fm_error_t *errp) {
 147       pci_ereport_post(dip, errp, NULL);
 148       return (errp->fme_status);
 149 }
 150 .fi
 151 .in -2
 152
 153 .sp
 154 .LP
 155 In addition, the driver might be able to carry out further device specific
 156 checks within the error handler.
 157 .sp
 158 .LP
 159 Error handlers can be called from kernel, interrupt, or high-level interrupt
 160 context. The interrupt block cookie returned from \fBddi_fm_init()\fR should be
 161 used to allocate and initialize any synchronization variables and locks that
 162 might be used within the error handler callback function. Such locks may not be
 163 held by the driver when a device register is accessed with functions such as
 164 \fBddi_get8\fR(9F) and \fBddi_put8\fR(9F).
 165 .sp
 166 .LP
 167 The data structure, \fBddi_fm_error_t\fR, contains an \fBFMA\fR protocol
 168 (format 1) \fBENA\fR for the current error propagation chain, the status of the
 169 error handler callback, an error expectation flag, and any potential access or
 170 \fBDMA\fR handles associated with an error detected by the parent nexus.
 171 .sp
 172 .LP
 173 The \fBddi_fm_handler_unregister()\fR function removes a previously registered
 174 error handling callback for the device instance specified by the \fIdip\fR.
 175 .SH CONTEXT
 176 .sp
 177 .LP
 178 The \fBddi_fm_handler_register()\fR and \fBddi_fm_handler_unregister()\fR
 179 functions must be called from kernel context in an \fBattach\fR(9E) or
 180 \fBdetach\fR(9E) entry point. The registered error handler,
 181 \fIerror_handler\fR, callback can be called from kernel, interrupt, or high
 182 level interrupt context.
 183 .SH ATTRIBUTES
 184 .sp
 185 .LP
 186 See \fBattributes\fR(5) for descriptions of the following attributes:
 187 .sp
 188
 189 .sp
 190 .TS
 191 box;
 192 c | c
 193 l | l .
 194 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 195 _
 196 Interface Stability     Committed
 197 .TE
 198
 199 .SH SEE ALSO
 200 .sp
 201 .LP
 202 \fBfmd\fR(8), \fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E),
 203 \fBddi_fm_ereport_post\fR(9F), \fBddi_fm_init\fR(9F), \fBddi_get8\fR(9F),
 204 \fBddi_put8\fR(9F), \fBpci_ereport_post\fR(9F), \fBddi_fm_error\fR(9S)
 205 .sp
 206 .LP
 207 \fIWriting Device Drivers\fR