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

   1 '\" te
   2 .\" Copyright (c) 2008, 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_ALLOC 9F "Apr 23, 2008"
   7 .SH NAME
   8 ddi_intr_alloc, ddi_intr_free \- allocate or free interrupts for a given
   9 interrupt type
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/types.h>
  14 #include <sys/conf.h>
  15 #include <sys/ddi.h>
  16 #include <sys/sunddi.h>
  17
  18 \fBint\fR \fBddi_intr_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_intr_handle_t *\fR\fIh_array\fR, \fBint\fR \fItype\fR,
  19      \fBint\fR \fIinum\fR, \fBint\fR \fIcount\fR, \fBint *\fR\fIactualp\fR, \fBint\fR \fIbehavior\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBddi_intr_free\fR(\fBddi_intr_handle_t\fR \fIh\fR);
  25 .fi
  26
  27 .SH INTERFACE LEVEL
  28 .sp
  29 .LP
  30 Solaris DDI specific (Solaris DDI).
  31 .SH PARAMETERS
  32 .sp
  33 .LP
  34 \fBddi_intr_alloc()\fR
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIdip\fR\fR
  39 .ad
  40 .RS 12n
  41 Pointer to the \fBdev_info\fR structure
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIh_array\fR\fR
  48 .ad
  49 .RS 12n
  50 Pointer to an array of DDI interrupt handles
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fItype\fR\fR
  57 .ad
  58 .RS 12n
  59 Interrupt type
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fIinum\fR\fR
  66 .ad
  67 .RS 12n
  68 Interrupt number
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fIcount\fR\fR
  75 .ad
  76 .RS 12n
  77 Number of interrupts requested. The \fIcount\fR should not exceed the total
  78 number of interrupts supported by the device, as returned by a call to
  79 \fBddi_intr_get_nintrs\fR(9F).
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fIactualp\fR\fR
  86 .ad
  87 .RS 12n
  88 Pointer to the number of interrupts actually allocated
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fIbehavior\fR\fR
  95 .ad
  96 .RS 12n
  97 Flag to determine the allocation algorithm
  98 .RE
  99
 100 .sp
 101 .LP
 102 \fBddi_intr_free()\fR
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fIh\fR\fR
 107 .ad
 108 .RS 5n
 109 DDI interrupt handle
 110 .RE
 111
 112 .SH DESCRIPTION
 113 .sp
 114 .LP
 115 The \fBddi_intr_alloc()\fR function allocates interrupts of the interrupt type
 116 given by the \fItype\fR argument beginning at the interrupt number \fIinum\fR.
 117 If \fBddi_intr_alloc()\fR allocates any interrupts, it returns the actual
 118 number of interrupts allocated in the integer pointed to by the \fIactualp\fR
 119 argument and returns the number of interrupt handles in the interrupt handle
 120 array pointed to by the \fIh_array\fR argument.
 121 .sp
 122 .LP
 123 Specific interrupts are always specified by the combination of interrupt
 124 \fItype\fR and \fIinum\fR. For legacy devices, \fIinum\fR refers to the nth
 125 interrupt, typically as defined by the devices \fBinterrupts\fR property. For
 126 PCI fixed interrupts, \fIinum\fR refers to the interrupt number. The \fIinum\fR
 127 is the relative interrupt vector number, from \fB0\fR to \fB31\fR for MSI, from
 128 \fB0\fR to \fB2047\fR for MSI-X. The first interrupt vector is \fB0\fR. The
 129 last relative vector is \fB31\fR for MSI or \fB2047\fR for MSI-X.
 130 .sp
 131 .LP
 132 The \fIh_array\fR must be pre-allocated by the caller as a \fIcount\fR sized
 133 array of ddi_intr_handle_t's.
 134 .sp
 135 .LP
 136 If MSI interrupts are being allocated, the \fIcount\fR argument passed should
 137 be a number between \fB1\fR and \fB32\fR, specified as a power of two. If
 138 \fIcount\fR is not specified as a power of two, the error \fBDDI_EINVAL\fR is
 139 returned.
 140 .sp
 141 .LP
 142 The behavior flag controls the interrupt allocation algorithm. It takes one of
 143 two input values: \fBDDI_INTR_ALLOC_NORMAL\fR or \fBDDI_INTR_ALLOC_STRICT\fR.
 144 If the \fIcount\fR value used is greater than \fBNINTRs\fR, then the call fails
 145 with \fBDDI_EINVAL\fR unconditionally. When set to \fBDDI_INTR_ALLOC_STRICT\fR,
 146 the call succeeds if and only if \fIcount\fR interrupts are allocated.
 147 Otherwise, the call fails, and the number of available interrupts is returned
 148 in \fIactualp\fR. When set to \fBDDI_INTR_ALLOC_NORMAL\fR, the call succeeds if
 149 at least one interrupt is allocated, and the number of allocated interrupts is
 150 returned in actualp.
 151 .sp
 152 .LP
 153 The handle for each allocated interrupt, if any, is returned in the array of
 154 handles given by the \fIh_array\fR argument.
 155 .sp
 156 .LP
 157 The \fBddi_intr_free()\fR function releases the system resources and interrupt
 158 vectors associated with the ddi_intr_handle_t \fIh\fR, including any resources
 159 associated with the handle \fIh\fR itself. Once freed, the handle \fIh\fR
 160 should not be used in any further calls.
 161 .sp
 162 .LP
 163 The \fBddi_intr_free()\fR function should be called once for each handle in the
 164 handle array.
 165 .SH RETURN VALUES
 166 .sp
 167 .LP
 168 The \fBddi_intr_alloc()\fR and \fBddi_intr_free()\fR functions return:
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBDDI_SUCCESS\fR\fR
 173 .ad
 174 .RS 21n
 175 On success.
 176 .RE
 177
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fBDDI_EAGAIN\fR\fR
 182 .ad
 183 .RS 21n
 184 Not enough interrupt resources.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBDDI_EINVAL\fR\fR
 191 .ad
 192 .RS 21n
 193 On encountering invalid input parameters.
 194 .RE
 195
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBDDI_INTR_NOTFOUND\fR\fR
 200 .ad
 201 .RS 21n
 202 On failure to find the interrupt.
 203 .RE
 204
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBDDI_FAILURE\fR\fR
 209 .ad
 210 .RS 21n
 211 On any implementation specific failure.
 212 .RE
 213
 214 .SH CONTEXT
 215 .sp
 216 .LP
 217 The \fBddi_intr_alloc()\fR and \fBddi_intr_free()\fR functions can be called
 218 from kernel non-interrupt context.
 219 .SH ATTRIBUTES
 220 .sp
 221 .LP
 222 See \fBattributes\fR(5) for descriptions of the following attributes:
 223 .sp
 224
 225 .sp
 226 .TS
 227 box;
 228 c | c
 229 l | l .
 230 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 231 _
 232 Interface Stability     Committed
 233 .TE
 234
 235 .SH SEE ALSO
 236 .sp
 237 .LP
 238 \fBattributes\fR(5), \fBddi_intr_add_handler\fR(9F),
 239 \fBddi_intr_block_enable\fR(9F), \fBddi_intr_disable\fR(9F),
 240 \fBddi_intr_enable\fR(9F), \fBddi_intr_get_cap\fR(9F),
 241 \fBddi_intr_get_nintrs\fR(9F), \fBddi_intr_get_pri\fR(9F),
 242 \fBddi_intr_get_supported_types\fR(9F), \fBddi_intr_remove_handler\fR(9F)
 243 .sp
 244 .LP
 245 \fIWriting Device Drivers\fR
 246 .SH NOTES
 247 .sp
 248 .LP
 249 Consumers of these interfaces should verify that the return value is not equal
 250 to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in
 251 inconsistent behavior among platforms.
 252 .sp
 253 .LP
 254 If a device driver that uses \fBMSI\fR and \fBMSI-X\fR interrupts resets the
 255 device, the device might reset its configuration space modifications. Such a
 256 reset could cause a device driver to lose any \fBMSI\fR and \fBMSI-X\fR
 257 interrupt usage settings that have been applied.