Kernel Functions for Drivers                   ddiintralloc(9F)



NAME
     ddiintralloc, ddiintrfree - allocate or free  interrupts
     for a given interrupt type

SYNOPSIS
     #include 
     #include 
     #include 
     #include 

     int ddiintralloc(devinfot *dip, ddiintrhandlet *harray, int type,
          int inum, int count, int *actualp, int behavior);


     int ddiintrfree(ddiintrhandlet h);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI).

PARAMETERS
     ddiintralloc()

     dip         Pointer to the devinfo structure


     harray     Pointer to an array of DI interrupt handles


     type        Interrupt type


     inum        Interrupt number


     count       Number of interrupts requested. The count should
                 not  exceed  the total number of interrupts sup-
                 ported by the device, as returned by a  call  to
                 ddiintrgetnintrs(9F).


     actualp     Pointer to the  number  of  interrupts  actually
                 allocated


     behavior    Flag to determine the allocation algorithm



     ddiintrfree()





SunOS 5.11          Last change: 23 Apr 2008                    1






Kernel Functions for Drivers                   ddiintralloc(9F)



     h    DI interrupt handle


DESCRIPTION
     The ddiintralloc() function allocates  interrupts  of  the
     interrupt  type  given by the type argument beginning at the
     interrupt number inum.  If  ddiintralloc()  allocates  any
     interrupts, it returns the actual number of interrupts allo-
     cated 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 harray argument.


     Specific interrupts are always specified by the  combination
     of  interrupt type and inum. For legacy devices, inum refers
     to the nth interrupt, 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.  The  last  relative
     vector is 31 for MSI or 2047 for MSI-X.


     The harray must be pre-allocated by the caller as  a  count
     sized array of ddiintrhandlet'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 DIEINVAL is returned.


     The behavior flag controls the  interrupt  allocation  algo-
     rithm.    It    takes    one    of    two    input   values:
     DINTRALOCNORMAL or DINTRALOCSTRICT. If the count
     value  used is greater than NINTRs, then the call fails with
     DIEINVAL      unconditionally.      When      set       to
     DINTRALOCSTRICT,  the  call  succeeds  if  and only if
     count interrupts are allocated. Otherwise, the  call  fails,
     and  the number of available interrupts is returned in actu-
     alp. When set to DINTRALOCNORMAL, the call succeeds if
     at least one interrupt is allocated, and the number of allo-
     cated interrupts is returned in actualp.


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


     The ddiintrfree() function releases the  system  resources
     and  interrupt vectors associated with the ddiintrhandlet



SunOS 5.11          Last change: 23 Apr 2008                    2






Kernel Functions for Drivers                   ddiintralloc(9F)



     h, including any resources  associated  with  the  handle  h
     itself.  Once  freed, the handle h should not be used in any
     further calls.


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

RETURN VALUES
     The ddiintralloc() and ddiintrfree() functions return:

     DISUCES          On success.


     DIEAGAIN           Not enough interrupt resources.


     DIEINVAL           On encountering invalid  input  parame-
                          ters.


     DINTRNOTFOUND    On failure to find the interrupt.


     DIFAILURE          On any implementation specific failure.


CONTEXT
     The ddiintralloc() and ddiintrfree()  functions  can  be
     called from kernel non-interrupt context.

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Committed                   
    


SEE ALSO
     attributes(5),                     ddiintraddhandler(9F),
     ddiintrblockenable(9F),             ddiintrdisable(9F),
     ddiintrenable(9F),                   ddiintrgetcap(9F),
     ddiintrgetnintrs(9F),               ddiintrgetpri(9F),
     ddiintrgetsupportedtypes(9F),
     ddiintrremovehandler(9F)




SunOS 5.11          Last change: 23 Apr 2008                    3






Kernel Functions for Drivers                   ddiintralloc(9F)



     Writing Device Drivers

NOTES
     Consumers of these interfaces should verify that the  return
     value  is  not equal to DISUCES. 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.









































SunOS 5.11          Last change: 23 Apr 2008                    4