ddi_intr_alloc(9F)														ddi_intr_alloc(9F)

NAME

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

SYNOPSIS

       #include <sys/types.h>
       #include <sys/conf.h>
       #include <sys/ddi.h>
       #include <sys/sunddi.h>

       int ddi_intr_alloc(dev_info_t *dip, ddi_intr_handle_t *h_array, int type, int inum, int count, int *actualp, int behavior);

       int ddi_intr_free(ddi_intr_handle_t h);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI).

       ddi_intr_alloc()

       dip	       Pointer to the dev_info structure

       h_array	       Pointer to an array of DDI interrupt handles

       type	       Interrupt type

       inum	       Interrupt number

       count	       Number of interrupts requested

       actualp	       Pointer to the number of interrupts actually allocated

       behavior        Flag to determine the allocation algorithm

       ddi_intr_free()

       h	       DDI interrupt handle

       The ddi_intr_alloc() function allocates interrupts of the interrupt type given by the type argument beginning at the interrupt number inum.
       If ddi_intr_alloc() allocates any interrupts, it returns the actual number of interrupts allocated in the integer pointed to by the actualp
       argument and returns the number of interrupt handles in the interrupt handle array pointed to by the h_array argument.

       Specific  interrupts  are always specified by the combination of interrupt type and inum. For legacy devices, inum refers to the nth inter-
       rupt, typically as defined by the devices interrupts property. For PCI fixed interrupts, inum refers to the interrupt number. The  inum	is
       the  relative  interrupt  vector number, from 0 to 31 for MSI, from 0 to 2047 for MSI-X. The first interrupt vector is 0, 31 or 2047 is the
       last relative vector.

       The h_array must be pre-allocated by the caller as a count sized array of ddi_intr_handle_t's.

       If MSI interrupts are being allocated, the count argument passed should be a number between 1 and 32, specified as a power of two. If count
       is not specified as a power of two, the error DDI_EINVAL is returned.

       The  value  of the behavior flag controls the allocation algorithm. If the behavior is set to DDI_INTR_ALLOC_STRICT, the call fails if less
       than count interrupts are currently available. If behavior is not set to DDI_INTR_ALLOC_STRICT, the call returns count or  less	number	of
       interrupts.

       If  any	interrupts  are  allocated,  the  number  of  interrupts  allocated  is returned in the int pointed to by the actualp argument and
       ddi_intr_alloc() returns DDI_SUCCESS.

       If behavior is DDI_INTR_ALLOC_STRICT and the requested count interrupt is not satisfied, ddi_intr_alloc() returns the number of	interrupts
       currently available for the given interrupt type in the int pointed to by the actualp argument.

       The handle for each allocated interrupt, if any, is returned in the array of handles given by the h_array argument.

       The  ddi_intr_free()  function  releases  the system resources and interrupt vectors associated with the ddi_intr_handle_t h, including any
       resources associated with the handle h itself. Once freed, the handle h should not be used in any further calls.

       The ddi_intr_free() function should be called once for each handle in the handle array.

       The ddi_intr_alloc() and ddi_intr_free() functions return:

       DDI_SUCCESS	       On success.

       DDI_EAGAIN	       Not enough interrupt resources..

       DDI_EINVAL	       On encountering invalid input parameters.

       DDI_INTR_NOTFOUND       On failure to find the interrupt.

       DDI_FAILURE	       On any implementation specific failure.

CONTEXT

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

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+

       attributes(5),  ddi_intr_add_handler(9F),  ddi_intr_block_enable(9F),  ddi_intr_disable(9F),   ddi_intr_enable(9F),   ddi_intr_get_cap(9F),
       ddi_intr_get_nintrs(9F), ddi_intr_get_pri(9F), ddi_intr_get_supported_types(9F), ddi_intr_remove_handler(9F)

       Consumers  of these interfaces should verify that the return value is not equal to DDI_SUCCESS. Incomplete checking for failure codes could
       result in inconsistent behavior among platforms.

       If a device driver that uses MSI and MSI-X interrupts resets the device, the device might reset its configuration space modifications. Such
       a reset could cause a device driver to lose any MSI and MSI-X interrupt usage settings that have been applied.

								    22 Apr 2005 						ddi_intr_alloc(9F)