usr/src/man/man9f/ddi_add_intr.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_ADD_INTR 9F "Oct 19, 2005"
   7 .SH NAME
   8 ddi_add_intr, ddi_get_iblock_cookie, ddi_remove_intr \- hardware interrupt
   9 handling routines
  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
  19
  20 \fBint\fR \fBddi_get_iblock_cookie\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinumber\fR,
  21       \fBddi_iblock_cookie_t *\fR\fIiblock_cookiep\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBddi_add_intr\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinumber\fR,
  27      \fBddi_iblock_cookie_t *\fR\fIiblock_cookiep\fR,
  28      \fBddi_idevice_cookie_t *\fR\fIidevice_cookiep\fR,
  29      \fBuint_t (*\fR\fIint_handler\fR) (caddr_t),
  30      \fBcaddr_t\fR \fIint_handler_arg\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBvoid\fR \fBddi_remove_intr\fR(\fBdev_info_t *\fR\fIdip\fR,
  36      \fBuint_t\fR \fIinumber\fR, \fBddi_iblock_cookie_t\fR \fIiblock_cookie\fR);
  37 .fi
  38
  39 .SH INTERFACE LEVEL
  40 .sp
  41 .LP
  42 Solaris DDI specific (Solaris DDI). These interfaces are obsolete. Use the new
  43 interrupt interfaces referenced in \fBIntro\fR(9F). Refer to \fIWriting Device
  44 Drivers\fR for more information.
  45 .SH PARAMETERS
  46 .sp
  47 .LP
  48 For \fBddi_get_iblock_cookie()\fR:
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fIdip\fR\fR
  53 .ad
  54 .RS 18n
  55 Pointer to \fBdev_info\fR structure.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fIinumber\fR\fR
  62 .ad
  63 .RS 18n
  64 Interrupt number.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fIiblock_cookiep\fR\fR
  71 .ad
  72 .RS 18n
  73 Pointer to an interrupt block cookie.
  74 .RE
  75
  76 .sp
  77 .LP
  78 For \fBddi_add_intr()\fR:
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fIdip\fR\fR
  83 .ad
  84 .RS 19n
  85 Pointer to \fBdev_info\fR structure.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fIinumber\fR\fR
  92 .ad
  93 .RS 19n
  94 Interrupt number.
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fIiblock_cookiep\fR\fR
 101 .ad
 102 .RS 19n
 103 Optional pointer to an interrupt block cookie where a returned interrupt block
 104 cookie is stored.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fIidevice_cookiep\fR\fR
 111 .ad
 112 .RS 19n
 113 Optional pointer to an interrupt device cookie where a returned interrupt
 114 device cookie is stored.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fIint_handler\fR\fR
 121 .ad
 122 .RS 19n
 123 Pointer to interrupt handler.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fIint_handler_arg\fR\fR
 130 .ad
 131 .RS 19n
 132 Argument for interrupt handler.
 133 .RE
 134
 135 .sp
 136 .LP
 137 For \fBddi_remove_intr()\fR:
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fIdip\fR\fR
 142 .ad
 143 .RS 17n
 144 Pointer to \fBdev_info\fR structure.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fIinumber\fR\fR
 151 .ad
 152 .RS 17n
 153 Interrupt number.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fIiblock_cookie\fR\fR
 160 .ad
 161 .RS 17n
 162 Block cookie which identifies the interrupt handler to be removed.
 163 .RE
 164
 165 .SH DESCRIPTION
 166 .SS "ddi_get_iblock_cookie(\|)"
 167 .sp
 168 .LP
 169 \fBddi_get_iblock_cookie()\fR retrieves the interrupt block cookie associated
 170 with a particular interrupt specification. This routine should be called before
 171 \fBddi_add_intr()\fR to retrieve the interrupt block cookie needed to
 172 initialize locks (\fBmutex\fR(9F), \fBrwlock\fR(9F)) used by the interrupt
 173 routine. The interrupt number \fIinumber\fR determines for which interrupt
 174 specification to retrieve the cookie. \fIinumber\fR is associated with
 175 information provided either by the device (see \fBsbus\fR(4)) or the hardware
 176 configuration file (see \fBsysbus\fR(4), \fBisa\fR(4), and
 177 \fBdriver.conf\fR(4)). If only one interrupt is associated with the device,
 178 \fIinumber\fR should be \fB0\fR.
 179 .sp
 180 .LP
 181 On a successful return, \fI*iblock_cookiep\fR contains information needed for
 182 initializing locks associated with the interrupt specification corresponding to
 183 \fIinumber\fR (see \fBmutex_init\fR(9F) and \fBrw_init\fR(9F)). The driver can
 184 then initialize locks acquired by the interrupt routine before calling
 185 \fBddi_add_intr()\fR which prevents a possible race condition where the
 186 driver's interrupt handler is called immediately \fBafter\fR the driver has
 187 called \fBddi_add_intr()\fR but \fBbefore\fR the driver has initialized the
 188 locks. This may happen when an interrupt for a different device occurs on the
 189 same interrupt level. If the interrupt routine acquires the lock before the
 190 lock has been initialized, undefined behavior may result.
 191 .SS "ddi_add_intr(\|)"
 192 .sp
 193 .LP
 194 \fBddi_add_intr()\fR adds an interrupt handler to the system. The interrupt
 195 number \fIinumber\fR determines which interrupt the handler will be associated
 196 with. (Refer to \fBddi_get_iblock_cookie()\fR above.)
 197 .sp
 198 .LP
 199 On a successful return, \fIiblock_cookiep\fR contains information used for
 200 initializing locks associated with this interrupt specification (see
 201 \fBmutex_init\fR(9F) and \fBrw_init\fR(9F)). Note that the interrupt block
 202 cookie is usually obtained using \fBddi_get_iblock_cookie()\fR to avoid the
 203 race conditions described above (refer to \fBddi_get_iblock_cookie()\fR above).
 204 For this reason, \fIiblock_cookiep\fR is no longer useful and should be set to
 205 \fINULL\fR.
 206 .sp
 207 .LP
 208 On a successful return, \fIidevice_cookiep\fR contains a pointer to a
 209 \fBddi_idevice_cookie_t\fR structure (see \fBddi_idevice_cookie\fR(9S))
 210 containing information useful for some devices that have programmable
 211 interrupts. If \fIidevice_cookiep\fR is set to \fINULL\fR, no value is
 212 returned.
 213 .sp
 214 .LP
 215 The routine \fIintr_handler\fR, with its argument \fIint_handler_arg\fR, is
 216 called upon receipt of the appropriate interrupt. The interrupt handler should
 217 return \fBDDI_INTR_CLAIMED\fR if the interrupt was claimed,
 218 \fBDDI_INTR_UNCLAIMED\fR otherwise.
 219 .sp
 220 .LP
 221 If successful, \fBddi_add_intr()\fR returns \fBDDI_SUCCESS\fR. If the interrupt
 222 information cannot be found on the sun4u architecture, either
 223 \fBDDI_INTR_NOTFOUND\fR or \fBDDI_FAILURE\fR can be returned. On i86pc and
 224 sun4m architectures, if the interrupt information cannot be found,
 225 \fBDDI_INTR_NOTFOUND\fR is returned.
 226 .SS "ddi_remove_intr(\|)"
 227 .sp
 228 .LP
 229 \fBddi_remove_intr()\fR removes an interrupt handler from the system.
 230 Unloadable drivers should call this routine during their \fBdetach\fR(9E)
 231 routine to remove their interrupt handler from the system.
 232 .sp
 233 .LP
 234 The device interrupt routine for this instance of the device will not execute
 235 after \fBddi_remove_intr()\fR returns. \fBddi_remove_intr()\fR may need to wait
 236 for the device interrupt routine to complete before returning. Therefore, locks
 237 acquired by the interrupt handler should not be held across the call to
 238 \fBddi_remove_intr()\fR or deadlock may result.
 239 .SS "For All Three Functions:"
 240 .sp
 241 .LP
 242 For certain bus types, you can call these \fBDDI\fR functions from a
 243 high-interrupt context. These types include \fBISA\fR and SBus buses. See
 244 \fBsysbus\fR(4), \fBisa\fR(4), and \fBsbus\fR(4) for details.
 245 .SH RETURN VALUES
 246 .sp
 247 .LP
 248 \fBddi_add_intr()\fR and \fBddi_get_iblock_cookie()\fR return:
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fBDDI_SUCCESS\fR\fR
 253 .ad
 254 .RS 21n
 255 On success.
 256 .RE
 257
 258 .sp
 259 .ne 2
 260 .na
 261 \fB\fBDDI_INTR_NOTFOUND\fR\fR
 262 .ad
 263 .RS 21n
 264 On failure to find the interrupt.
 265 .RE
 266
 267 .sp
 268 .ne 2
 269 .na
 270 \fB\fBDDI_FAILURE\fR\fR
 271 .ad
 272 .RS 21n
 273 On failure. \fBDDI_FAILURE\fR can also be returned on failure to find interrupt
 274 (\fBsun4u\fR).
 275 .RE
 276
 277 .SH CONTEXT
 278 .sp
 279 .LP
 280 \fBddi_add_intr()\fR, \fBddi_remove_intr()\fR, and
 281 \fBddi_get_iblock_cookie()\fR can be called from user or kernel context.
 282 .SH ATTRIBUTES
 283 .sp
 284 .LP
 285 See \fBattributes\fR(5) for descriptions of the following attributes:
 286 .sp
 287
 288 .sp
 289 .TS
 290 box;
 291 c | c
 292 l | l .
 293 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 294 _
 295 Interface Stability     Obsolete
 296 .TE
 297
 298 .SH SEE ALSO
 299 .sp
 300 .LP
 301 \fBdriver.conf\fR(4), \fBisa\fR(4), \fBsbus\fR(4), \fBsysbus\fR(4),
 302 \fBattach\fR(9E), \fBdetach\fR(9E), \fBddi_intr_hilevel\fR(9F),
 303 \fBIntro\fR(9F), \fBmutex\fR(9F), \fBmutex_init\fR(9F), \fBrw_init\fR(9F),
 304 \fBrwlock\fR(9F), \fBddi_idevice_cookie\fR(9S)
 305 .sp
 306 .LP
 307 \fIWriting Device Drivers\fR
 308 .SH NOTES
 309 .sp
 310 .LP
 311 \fBddi_get_iblock_cookie()\fR must not be called \fBafter\fR the driver adds an
 312 interrupt handler for the interrupt specification corresponding to
 313 \fIinumber\fR.
 314 .sp
 315 .LP
 316 All consumers of these interfaces, checking return codes, should verify
 317 \fBreturn_code != DDI_SUCCESS\fR. Checking for specific failure codes can
 318 result in inconsistent behaviors among platforms.
 319 .SH BUGS
 320 .sp
 321 .LP
 322 The \fIidevice_cookiep\fR should really point to a data structure that is
 323 specific to the bus architecture that the device operates on. Currently the
 324 SBus and PCI buses are supported and a single data structure is used to
 325 describe both.