xref: /illumos-gate/usr/src/uts/common/sys/ddi_intr.h (revision 657f87de)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
23  */
24 
25 #ifndef	_SYS_DDI_INTR_H
26 #define	_SYS_DDI_INTR_H
27 
28 /*
29  * Sun DDI interrupt support definitions
30  */
31 
32 #include <sys/ddipropdefs.h>
33 #include <sys/rwlock.h>
34 #include <sys/processor.h>
35 
36 #ifdef	__cplusplus
37 extern "C" {
38 #endif
39 
40 #ifdef _KERNEL
41 
42 /*
43  * Interrupt related definitions.
44  */
45 
46 /*
47  * Returned by ddi_add_intr or ddi_add_fastintr in order to signal
48  * the the caller requested interrupt number to be added does not
49  * exist.
50  */
51 #define	DDI_INTR_NOTFOUND	1	/* interrupt not found error */
52 
53 /*
54  * For use by driver interrupt service routines to return to the
55  * system whether an interrupt was for the driver or not.
56  */
57 #define	DDI_INTR_CLAIMED	1	/* returned when driver claims intr */
58 #define	DDI_INTR_UNCLAIMED	0	/* returned when driver does not */
59 
60 /* Hardware interrupt types */
61 #define	DDI_INTR_TYPE_FIXED	0x1
62 #define	DDI_INTR_TYPE_MSI	0x2
63 #define	DDI_INTR_TYPE_MSIX	0x4
64 
65 /* Hardware interrupt priority must be a number within these min/max values */
66 #define	DDI_INTR_PRI_MIN	1
67 #define	DDI_INTR_PRI_MAX	12
68 
69 /* Soft priority must be a number within these min/max values */
70 #define	DDI_INTR_SOFTPRI_MIN	1
71 #define	DDI_INTR_SOFTPRI_MAX	9
72 
73 /* Used in calls to allocate soft interrupt priority. */
74 #define	DDI_INTR_SOFTPRI_DEFAULT	DDI_INTR_SOFTPRI_MIN
75 
76 /*
77  * Interrupt flags specify certain capabilities for a given
78  * interrupt (by type and inum).
79  * RO/RW refer to use by ddi_intr_set_cap(9f)
80  *
81  * DDI_INTR_FLAG_MSI64 is an internal flag not exposed to leaf drivers.
82  */
83 #define	DDI_INTR_FLAG_LEVEL	0x0001	/* (RW) level trigger */
84 #define	DDI_INTR_FLAG_EDGE	0x0002	/* (RW) edge triggered */
85 #define	DDI_INTR_FLAG_MASKABLE	0x0010	/* (RO) maskable */
86 #define	DDI_INTR_FLAG_PENDING	0x0020	/* (RO) int pending supported */
87 #define	DDI_INTR_FLAG_BLOCK	0x0100	/* (RO) requires block enable */
88 #define	DDI_INTR_FLAG_MSI64	0x0200	/* (RO) MSI/X supports 64 bit addr */
89 
90 /*
91  * Macro to be used while passing interrupt priority
92  * for lock initialization.
93  */
94 #define	DDI_INTR_PRI(pri)	(void *)((uintptr_t)(pri))
95 
96 /*
97  * Typedef for interrupt handles
98  */
99 typedef struct __ddi_intr_handle *ddi_intr_handle_t;
100 typedef struct __ddi_softint_handle *ddi_softint_handle_t;
101 
102 /*
103  * Definition for behavior flag which is used with ddi_intr_alloc(9f).
104  */
105 #define	DDI_INTR_ALLOC_NORMAL	0	/* Non-strict alloc */
106 #define	DDI_INTR_ALLOC_STRICT	1	/* Strict allocation */
107 
108 /*
109  * Typedef for driver's interrupt handler
110  */
111 typedef uint_t (ddi_intr_handler_t)(caddr_t arg1, caddr_t arg2);
112 
113 #endif	/* _KERNEL */
114 #include <sys/ddi_intr_impl.h>
115 #ifdef _KERNEL
116 
117 /*
118  * DDI interrupt function prototypes.
119  *
120  * New DDI interrupt interfaces.
121  */
122 
123 /*
124  * ddi_intr_get_supported_types:
125  *
126  *	Return, as a bit mask, the hardware interrupt types supported by
127  *	both the device and by the host in the integer pointed
128  *	to be the 'typesp' argument.
129  */
130 int	ddi_intr_get_supported_types(dev_info_t *dip, int *typesp);
131 
132 /*
133  * ddi_intr_get_nintrs:
134  *
135  * 	Return as an integer in the integer pointed to by the argument
136  * 	*nintrsp*, the number of interrupts the device supports for the
137  *	given interrupt type.
138  */
139 int	ddi_intr_get_nintrs(dev_info_t *dip, int type, int *nintrsp);
140 
141 /*
142  * ddi_intr_get_navail:
143  *
144  * 	Return as an integer in the integer pointed to by the argument
145  * 	*navailp*, the number of interrupts currently available for the
146  *	given interrupt type.
147  */
148 int	ddi_intr_get_navail(dev_info_t *dip, int type, int *navailp);
149 
150 /*
151  * Interrupt resource allocate/free functions
152  */
153 int	ddi_intr_alloc(dev_info_t *dip, ddi_intr_handle_t *h_array,
154 	    int type, int inum, int count, int *actualp, int behavior);
155 int	ddi_intr_free(ddi_intr_handle_t h);
156 
157 /*
158  * Interrupt get/set capacity functions
159  */
160 int	ddi_intr_get_cap(ddi_intr_handle_t h, int *flagsp);
161 int	ddi_intr_set_cap(ddi_intr_handle_t h, int flags);
162 
163 /*
164  * Interrupt priority management functions
165  */
166 uint_t	ddi_intr_get_hilevel_pri(void);
167 int	ddi_intr_get_pri(ddi_intr_handle_t h, uint_t *prip);
168 int	ddi_intr_set_pri(ddi_intr_handle_t h, uint_t pri);
169 
170 /*
171  * Interrupt add/duplicate/remove functions
172  */
173 int	ddi_intr_add_handler(ddi_intr_handle_t h,
174 	    ddi_intr_handler_t inthandler, void *arg1, void *arg2);
175 int	ddi_intr_dup_handler(ddi_intr_handle_t org, int vector,
176 	    ddi_intr_handle_t *dup);
177 int	ddi_intr_remove_handler(ddi_intr_handle_t h);
178 
179 
180 /*
181  * Interrupt enable/disable/block_enable/block_disable functions
182  */
183 int	ddi_intr_enable(ddi_intr_handle_t h);
184 int	ddi_intr_disable(ddi_intr_handle_t h);
185 int	ddi_intr_block_enable(ddi_intr_handle_t *h_array, int count);
186 int	ddi_intr_block_disable(ddi_intr_handle_t *h_array, int count);
187 
188 /*
189  * Interrupt set/clr mask functions
190  */
191 int	ddi_intr_set_mask(ddi_intr_handle_t h);
192 int	ddi_intr_clr_mask(ddi_intr_handle_t h);
193 
194 /*
195  * Interrupt get pending function
196  */
197 int	ddi_intr_get_pending(ddi_intr_handle_t h, int *pendingp);
198 
199 /*
200  * Interrupt resource management function
201  */
202 int	ddi_intr_set_nreq(dev_info_t *dip, int nreq);
203 
204 /*
205  * Soft interrupt functions
206  */
207 int	ddi_intr_add_softint(dev_info_t *dip, ddi_softint_handle_t *h,
208 	    int soft_pri, ddi_intr_handler_t handler, void *arg1);
209 int	ddi_intr_remove_softint(ddi_softint_handle_t h);
210 int	ddi_intr_trigger_softint(ddi_softint_handle_t h, void *arg2);
211 int	ddi_intr_get_softint_pri(ddi_softint_handle_t h, uint_t *soft_prip);
212 int	ddi_intr_set_softint_pri(ddi_softint_handle_t h, uint_t soft_pri);
213 
214 /*
215  * Old DDI interrupt interfaces.
216  *
217  * The following DDI interrupt interfaces are obsolete.
218  * Use the above new DDI interrupt interfaces instead.
219  */
220 
221 /*
222  * Return non-zero if the specified interrupt exists and the handler
223  * will be restricted to using only certain functions because the
224  * interrupt level is not blocked by the scheduler.  I.e., it cannot
225  * signal other threads.
226  */
227 int	ddi_intr_hilevel(dev_info_t *dip, uint_t inumber);
228 
229 int	ddi_get_iblock_cookie(dev_info_t *dip, uint_t inumber,
230 	    ddi_iblock_cookie_t *iblock_cookiep);
231 
232 /*
233  * ddi_dev_nintrs
234  *
235  *	If the device has h/w interrupt(s), report
236  *	how many of them that there are into resultp.
237  *	Return DDI_FAILURE if the device has no interrupts.
238  */
239 int	ddi_dev_nintrs(dev_info_t *dev, int *resultp);
240 
241 /*
242  * ddi_add_intr: Add an interrupt to the system.
243  *
244  *	The interrupt number "inumber" determines which interrupt will
245  *	be added. The interrupt number is associated with interrupt
246  *	information provided from self identifying devices or configuration
247  *	information for non-self identifying devices. If only one interrupt
248  *	is associated with the device then the interrupt number should be 0.
249  *
250  *	If successful, "*iblock_cookiep" will contain information necessary
251  *	for initializing locks (mutex_init, cv_init, etc.) as well as for
252  *	possible later removal of the interrupt from the system.
253  *
254  *	If successful, "*idevice_cookiep" will contain the correct programmable
255  *	device interrupt value (see <sys/dditypes.h> in the form of the
256  *	type ddi_idevice_cookie_t).
257  *
258  *	Either cookie pointer may be specified as a NULL pointer
259  *	in which case no value will be returned.
260  *
261  *	The interrupt handler "int_handler" is the address of the routine
262  *	to be called upon receipt of an appropriate interrupt. The
263  *	interrupt handler should return DDI_INTR_CLAIMED if the
264  *	interrupt was claimed, else DDI_INTR_UNCLAIMED. The argument
265  *	"int_handler_arg" will be passed to the "int_handler"
266  *	upon receipt of an appropriate interrupt.
267  *
268  *	If successful ddi_add_intr will return DDI_SUCCESS.
269  *	If the interrupt information cannot be found it will
270  *	return DDI_INTR_NOTFOUND.
271  *
272  */
273 int	ddi_add_intr(dev_info_t *dip, uint_t inumber,
274 	    ddi_iblock_cookie_t *iblock_cookiep,
275 	    ddi_idevice_cookie_t *idevice_cookiep,
276 	    uint_t (*int_handler)(caddr_t int_handler_arg),
277 	    caddr_t int_handler_arg);
278 
279 /*
280  * The following function is for Sun's internal use only at present
281  */
282 int	ddi_add_fastintr(dev_info_t *dip, uint_t inumber,
283 	    ddi_iblock_cookie_t *iblock_cookiep,
284 	    ddi_idevice_cookie_t *idevice_cookiep,
285 	    uint_t (*hi_int_handler)(void));
286 
287 /*
288  * ddi_remove_intr:	Remove interrupt set up by ddi_add_intr.
289  *
290  *	This routine is intended to be used by drivers that are
291  *	preparing to unload themselves "detach" from the system.
292  */
293 void	ddi_remove_intr(dev_info_t *dip, uint_t inum,
294 	    ddi_iblock_cookie_t iblock_cookie);
295 
296 /*
297  * For use by ddi_add_softintr in order to specify a priority preference.
298  */
299 #define	DDI_SOFTINT_FIXED	0	/* Fixed priority soft interrupt */
300 #define	DDI_SOFTINT_LOW		8	/* Low priority soft interrupt */
301 #define	DDI_SOFTINT_MED		128	/* Medium priority soft interrupt */
302 #define	DDI_SOFTINT_HIGH	256	/* High priority soft interrupt */
303 
304 
305 int	ddi_get_soft_iblock_cookie(dev_info_t *dip, int preference,
306 	    ddi_iblock_cookie_t *iblock_cookiep);
307 
308 /*
309  * ddi_add_softintr:	Add a "soft" interrupt to the system.
310  *
311  *	Like ddi_add_intr, only for system interrupts that you can trigger
312  *	yourself. You specify a preference (see above) for the level you
313  *	want. You get an identifier back which you can use to either trigger
314  *	a soft interrupt or, later, remove it.
315  */
316 int	ddi_add_softintr(dev_info_t *dip, int preference, ddi_softintr_t *idp,
317 	    ddi_iblock_cookie_t *iblock_cookiep,
318 	    ddi_idevice_cookie_t *idevice_cookiep,
319 	    uint_t (*int_handler)(caddr_t int_handler_arg),
320 	    caddr_t int_handler_arg);
321 
322 void	ddi_remove_softintr(ddi_softintr_t id);
323 
324 void	ddi_trigger_softintr(ddi_softintr_t id);
325 
326 #endif	/* _KERNEL */
327 
328 #ifdef	__cplusplus
329 }
330 #endif
331 
332 #endif	/* _SYS_DDI_INTR_H */
333