usr/src/man/man9f/ddi_intr_enable.9f

   1 '\" te
   2 .\" Copyright (c) 2005, 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_INTR_ENABLE 9F "Apr 22, 2005"
   7 .SH NAME
   8 ddi_intr_enable, ddi_intr_block_enable, ddi_intr_disable,
   9 ddi_intr_block_disable \- enable or disable a given interrupt or range of
  10 interrupts
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/types.h>
  15 #include <sys/conf.h>
  16 #include <sys/ddi.h>
  17 #include <sys/sunddi.h>
  18
  19
  20
  21 \fBint\fR \fBddi_intr_enable\fR(\fBddi_intr_handle_t\fR \fIh\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBddi_intr_block_enable\fR(\fBddi_intr_handle_t *\fR\fIh_array\fR, \fBint\fR \fIcount\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fBddi_intr_disable\fR(\fBddi_intr_handle_t\fR \fIh\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBint\fR \fBddi_intr_block_disable\fR(\fBddi_intr_handle_t *\fR\fIh_array\fR, \fBint\fR \fIcount\fR);
  37 .fi
  38
  39 .SH INTERFACE LEVEL
  40 .sp
  41 .LP
  42 Solaris DDI specific (Solaris DDI).
  43 .SH PARAMETERS
  44 .sp
  45 .LP
  46 \fBddi_intr_enable()\fR
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fIh\fR\fR
  51 .ad
  52 .RS 5n
  53 DDI interrupt handle
  54 .RE
  55
  56 .sp
  57 .LP
  58 \fBddi_intr_block_enable()\fR
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fIh_array\fR\fR
  63 .ad
  64 .RS 11n
  65 Pointer to an array of DDI interrupt handles
  66 .RE
  67
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fIcount\fR\fR
  72 .ad
  73 .RS 11n
  74 Number of interrupts
  75 .RE
  76
  77 .sp
  78 .LP
  79 \fBddi_intr_disable()\fR
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fIh\fR\fR
  84 .ad
  85 .RS 5n
  86 DDI interrupt handle
  87 .RE
  88
  89 .sp
  90 .LP
  91 \fBddi_intr_block_disable()\fR
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fIh_array\fR\fR
  96 .ad
  97 .RS 11n
  98 Pointer to an array of DDI interrupt handles
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fIcount\fR\fR
 105 .ad
 106 .RS 11n
 107 Number of interrupts
 108 .RE
 109
 110 .SH DESCRIPTION
 111 .sp
 112 .LP
 113 The \fBddi_intr_enable()\fR function enables the interrupt given by the
 114 interrupt handle \fIh\fR.
 115 .sp
 116 .LP
 117 The \fBddi_intr_block_enable()\fR function enables a range of interrupts given
 118 by the \fIcount\fR and \fIh_array\fR arguments, where \fIcount\fR must be at
 119 least \fB1\fR and \fIh_array\fR is pointer to a count-sized array of interrupt
 120 handles.
 121 .sp
 122 .LP
 123 The \fBddi_intr_block_enable()\fR function can be used only if the device or
 124 host bridge supports the block enable/disable feature. The
 125 \fBddi_intr_get_cap()\fR function returns the \fBRO\fR flag
 126 \fBDDI_INTR_FLAG_BLOCK\fR if the device or host bridge supports the interrupt
 127 block enable/disable feature for the given interrupt type. The
 128 \fBddi_intr_block_enable()\fR function is useful for enabling MSI interrupts
 129 when the optional per-vector masking capability is not supported.
 130 .sp
 131 .LP
 132 The \fBddi_intr_enable()\fR or \fBddi_intr_block_enable()\fR functions must be
 133 called after the required interrupt resources are allocated with
 134 \fBddi_intr_alloc()\fR, the interrupt handlers are added through
 135 \fBddi_intr_add_handler()\fR, and the required locks are initialized by
 136 \fBmutex\fR(9F) or \fBrwlock\fR(9F).
 137 .sp
 138 .LP
 139 Once enabled by either of the enable calls, the interrupt can be taken and
 140 passed to the driver's interrupt service routine. Enabling an interrupt implies
 141 clearing any system or device mask bits associated with the interrupt.
 142 .sp
 143 .LP
 144 The \fBddi_intr_disable()\fR function disables the interrupt given by the
 145 interrupt handle \fIh\fR.
 146 .sp
 147 .LP
 148 The \fBddi_intr_block_disable()\fR function disables a range of interrupts
 149 given by the \fIcount\fR and \fIh_array\fR arguments, where \fIcount\fR must be
 150 at least \fB1\fR and \fIh_array\fR is pointer to a count-sized array of
 151 interrupt handles.
 152 .sp
 153 .LP
 154 The \fBddi_intr_block_disable()\fR function can be used only if the device or
 155 host bridge supports the block enable/disable feature. The
 156 \fBddi_intr_get_cap()\fR function returns the \fBRO\fR flag
 157 \fBDDI_INTR_FLAG_BLOCK\fR if the device or host bridge supports the interrupt
 158 block enable/disable feature for the given interrupt type. The
 159 \fBddi_intr_block_disable()\fR function is useful for disabling MSI interrupts
 160 when the optional per-vector masking capability is not supported.
 161 .sp
 162 .LP
 163 The \fBddi_intr_disable()\fR or \fBddi_intr_block_disable()\fR functions must
 164 be called before removing the interrupt handler and freeing the corresponding
 165 interrupt with \fBddi_intr_remove_handler()\fR and \fBddi_intr_free()\fR,
 166 respectively. The \fBddi_intr_block_disable()\fR function should be called if
 167 the \fBddi_intr_block_enable()\fR function was used to enable the interrupts.
 168 .SH RETURN VALUES
 169 .sp
 170 .LP
 171 The \fBddi_intr_enable()\fR, \fBddi_intr_block_enable()\fR,
 172 \fBddi_intr_disable()\fR, and \fBddi_intr_block_disable()\fR functions return:
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBDDI_SUCCESS\fR\fR
 177 .ad
 178 .RS 15n
 179 On success.
 180 .RE
 181
 182 .sp
 183 .ne 2
 184 .na
 185 \fB\fBDDI_EINVAL\fR\fR
 186 .ad
 187 .RS 15n
 188 On encountering invalid input parameters.
 189 .RE
 190
 191 .sp
 192 .ne 2
 193 .na
 194 \fB\fBDDI_FAILURE\fR\fR
 195 .ad
 196 .RS 15n
 197 On any implementation specific failure.
 198 .RE
 199
 200 .SH CONTEXT
 201 .sp
 202 .LP
 203 The \fBddi_intr_enable()\fR, \fBddi_intr_block_enable()\fR,
 204 \fBddi_intr_disable()\fR, and \fBddi_intr_block_disable()\fR functions can be
 205 called from kernel non-interrupt context.
 206 .SH ATTRIBUTES
 207 .sp
 208 .LP
 209 See \fBattributes\fR(5) for descriptions of the following attributes:
 210 .sp
 211
 212 .sp
 213 .TS
 214 box;
 215 c | c
 216 l | l .
 217 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 218 _
 219 Interface Stability     Committed
 220 .TE
 221
 222 .SH SEE ALSO
 223 .sp
 224 .LP
 225 \fBattributes\fR(5), \fBddi_intr_add_handler\fR(9F), \fBddi_intr_alloc\fR(9F),
 226 \fBddi_intr_dup_handler\fR(9F), \fBddi_intr_free\fR(9F),
 227 \fBddi_intr_get_cap\fR(9F), \fBddi_intr_remove_handler\fR(9F), \fBmutex\fR(9F),
 228 \fBrwlock\fR(9F)
 229 .sp
 230 .LP
 231 \fIWriting Device Drivers\fR
 232 .SH NOTES
 233 .sp
 234 .LP
 235 Consumers of these interfaces should verify that the return value is not equal
 236 to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in
 237 inconsistent behavior among platforms.
 238 .sp
 239 .LP
 240 If a device driver that uses \fBMSI\fR and \fBMSI-X\fR interrupts resets the
 241 device, the device might reset its configuration space modifications. Such a
 242 reset could cause a device driver to lose any \fBMSI\fR and \fBMSI-X\fR
 243 interrupt usage settings that have been applied.