usr/src/man/man9f/ddi_fm_init.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_INIT 9F "May 14, 2007"
   7 .SH NAME
   8 ddi_fm_init, ddi_fm_fini, ddi_fm_capable \- initialize and get the FM
   9 capabilities for a device instance
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddifm.h>
  14
  15 \fBvoid\fR \fBddi_fm_init\fR(\fBdev_info_t\fR *\fIdip\fR, \fBint\fR *\fIfm_capability\fR,
  16      \fBddi_iblock_cookie_t\fR *\fIibcp\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid\fR \fBddi_fm_fini\fR(\fBdev_info_t\fR *\fIdip\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBddi_fm_capable\fR(\fBdev_info_t\fR *\fIdip\fR, \fBint\fR *\fIfm_capability\fR);
  27 .fi
  28
  29 .SH INTERFACE LEVEL
  30 .sp
  31 .LP
  32 Solaris DDI specific (Solaris DDI)
  33 .SH PARAMETERS
  34 .sp
  35 .LP
  36 \fBddi_fm_init()\fR
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fIdip\fR\fR
  41 .ad
  42 .RS 17n
  43 Pointer to the \fBdev_info\fR structure
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIfm_capability\fR\fR
  50 .ad
  51 .RS 17n
  52 Fault Management capability bit mask
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fIibcp\fR\fR
  59 .ad
  60 .RS 17n
  61 Pointer to where the interrupt block cookie should be returned.
  62 .RE
  63
  64 .SH DESCRIPTION
  65 .sp
  66 .LP
  67 A device driver can declare its fault management capabilities to the \fBI/O\fR
  68 Fault Management framework by calling \fBddi_fm_init()\fR. The
  69 \fBddi_fm_init()\fR function allocates and initializes resources according to
  70 the bitwise-inclusive-OR of the fault management capabilities, described in the
  71 following and supported by the driver's immediate nexus parent.
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBDDI_FM_NOT_CAPABLE\fR\fR
  76 .ad
  77 .RS 26n
  78 The driver does not support any \fBFMA\fR features. This is the default value
  79 assigned to device drivers.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBDDI_FM_EREPORT_CAPABLE\fR\fR
  86 .ad
  87 .RS 26n
  88 The driver generates \fBFMA\fR protocol error events (\fBereports\fR) upon the
  89 detection of an error condition.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBDDI_FM_ACCCHK_CAPABLE\fR\fR
  96 .ad
  97 .RS 26n
  98 The driver checks for errors upon the completion of one or more access
  99 \fBI/O\fR transactions.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBDDI_FM_DMACHK_CAPABLE\fR\fR
 106 .ad
 107 .RS 26n
 108 The driver checks for errors upon the completion of one or more \fBDMA\fR
 109 \fBI/O\fR transactions.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBDDI_FM_ERRCB_CAPABLE\fR\fR
 116 .ad
 117 .RS 26n
 118 The driver is capable of error handler callback registration.
 119 .RE
 120
 121 .sp
 122 .LP
 123 If the parent nexus is not capable of supporting any one of the requested
 124 capabilities, the associated bit will not be set and returned as such to the
 125 driver. Before returning from \fBddi_fm_init()\fR, the \fBI/O\fR Fault
 126 Management framework creates a set of fault management capability properties:
 127 \fBfm-ereport-capable\fR, \fBfm-errcb-capable\fR, \fBfm-accchk-capable\fR, and
 128 \fBfm-dmachk-capable\fR. The current supported fault management capability
 129 levels are observable via \fBprtconf\fR(1M).
 130 .sp
 131 .LP
 132 A driver can support the administrative selection of fault management
 133 capabilities by exporting and setting a fault management capability level
 134 property in its \fBdriver.conf\fR(4) file to the values described above. The
 135 \fBfm_capable\fR properties must be set and read prior to calling
 136 \fBddi_fm_init()\fR with the desired capability list.
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBddi_fm_fini()\fR\fR
 141 .ad
 142 .RS 17n
 143 This function cleans up resources allocated to support fault management for the
 144 \fIdip\fR structure.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBddi_fm_capable()\fR\fR
 151 .ad
 152 .RS 20n
 153 This function returns the capability bit mask currently set for the \fIdip\fR
 154 structure.
 155 .RE
 156
 157 .SH CONTEXT
 158 .sp
 159 .LP
 160 These functions can be called from kernel context in a driver \fBattach\fR(9E)
 161 or \fBdetach\fR(9E) operation.
 162 .SH ATTRIBUTES
 163 .sp
 164 .LP
 165 See \fBattributes\fR(5) for descriptions of the following attributes:
 166 .sp
 167
 168 .sp
 169 .TS
 170 box;
 171 c | c
 172 l | l .
 173 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 174 _
 175 Interface Stability     Committed
 176 .TE
 177
 178 .SH SEE ALSO
 179 .sp
 180 .LP
 181 \fBprtconf\fR(1M), \fBdriver.conf\fR(4), \fBattributes\fR(5), \fBattach\fR(9E),
 182 \fBdetach\fR(9E)
 183 .sp
 184 .LP
 185 \fIWriting Device Drivers\fR