1ddi_add_intr(9F)         Kernel Functions for Drivers         ddi_add_intr(9F)
2
3
4

NAME

6       ddi_add_intr,  ddi_get_iblock_cookie, ddi_remove_intr - hardware inter‐
7       rupt handling routines
8

SYNOPSIS

10       #include <sys/types.h>
11       #include <sys/conf.h>
12       #include <sys/ddi.h>
13       #include <sys/sunddi.h>
14
15
16
17       int ddi_get_iblock_cookie(dev_info_t *dip, uint_t inumber,
18             ddi_iblock_cookie_t *iblock_cookiep);
19
20
21       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
27
28       void ddi_remove_intr(dev_info_t *dip,
29            uint_t inumber, ddi_iblock_cookie_t iblock_cookie);
30
31

INTERFACE LEVEL

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

PARAMETERS

38       For ddi_get_iblock_cookie():
39
40       dip               Pointer to dev_info structure.
41
42
43       inumber           Interrupt number.
44
45
46       iblock_cookiep    Pointer to an interrupt block cookie.
47
48
49
50       For ddi_add_intr():
51
52       dip                Pointer to dev_info structure.
53
54
55       inumber            Interrupt number.
56
57
58       iblock_cookiep     Optional pointer to an interrupt block cookie  where
59                          a returned interrupt block cookie is stored.
60
61
62       idevice_cookiep    Optional pointer to an interrupt device cookie where
63                          a returned interrupt device cookie is stored.
64
65
66       int_handler        Pointer to interrupt handler.
67
68
69       int_handler_arg    Argument for interrupt handler.
70
71
72
73       For ddi_remove_intr():
74
75       dip              Pointer to dev_info structure.
76
77
78       inumber          Interrupt number.
79
80
81       iblock_cookie    Block cookie which identifies the interrupt handler to
82                        be removed.
83
84

DESCRIPTION

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
97
98       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
109   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
114
115       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
123
124       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
129
130       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
135
136       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
142   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
147
148       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
154   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

RETURN VALUES

160       ddi_add_intr() and ddi_get_iblock_cookie() return:
161
162       DDI_SUCCESS          On success.
163
164
165       DDI_INTR_NOTFOUND    On failure to find the interrupt.
166
167
168       DDI_FAILURE          On failure. DDI_FAILURE can also  be  returned  on
169                            failure to find interrupt (sun4u).
170
171

CONTEXT

173       ddi_add_intr(),  ddi_remove_intr(),  and ddi_get_iblock_cookie() can be
174       called from user or kernel context.
175

ATTRIBUTES

177       See attributes(5) for descriptions of the following attributes:
178
179
180
181
182       ┌─────────────────────────────┬─────────────────────────────┐
183       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
184       ├─────────────────────────────┼─────────────────────────────┤
185       │Interface Stability          │Obsolete                     │
186       └─────────────────────────────┴─────────────────────────────┘
187

SEE ALSO

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
193
194       Writing Device Drivers
195

NOTES

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
201
202       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

BUGS

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.
211
212
213
214SunOS 5.11                        19 Oct 2005                 ddi_add_intr(9F)
Impressum