ddi_add_intr(9F)
NAME
ddi_add_intr, ddi_get_iblock_cookie, ddi_remove_intr -
hardware interrupt handling routines
SYNOPSIS
#include <sys/types.h>
#include <sys/conf.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>
int ddi_get_iblock_cookie(dev_info_t *dip, uint_t inumber,
ddi_iblock_cookie_t *iblock_cookiep);
int ddi_add_intr(dev_info_t *dip, uint_t inumber,
ddi_iblock_cookie_t *iblock_cookiep, ddi_idevice_cookie_t
*idevice_cookiep, uint_t (*int_handler) (caddr_t), caddr_t
int_handler_arg);
void ddi_remove_intr(dev_info_t *dip, uint_t inumber,
ddi_iblock_cookie_t iblock_cookie);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI).
PARAMETERS
For ddi_get_iblock_cookie():
dip Pointer to dev_info structure.
inumber
Interrupt number.
iblock_cookiep
Pointer to an interrupt block cookie.
For ddi_add_intr():
dip Pointer to dev_info structure.
inumber
Interrupt number.
iblock_cookiep
Optional pointer to an interrupt block cookie where a
returned interrupt block cookie is stored.
idevice_cookiep
Optional pointer to an interrupt device cookie where a
returned interrupt device cookie is stored.
int_handler
Pointer to interrupt handler.
int_handler_arg
Argument for interrupt handler.
For ddi_remove_intr():
dip Pointer to dev_info structure.
inumber
Interrupt number.
iblock_cookie
Block cookie which identifies the interrupt handler to
be removed.
DESCRIPTION
ddi_get_iblock_cookie()
ddi_get_iblock_cookie() retrieves the interrupt block cookie
associated with a particular interrupt specification. This
routine should be called before ddi_add_intr() to retrieve
the interrupt block cookie needed to initialize locks
(mutex(9F), rwlock(9F)) used by the interrupt routine. The
interrupt number inumber determines for which interrupt
specification to retrieve the cookie. inumber is associated
with information provided either by the device (see sbus(4))
or the hardware configuration file (see sysbus(4), isa(4),
eisa(4), and driver.conf(4)). If only one interrupt is asso-
ciated with the device, inumber should be 0.
On a successful return, *iblock_cookiep contains information
needed for initializing locks associated with the interrupt
specification corresponding to inumber (see mutex_init(9F)
and rw_init(9F)). The driver can then initialize locks
acquired by the interrupt routine before calling
ddi_add_intr() which prevents a possible race condition
where the driver's interrupt handler is called immediately
after the driver has called ddi_add_intr() but before the
driver has initialized the locks. This may happen when an
interrupt for a different device occurs on the same inter-
rupt level. If the interrupt routine acquires the lock
before the lock has been initialized, undefined behavior may
result.
ddi_add_intr()
ddi_add_intr() adds an interrupt handler to the system. The
interrupt number inumber determines which interrupt the
handler will be associated with. (Refer to
ddi_get_iblock_cookie() above.)
On a successful return, iblock_cookiep contains information
used for initializing locks associated with this interrupt
specification (see mutex_init(9F) and rw_init(9F)). Note
that the interrupt block cookie is usually obtained using
ddi_get_iblock_cookie() to avoid the race conditions
described above (refer to ddi_get_iblock_cookie() above).
For this reason, iblock_cookiep is no longer useful and
should be set to NULL.
On a successful return, idevice_cookiep contains a pointer
to a ddi_idevice_cookie_t structure (see
ddi_idevice_cookie(9S)) containing information useful for
some devices that have programmable interrupts. If
idevice_cookiep is set to NULL, no value is returned.
The routine intr_handler, with its argument int_handler_arg,
is called upon receipt of the appropriate interrupt. The
interrupt handler should return DDI_INTR_CLAIMED if the
interrupt was claimed, DDI_INTR_UNCLAIMED otherwise.
If successful, ddi_add_intr() will return DDI_SUCCESS.
DDI_INTR_NOTFOUND is returned on i86pc and sun4m architec-
tures if the interrupt information cannot be found. If the
interrupt information cannot be found on the sun4u architec-
ture, either DDI_INTR_NOTFOUND or DDI_FAILURE can be
returned.
ddi_remove_intr()
ddi_remove_intr() removes an interrupt handler from the sys-
tem. Unloadable drivers should call this routine during
their detach(9E) routine to remove their interrupt handler
from the system.
The device interrupt routine for this instance of the device
will not execute after ddi_remove_intr() returns.
ddi_remove_intr() may need to wait for the device interrupt
routine to complete before returning. Therefore, locks
acquired by the interrupt handler should not be held across
the call to ddi_remove_intr() or deadlock may result.
For All Three Functions:
For certain bus types, you can call these DDI functions from
a high-interrupt context. These types include ISA, EISA, and
SBus buses. See sysbus(4), isa(4), eisa(4), and sbus(4) for
details.
RETURN VALUES
ddi_add_intr() and ddi_get_iblock_cookie() return:
DDI_SUCCESS
On success.
DDI_INTR_NOTFOUND
On failure to find the interrupt.
DDI_FAILURE
On failure. DDI_FAILURE can also be returned on
failure to find interrupt (sun4u).
CONTEXT
ddi_add_intr(), ddi_remove_intr(), and
ddi_get_iblock_cookie() can be called from user or kernel
context.
SEE ALSO
driver.conf(4), eisa(4), isa(4), sbus(4), sysbus(4),
attach(9E), detach(9E), ddi_intr_hilevel(9F), mutex(9F),
mutex_init(9F), rw_init(9F), rwlock(9F),
ddi_idevice_cookie(9S)
Writing Device Drivers
NOTES
ddi_get_iblock_cookie() must not be called after the driver
adds an interrupt handler for the interrupt specification
corresponding to inumber.
All consumers of these interfaces, checking return codes,
should verify return_code != DDI_SUCCESS. Checking for
specific failure codes can result in inconsistent behaviors
among platforms.
BUGS
The idevice_cookiep should really point to a data structure
that is specific to the bus architecture that the device
operates on. Currently the SBus and PCI buses are supported
and a single data structure is used to describe both.
Man(1) output converted with
man2html