#ident	"@(#)ndi_irm_create.9f 1.1     08/09/30 SMI"

Kernel Functions for Nexus Drivers		ndi_irm_create(9F)

NAME
    ndi_irm_create, ndi_irm_destroy - create and destroy interrupt pools

SYNOPSIS
    #include <sys/sunndi.h>

    int ndi_irm_create(dev_info_t *dip, ddi_irm_params_t *paramsp,
                       ddi_irm_pool_t **pool_retp);

    int ndi_irm_destroy(ddi_irm_pool_t *pool);

INTERFACE LEVEL
    Solaris NDI specific (Solaris NDI).

PARAMETERS
    ndi_irm_create()

    dip		Pointer to the dev_info structure

    paramsp	Pointer to the parameters defining the pool to create

    pool_retp	Pointer in which to store a pointer to the pool created


    ndi_irm_destroy()

    pool	Pointer to the interupt pool to destroy

DESCRIPTION
    The ndi_irm_create() function is used by a nexus driver to define
    an interrupt pool.  Device drivers will then be able to consume
    interrupts from this pool in a manner which seeks to give each
    driver a fair and optimal allocation of interrupt vectors from
    this supply.  The goal being to maximize utilization of interrupt
    vectors from the supply in accordance with the balancing policies
    employed by Interrupt Resource Management (IRM).

    The paramsp argument is a pointer to an interrupt pool parameters
    structure which describes the interrupt pool being created.  The
    structure includes the following members:

        int       iparams_types;	/* Interrupt types in pool */
        uint_t    iparams_total;	/* Total vectors in pool */
        uint_t    iparams_default;	/* Default allocation limit */

    Descriptions of structure members are as follows:

    iparams_types	The types of interrupt vectors contained in the
			interrupt pool.  Multiple types can be combined.
			Possible types include DDI_INTR_TYPE_MSI and
			DDI_INTR_TYPE_MSIX.

    iparams_total	The total number of interrupt vectors contained
			within the pool.

    iparams_default	The default allocation limit for the interrupt
			pool.  If a driver gets mapped against this
			pool and it does not implement the necessary
			functionality to be dynamically managed by IRM,
			then this number represents the maximum number
			of interrupts that such a device can consume
			from the pool.  This value should be appropriate
			for the platform.

    The interrupt pool parameters structure may later be expanded to
    include new members.  For compatibility, a driver should zero the
    structure before setting individual members.  When new members are
    defined, those not explicitly set will use default values.

    The ndi_irm_destroy() function is used by a nexus driver to destroy
    a previously defined interrupt pool.  But only when there are no
    longer any device driver instances actively consuming interrupts
    from the pool.

    A nexus driver is expected to use ndi_irm_create() when it first
    attaches to the system to define any interrupt pools it provides.
    And then use ndi_irm_destroy() when it detaches.

    While operating, the nexus driver may periodically be asked by the
    system to map subordinate device driver instances to its defined
    pools.  It will receive a bus nexus driver interrupt operation
    DDI_INTROP_GETPOOL to perform this mapping.  Each such operation
    will be accompanied by a ddi_intr_handle_t containing a pointer to
    the dev_info node to be mapped, and the interrupt type associated
    with the mapping.  The nexus driver shall return a pointer to the
    relevant interrupt pool as the result of this operation.  Or return
    a NULL pointer and the error code DDI_ENOTSUP if no mapping exists.

    An interrupt pool could be used to support device driver instances
    on a specific IO bus, or it could be used to represent a systemwide
    resource.  A set of nexus drivers may need to cooperate together to
    perform the necessary mappings in a platform specific manner.

RETURN VALUES
    The ndi_irm_create() and ndi_irm_destroy() functions return:

    NDI_SUCCESS		On success.

    NDI_FAILURE		An invalid description was provided when
			creating an interrupt pool.  Or an invalid
			pointer was used to destroy an interrupt pool.

    NDI_BUSY		An interrupt pool could not be destroyed since
			device drivers are still actively consuming
			interrupts from the pool.

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

     ____________________________________________________________
    |      ATTRIBUTE TYPE	|	    ATTRIBUTE VALUE      |
    |___________________________|________________________________|
    | Interface Stability	| Consolidation Private          |
    |___________________________|________________________________|
    | MT-Level			| MT-Safe                        |
    |___________________________|________________________________|