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

NAME

6       ddi_intr_add_handler, ddi_intr_remove_handler - add or remove interrupt
7       handler
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_intr_add_handler(ddi_intr_handle_t *h,
18            ddi_intr_handler_t inthandler, void *arg1,
19             void *arg2);
20
21
22       int ddi_intr_remove_handler(ddi_intr_handle_t h);
23
24

INTERFACE LEVEL

26       Solaris DDI specific (Solaris DDI).
27

PARAMETERS

29       ddi_intr_add_handler()
30
31       h             Pointer to the DDI interrupt handle
32
33
34       inthandler    Pointer to interrupt handler
35
36
37       arg1          First argument for the interrupt handler
38
39
40       arg2          Second, optional, argument for the interrupt handler
41
42
43
44       ddi_intr_remove_handler()
45
46       h    DDI interrupt handle
47
48

DESCRIPTION

50       The ddi_intr_add_handler() function adds an interrupt handler given  by
51       the  inthandler  argument to the system with the handler arguments arg1
52       and arg2 for the previously allocated interrupt handle specified by the
53       h pointer. The arguments arg1 and arg2 are passed as the first and sec‐
54       ond arguments, respectively, to the interrupt handler  inthandler.  See
55       <sys/ddi_intr.h> for the definition of the interrupt handler.
56
57
58       The  routine inthandler with the arguments arg1 and arg2 is called upon
59       receipt of the appropriate  interrupt.  The  interrupt  handler  should
60       return    DDI_INTR_CLAIMED    if   the   interrupt   is   claimed   and
61       DDI_INTR_UNCLAIMED otherwise.
62
63
64       The   ddi_intr_add_handler()   function   must    be    called    after
65       ddi_intr_alloc(), but before ddi_intr_enable() is called. The interrupt
66       must be enabled through  ddi_intr_enable()  or  ddi_intr_block_enable()
67       before it can be used.
68
69
70       The ddi_intr_remove_handler() function removes the handler association,
71       added previously with ddi_intr_add_handler(), for the interrupt identi‐
72       fied by the interrupt handle h argument. Unloadable drivers should call
73       this routine during their detach(9E) routine to  remove  the  interrupt
74       handler from the system.
75
76
77       The ddi_intr_remove_handler() function is used to disassociate the han‐
78       dler after the interrupt is disabled to remove  dup-ed  interrupt  han‐
79       dles.  See  ddi_intr_dup_handler(9F) for dup-ed interrupt handles. If a
80       handler is duplicated with  the  ddi_intr_dup_handler()  function,  all
81       added  and  duplicated  instances  of  the handler must be removed with
82       ddi_intr_remove_handler() in order for the  handler  to  be  completely
83       removed.
84

RETURN VALUES

86       The   ddi_intr_add_handler()  and  ddi_intr_remove_handler()  functions
87       return:
88
89       DDI_SUCCESS    On success.
90
91
92       DDI_EINVAL     On encountering invalid input parameters.
93
94
95       DDI_FAILURE    On any implementation specific failure.
96
97

CONTEXT

99       The ddi_intr_add_handler() and ddi_intr_remove_handler() functions  can
100       be called from kernel non-interrupt context.
101

ATTRIBUTES

103       See attributes(5) for descriptions of the following attributes:
104
105
106
107
108       ┌─────────────────────────────┬─────────────────────────────┐
109       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
110       ├─────────────────────────────┼─────────────────────────────┤
111       │Interface Stability          │Committed                    │
112       └─────────────────────────────┴─────────────────────────────┘
113

SEE ALSO

115       attributes(5),      attach(9E),     detach(9E),     ddi_intr_alloc(9F),
116       ddi_intr_block_enable(9F),   ddi_intr_disable(9F),    ddi_intr_dup_han‐
117       dler(9F),   ddi_intr_enable(9F),  ddi_intr_free(9F),  ddi_intr_get_sup‐
118       ported_types(9F), mutex(9F), mutex_init(9F), rw_init(9F), rwlock(9F)
119
120
121       Writing Device Drivers
122

NOTES

124       Consumers of these interfaces should verify that the  return  value  is
125       not  equal  to DDI_SUCCESS. Incomplete checking for failure codes could
126       result in inconsistent behavior among platforms.
127
128
129       If a device driver that  uses  MSI  and  MSI-X  interrupts  resets  the
130       device,  the  device might reset its configuration space modifications.
131       Such a reset could cause a device driver to  lose  any  MSI  and  MSI-X
132       interrupt usage settings that have been applied.
133
134
135       The  second argument, arg2, is optional. Device drivers are free to use
136       the two arguments however they see fit. There is no  officially  recom‐
137       mended  model  or  restrictions.  For example, an interrupt handler may
138       wish to use the first argument as the pointer to its softstate and  the
139       second argument as the value of the MSI vector.
140
141
142
143SunOS 5.11                        22 Apr 2005         ddi_intr_add_handler(9F)
Impressum