usr/src/man/man9f/ddi_intr_add_handler.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_ADD_HANDLER 9F "Apr 22, 2005"
   7 .SH NAME
   8 ddi_intr_add_handler, ddi_intr_remove_handler \- add or remove interrupt
   9 handler
  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_intr_add_handler\fR(\fBddi_intr_handle_t *\fR\fIh\fR,
  21      \fBddi_intr_handler_t\fR \fIinthandler\fR, \fBvoid *\fR\fIarg1\fR,
  22       \fBvoid *\fR\fIarg2\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBint\fR \fBddi_intr_remove_handler\fR(\fBddi_intr_handle_t\fR \fIh\fR);
  28 .fi
  29
  30 .SH INTERFACE LEVEL
  31 .sp
  32 .LP
  33 Solaris DDI specific (Solaris DDI).
  34 .SH PARAMETERS
  35 .sp
  36 .LP
  37 \fBddi_intr_add_handler()\fR
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIh\fR\fR
  42 .ad
  43 .RS 14n
  44 Pointer to the DDI interrupt handle
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fIinthandler\fR\fR
  51 .ad
  52 .RS 14n
  53 Pointer to interrupt handler
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIarg1\fR\fR
  60 .ad
  61 .RS 14n
  62 First argument for the interrupt handler
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIarg2\fR\fR
  69 .ad
  70 .RS 14n
  71 Second, optional, argument for the interrupt handler
  72 .RE
  73
  74 .sp
  75 .LP
  76 \fBddi_intr_remove_handler()\fR
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fIh\fR\fR
  81 .ad
  82 .RS 5n
  83 DDI interrupt handle
  84 .RE
  85
  86 .SH DESCRIPTION
  87 .sp
  88 .LP
  89 The \fBddi_intr_add_handler()\fR function adds an interrupt handler given by
  90 the \fIinthandler\fR argument to the system with the handler arguments
  91 \fIarg1\fR and \fIarg2\fR for the previously allocated interrupt handle
  92 specified by the \fIh\fR pointer. The arguments \fIarg1\fR and \fIarg2\fR are
  93 passed as the first and second arguments, respectively, to the interrupt
  94 handler \fIinthandler\fR. See \fB<sys/ddi_intr.h>\fR for the definition of the
  95 interrupt handler.
  96 .sp
  97 .LP
  98 The routine \fIinthandler\fR with the arguments \fIarg1\fR and \fIarg2\fR is
  99 called upon receipt of the appropriate interrupt. The interrupt handler should
 100 return \fBDDI_INTR_CLAIMED\fR if the interrupt is claimed and
 101 \fBDDI_INTR_UNCLAIMED\fR otherwise.
 102 .sp
 103 .LP
 104 The \fBddi_intr_add_handler()\fR function must be called after
 105 \fBddi_intr_alloc()\fR, but before \fBddi_intr_enable()\fR is called. The
 106 interrupt must be enabled through \fBddi_intr_enable()\fR or
 107 \fBddi_intr_block_enable()\fR before it can be used.
 108 .sp
 109 .LP
 110 The \fBddi_intr_remove_handler()\fR function removes the handler association,
 111 added previously with \fBddi_intr_add_handler()\fR, for the interrupt
 112 identified by the interrupt handle \fIh\fR argument. Unloadable drivers should
 113 call this routine during their \fBdetach\fR(9E) routine to remove the interrupt
 114 handler from the system.
 115 .sp
 116 .LP
 117 The \fBddi_intr_remove_handler()\fR function is used to disassociate the
 118 handler after the interrupt is disabled to remove \fBdup-ed\fR interrupt
 119 handles. See \fBddi_intr_dup_handler\fR(9F) for \fBdup-ed\fR interrupt handles.
 120 If a handler is duplicated with the \fBddi_intr_dup_handler()\fR function, all
 121 added and duplicated instances of the handler must be removed with
 122 \fBddi_intr_remove_handler()\fR in order for the handler to be completely
 123 removed.
 124 .SH RETURN VALUES
 125 .sp
 126 .LP
 127 The \fBddi_intr_add_handler()\fR and \fBddi_intr_remove_handler()\fR functions
 128 return:
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBDDI_SUCCESS\fR\fR
 133 .ad
 134 .RS 15n
 135 On success.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBDDI_EINVAL\fR\fR
 142 .ad
 143 .RS 15n
 144 On encountering invalid input parameters.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBDDI_FAILURE\fR\fR
 151 .ad
 152 .RS 15n
 153 On any implementation specific failure.
 154 .RE
 155
 156 .SH CONTEXT
 157 .sp
 158 .LP
 159 The \fBddi_intr_add_handler()\fR and \fBddi_intr_remove_handler()\fR functions
 160 can be called from kernel non-interrupt context.
 161 .SH ATTRIBUTES
 162 .sp
 163 .LP
 164 See \fBattributes\fR(5) for descriptions of the following attributes:
 165 .sp
 166
 167 .sp
 168 .TS
 169 box;
 170 c | c
 171 l | l .
 172 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 173 _
 174 Interface Stability     Committed
 175 .TE
 176
 177 .SH SEE ALSO
 178 .sp
 179 .LP
 180 \fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E),
 181 \fBddi_intr_alloc\fR(9F), \fBddi_intr_block_enable\fR(9F),
 182 \fBddi_intr_disable\fR(9F), \fBddi_intr_dup_handler\fR(9F),
 183 \fBddi_intr_enable\fR(9F), \fBddi_intr_free\fR(9F),
 184 \fBddi_intr_get_supported_types\fR(9F), \fBmutex\fR(9F), \fBmutex_init\fR(9F),
 185 \fBrw_init\fR(9F), \fBrwlock\fR(9F)
 186 .sp
 187 .LP
 188 \fIWriting Device Drivers\fR
 189 .SH NOTES
 190 .sp
 191 .LP
 192 Consumers of these interfaces should verify that the return value is not equal
 193 to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in
 194 inconsistent behavior among platforms.
 195 .sp
 196 .LP
 197 If a device driver that uses \fBMSI\fR and \fBMSI-X\fR interrupts resets the
 198 device, the device might reset its configuration space modifications. Such a
 199 reset could cause a device driver to lose any \fBMSI\fR and \fBMSI-X\fR
 200 interrupt usage settings that have been applied.
 201 .sp
 202 .LP
 203 The second argument, \fIarg2\fR, is optional. Device drivers are free to use
 204 the two arguments however they see fit. There is no officially recommended
 205 model or restrictions. For example, an interrupt handler may wish to use the
 206 first argument as the pointer to its softstate and the second argument as the
 207 value of the MSI vector.