ddi_intr_alloc(9f)

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

NAME

6       ddi_intr_alloc, ddi_intr_free - allocate or free interrupts for a given
7       interrupt type
8

SYNOPSIS

10       #include <sys/types.h>
11       #include <sys/conf.h>
12       #include <sys/ddi.h>
13       #include <sys/sunddi.h>
14
15       int ddi_intr_alloc(dev_info_t *dip, ddi_intr_handle_t *h_array, int type,
16            int inum, int count, int *actualp, int behavior);
17
18
19       int ddi_intr_free(ddi_intr_handle_t h);
20
21

INTERFACE LEVEL

23       Solaris DDI specific (Solaris DDI).
24

PARAMETERS

26       ddi_intr_alloc()
27
28       dip         Pointer to the dev_info structure
29
30
31       h_array     Pointer to an array of DDI interrupt handles
32
33
34       type        Interrupt type
35
36
37       inum        Interrupt number
38
39
40       count       Number of interrupts requested. The count should not exceed
41                   the  total number of interrupts supported by the device, as
42                   returned by a call to ddi_intr_get_nintrs(9F).
43
44
45       actualp     Pointer to the number of interrupts actually allocated
46
47
48       behavior    Flag to determine the allocation algorithm
49
50
51
52       ddi_intr_free()
53
54       h    DDI interrupt handle
55
56

DESCRIPTION

58       The ddi_intr_alloc() function allocates  interrupts  of  the  interrupt
59       type given by the type argument beginning at the interrupt number inum.
60       If ddi_intr_alloc() allocates any interrupts,  it  returns  the  actual
61       number of interrupts allocated in the integer pointed to by the actualp
62       argument and returns the number of interrupt handles in  the  interrupt
63       handle array pointed to by the h_array argument.
64
65
66       Specific  interrupts  are always specified by the combination of inter‐
67       rupt type and inum. For legacy devices, inum refers to the  nth  inter‐
68       rupt,  typically as defined by the devices interrupts property. For PCI
69       fixed interrupts, inum refers to the interrupt number. The inum is  the
70       relative  interrupt vector number, from 0 to 31 for MSI, from 0 to 2047
71       for MSI-X. The first interrupt vector is 0. The last relative vector is
72       31 for MSI or 2047 for MSI-X.
73
74
75       The  h_array must be pre-allocated by the caller as a count sized array
76       of ddi_intr_handle_t's.
77
78
79       If MSI interrupts are being allocated, the count argument passed should
80       be  a number between 1 and 32, specified as a power of two. If count is
81       not specified as a power of two, the error DDI_EINVAL is returned.
82
83
84       The behavior flag controls the interrupt allocation algorithm. It takes
85       one     of     two     input     values:    DDI_INTR_ALLOC_NORMAL    or
86       DDI_INTR_ALLOC_STRICT. If the count value used is greater than  NINTRs,
87       then  the  call  fails  with  DDI_EINVAL  unconditionally.  When set to
88       DDI_INTR_ALLOC_STRICT, the call succeeds if and only  if  count  inter‐
89       rupts  are  allocated.  Otherwise,  the  call  fails, and the number of
90       available  interrupts   is   returned   in   actualp.   When   set   to
91       DDI_INTR_ALLOC_NORMAL,  the  call succeeds if at least one interrupt is
92       allocated, and the number of allocated interrupts is returned in  actu‐
93       alp.
94
95
96       The  handle  for  each  allocated interrupt, if any, is returned in the
97       array of handles given by the h_array argument.
98
99
100       The ddi_intr_free() function releases the system resources  and  inter‐
101       rupt  vectors  associated  with  the ddi_intr_handle_t h, including any
102       resources associated with the handle h itself. Once freed, the handle h
103       should not be used in any further calls.
104
105
106       The  ddi_intr_free()  function should be called once for each handle in
107       the handle array.
108

RETURN VALUES

110       The ddi_intr_alloc() and ddi_intr_free() functions return:
111
112       DDI_SUCCESS          On success.
113
114
115       DDI_EAGAIN           Not enough interrupt resources.
116
117
118       DDI_EINVAL           On encountering invalid input parameters.
119
120
121       DDI_INTR_NOTFOUND    On failure to find the interrupt.
122
123
124       DDI_FAILURE          On any implementation specific failure.
125
126

CONTEXT

128       The ddi_intr_alloc() and ddi_intr_free() functions can be  called  from
129       kernel non-interrupt context.
130

ATTRIBUTES

132       See attributes(5) for descriptions of the following attributes:
133
134
135
136
137       ┌─────────────────────────────┬─────────────────────────────┐
138       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
139       ├─────────────────────────────┼─────────────────────────────┤
140       │Interface Stability          │Committed                    │
141       └─────────────────────────────┴─────────────────────────────┘
142

NOTES

153       Consumers of these interfaces should verify that the  return  value  is
154       not  equal  to DDI_SUCCESS. Incomplete checking for failure codes could
155       result in inconsistent behavior among platforms.
156
157
158       If a device driver that  uses  MSI  and  MSI-X  interrupts  resets  the
159       device,  the  device might reset its configuration space modifications.
160       Such a reset could cause a device driver to  lose  any  MSI  and  MSI-X
161       interrupt usage settings that have been applied.
162
163
164
165SunOS 5.11                        23 Apr 2008               ddi_intr_alloc(9F)