1ddi_add_intr(9F) Kernel Functions for Drivers ddi_add_intr(9F)
2
6 ddi_add_intr, ddi_get_iblock_cookie, ddi_remove_intr - hardware inter‐
7 rupt handling routines
8
10 #include <sys/types.h>
11 #include <sys/conf.h>
12 #include <sys/ddi.h>
13 #include <sys/sunddi.h>
14 int ddi_get_iblock_cookie(dev_info_t *dip, uint_t inumber,
18 ddi_iblock_cookie_t *iblock_cookiep);
19 int ddi_add_intr(dev_info_t *dip, uint_t inumber,
22 ddi_iblock_cookie_t *iblock_cookiep,
23 ddi_idevice_cookie_t *idevice_cookiep,
24 uint_t (*int_handler) (caddr_t),
25 caddr_t int_handler_arg);
26 void ddi_remove_intr(dev_info_t *dip,
29 uint_t inumber, ddi_iblock_cookie_t iblock_cookie);
30
33 Solaris DDI specific (Solaris DDI). These interfaces are obsolete. Use
34 the new interrupt interfaces referenced in Intro(9F). Refer to Writing
35 Device Drivers for more information.
36
38 For ddi_get_iblock_cookie():
39 dip Pointer to dev_info structure.
41 inumber Interrupt number.
44 iblock_cookiep Pointer to an interrupt block cookie.
47 For ddi_add_intr():
51 dip Pointer to dev_info structure.
53 inumber Interrupt number.
56 iblock_cookiep Optional pointer to an interrupt block cookie where
59 a returned interrupt block cookie is stored.
60 idevice_cookiep Optional pointer to an interrupt device cookie where
63 a returned interrupt device cookie is stored.
64 int_handler Pointer to interrupt handler.
67 int_handler_arg Argument for interrupt handler.
70 For ddi_remove_intr():
74 dip Pointer to dev_info structure.
76 inumber Interrupt number.
79 iblock_cookie Block cookie which identifies the interrupt handler to
82 be removed.
83
86 ddi_get_iblock_cookie()
87 ddi_get_iblock_cookie() retrieves the interrupt block cookie associated
88 with a particular interrupt specification. This routine should be
89 called before ddi_add_intr() to retrieve the interrupt block cookie
90 needed to initialize locks (mutex(9F), rwlock(9F)) used by the inter‐
91 rupt routine. The interrupt number inumber determines for which inter‐
92 rupt specification to retrieve the cookie. inumber is associated with
93 information provided either by the device (see sbus(4)) or the hardware
94 configuration file (see sysbus(4), isa(4), and driver.conf(4)). If only
95 one interrupt is associated with the device, inumber should be 0.
96 On a successful return, *iblock_cookiep contains information needed for
99 initializing locks associated with the interrupt specification corre‐
100 sponding to inumber (see mutex_init(9F) and rw_init(9F)). The driver
101 can then initialize locks acquired by the interrupt routine before
102 calling ddi_add_intr() which prevents a possible race condition where
103 the driver's interrupt handler is called immediately after the driver
104 has called ddi_add_intr() but before the driver has initialized the
105 locks. This may happen when an interrupt for a different device occurs
106 on the same interrupt level. If the interrupt routine acquires the lock
107 before the lock has been initialized, undefined behavior may result.
108 ddi_add_intr()
110 ddi_add_intr() adds an interrupt handler to the system. The interrupt
111 number inumber determines which interrupt the handler will be associ‐
112 ated with. (Refer to ddi_get_iblock_cookie() above.)
113 On a successful return, iblock_cookiep contains information used for
116 initializing locks associated with this interrupt specification (see
117 mutex_init(9F) and rw_init(9F)). Note that the interrupt block cookie
118 is usually obtained using ddi_get_iblock_cookie() to avoid the race
119 conditions described above (refer to ddi_get_iblock_cookie() above).
120 For this reason, iblock_cookiep is no longer useful and should be set
121 to NULL.
122 On a successful return, idevice_cookiep contains a pointer to a
125 ddi_idevice_cookie_t structure (see ddi_idevice_cookie(9S)) containing
126 information useful for some devices that have programmable interrupts.
127 If idevice_cookiep is set to NULL, no value is returned.
128 The routine intr_handler, with its argument int_handler_arg, is called
131 upon receipt of the appropriate interrupt. The interrupt handler should
132 return DDI_INTR_CLAIMED if the interrupt was claimed,
133 DDI_INTR_UNCLAIMED otherwise.
134 If successful, ddi_add_intr() returns DDI_SUCCESS. If the interrupt
137 information cannot be found on the sun4u architecture, either
138 DDI_INTR_NOTFOUND or DDI_FAILURE can be returned. On i86pc and sun4m
139 architectures, if the interrupt information cannot be found,
140 DDI_INTR_NOTFOUND is returned.
141 ddi_remove_intr()
143 ddi_remove_intr() removes an interrupt handler from the system. Unload‐
144 able drivers should call this routine during their detach(9E) routine
145 to remove their interrupt handler from the system.
146 The device interrupt routine for this instance of the device will not
149 execute after ddi_remove_intr() returns. ddi_remove_intr() may need to
150 wait for the device interrupt routine to complete before returning.
151 Therefore, locks acquired by the interrupt handler should not be held
152 across the call to ddi_remove_intr() or deadlock may result.
153 For All Three Functions:
155 For certain bus types, you can call these DDI functions from a high-
156 interrupt context. These types include ISA and SBus buses. See sys‐
157 bus(4), isa(4), and sbus(4) for details.
158
160 ddi_add_intr() and ddi_get_iblock_cookie() return:
161 DDI_SUCCESS On success.
163 DDI_INTR_NOTFOUND On failure to find the interrupt.
166 DDI_FAILURE On failure. DDI_FAILURE can also be returned on
169 failure to find interrupt (sun4u).
170
173 ddi_add_intr(), ddi_remove_intr(), and ddi_get_iblock_cookie() can be
174 called from user or kernel context.
175
177 See attributes(5) for descriptions of the following attributes:
178 ┌─────────────────────────────┬─────────────────────────────┐
183 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
184 ├─────────────────────────────┼─────────────────────────────┤
185 │Interface Stability │Obsolete │
186 └─────────────────────────────┴─────────────────────────────┘
187
189 driver.conf(4), isa(4), sbus(4), sysbus(4), attach(9E), detach(9E),
190 ddi_intr_hilevel(9F), Intro(9F), mutex(9F), mutex_init(9F),
191 rw_init(9F), rwlock(9F), ddi_idevice_cookie(9S)
192 Writing Device Drivers
195
197 ddi_get_iblock_cookie() must not be called after the driver adds an
198 interrupt handler for the interrupt specification corresponding to
199 inumber.
200 All consumers of these interfaces, checking return codes, should verify
203 return_code != DDI_SUCCESS. Checking for specific failure codes can
204 result in inconsistent behaviors among platforms.
205
207 The idevice_cookiep should really point to a data structure that is
208 specific to the bus architecture that the device operates on. Currently
209 the SBus and PCI buses are supported and a single data structure is
210 used to describe both.
211SunOS 5.11 19 Oct 2005 ddi_add_intr(9F)