te
Copyright (c) 2005, 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_add_handler, ddi_intr_remove_handler - add or remove interrupt handler

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



int ddi_intr_add_handler(ddi_intr_handle_t *h, 
 ddi_intr_handler_t inthandler, void *arg1,
 void *arg2);

int ddi_intr_remove_handler(ddi_intr_handle_t h);

Solaris DDI specific (Solaris DDI).

ddi_intr_add_handler()

h

inthandler

arg1

arg2

ddi_intr_remove_handler()

h

The ddi_intr_add_handler() function adds an interrupt handler given by the inthandler argument to the system with the handler arguments arg1 and arg2 for the previously allocated interrupt handle specified by the h pointer. The arguments arg1 and arg2 are passed as the first and second arguments, respectively, to the interrupt handler inthandler. See <sys/ddi_intr.h> for the definition of the interrupt handler.

The routine inthandler with the arguments arg1 and arg2 is called upon receipt of the appropriate interrupt. The interrupt handler should return DDI_INTR_CLAIMED if the interrupt is claimed and DDI_INTR_UNCLAIMED otherwise.

The ddi_intr_add_handler() function must be called after ddi_intr_alloc(), but before ddi_intr_enable() is called. The interrupt must be enabled through ddi_intr_enable() or ddi_intr_block_enable() before it can be used.

The ddi_intr_remove_handler() function removes the handler association, added previously with ddi_intr_add_handler(), for the interrupt identified by the interrupt handle h argument. Unloadable drivers should call this routine during their detach(9E) routine to remove the interrupt handler from the system.

The ddi_intr_remove_handler() function is used to disassociate the handler after the interrupt is disabled to remove dup-ed interrupt handles. See ddi_intr_dup_handler(9F) for dup-ed interrupt handles. If a handler is duplicated with the ddi_intr_dup_handler() function, all added and duplicated instances of the handler must be removed with ddi_intr_remove_handler() in order for the handler to be completely removed.

The ddi_intr_add_handler() and ddi_intr_remove_handler() functions return:

DDI_SUCCESS

DDI_EINVAL

DDI_FAILURE

The ddi_intr_add_handler() and ddi_intr_remove_handler() functions can be called from kernel non-interrupt context.

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed

attributes(5), attach(9E), detach(9E), ddi_intr_alloc(9F), ddi_intr_block_enable(9F), ddi_intr_disable(9F), ddi_intr_dup_handler(9F), ddi_intr_enable(9F), ddi_intr_free(9F), ddi_intr_get_supported_types(9F), mutex(9F), mutex_init(9F), rw_init(9F), rwlock(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.

The second argument, arg2, is optional. Device drivers are free to use the two arguments however they see fit. There is no officially recommended model or restrictions. For example, an interrupt handler may wish to use the first argument as the pointer to its softstate and the second argument as the value of the MSI vector.