te
Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
ddi_intr_alloc, ddi_intr_free - allocate or free interrupts for a given interrupt type

#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);

illumos DDI specific (illumos DDI). ddi_intr_alloc() dip h_array type inum count actualp behavior

ddi_intr_free() h

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 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 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 behavior flag controls the interrupt allocation algorithm. It takes one of two input values: DDI_INTR_ALLOC_NORMAL or DDI_INTR_ALLOC_STRICT. If the count value used is greater than NINTRs, then the call fails with DDI_EINVAL unconditionally. When set to DDI_INTR_ALLOC_STRICT, the call succeeds if and only if count interrupts are allocated. Otherwise, the call fails, and the number of available interrupts is returned in actualp. When set to DDI_INTR_ALLOC_NORMAL, the call succeeds if at least one interrupt is allocated, and the number of allocated interrupts is returned in actualp.

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 DDI_EAGAIN DDI_EINVAL DDI_INTR_NOTFOUND DDI_FAILURE The ddi_intr_alloc() and ddi_intr_free() functions can be called from kernel non-interrupt context. See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Committed

attributes (7), 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)

Writing Device Drivers

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.