Kernel Functions for Drivers ddiaddintr(9F)
NAME
ddiaddintr, ddigetiblockcookie, ddiremoveintr -
hardware interrupt handling routines
SYNOPSIS
#include
#include
#include
#include
int ddigetiblockcookie(devinfot *dip, uintt inumber,
ddiiblockcookiet *iblockcookiep);
int ddiaddintr(devinfot *dip, uintt inumber,
ddiiblockcookiet *iblockcookiep,
ddiidevicecookiet *idevicecookiep,
uintt (*inthandler) (caddrt),
caddrt inthandlerarg);
void ddiremoveintr(devinfot *dip,
uintt inumber, ddiiblockcookiet iblockcookie);
INTERFACE LEVEL
Solaris DI specific (Solaris DI). These interfaces are
obsolete. Use the new interrupt interfaces referenced in
Intro(9F). Refer to Writing Device Drivers for more informa-
tion.
PARAMETERS
For ddigetiblockcookie():
dip Pointer to devinfo structure.
inumber Interrupt number.
iblockcookiep Pointer to an interrupt block cookie.
For ddiaddintr():
dip Pointer to devinfo structure.
SunOS 5.11 Last change: 19 Oct 2005 1
Kernel Functions for Drivers ddiaddintr(9F)
inumber Interrupt number.
iblockcookiep Optional pointer to an interrupt block
cookie where a returned interrupt block
cookie is stored.
idevicecookiep Optional pointer to an interrupt device
cookie where a returned interrupt device
cookie is stored.
inthandler Pointer to interrupt handler.
inthandlerarg Argument for interrupt handler.
For ddiremoveintr():
dip Pointer to devinfo structure.
inumber Interrupt number.
iblockcookie Block cookie which identifies the interrupt
handler to be removed.
DESCRIPTION
ddigetiblockcookie()
ddigetiblockcookie() retrieves the interrupt block cookie
associated with a particular interrupt specification. This
routine should be called before ddiaddintr() 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),
and driver.conf(4)). If only one interrupt is associated
with the device, inumber should be 0.
On a successful return, *iblockcookiep contains information
needed for initializing locks associated with the interrupt
specification corresponding to inumber (see mutexinit(9F)
and rwinit(9F)). The driver can then initialize locks
acquired by the interrupt routine before calling
SunOS 5.11 Last change: 19 Oct 2005 2
Kernel Functions for Drivers ddiaddintr(9F)
ddiaddintr() which prevents a possible race condition
where the driver's interrupt handler is called immediately
after the driver has called ddiaddintr() 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.
ddiaddintr()
ddiaddintr() adds an interrupt handler to the system. The
interrupt number inumber determines which interrupt the
handler will be associated with. (Refer to
ddigetiblockcookie() above.)
On a successful return, iblockcookiep contains information
used for initializing locks associated with this interrupt
specification (see mutexinit(9F) and rwinit(9F)). Note
that the interrupt block cookie is usually obtained using
ddigetiblockcookie() to avoid the race conditions
described above (refer to ddigetiblockcookie() above).
For this reason, iblockcookiep is no longer useful and
should be set to NUL.
On a successful return, idevicecookiep contains a pointer
to a ddiidevicecookiet structure (see
ddiidevicecookie(9S)) containing information useful for
some devices that have programmable interrupts. If
idevicecookiep is set to NUL, no value is returned.
The routine intrhandler, with its argument inthandlerarg,
is called upon receipt of the appropriate interrupt. The
interrupt handler should return DINTRCLAIMED if the
interrupt was claimed, DINTRUNCLAIMED otherwise.
If successful, ddiaddintr() returns DISUCES. If the
interrupt information cannot be found on the sun4u architec-
ture, either DINTRNOTFOUND or DIFAILURE can be
returned. On i86pc and sun4m architectures, if the interrupt
information cannot be found, DINTRNOTFOUND is returned.
ddiremoveintr()
ddiremoveintr() 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.
SunOS 5.11 Last change: 19 Oct 2005 3
Kernel Functions for Drivers ddiaddintr(9F)
The device interrupt routine for this instance of the device
will not execute after ddiremoveintr() returns.
ddiremoveintr() 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 ddiremoveintr() or deadlock may result.
For All Three Functions:
For certain bus types, you can call these DI functions from
a high-interrupt context. These types include ISA and SBus
buses. See sysbus(4), isa(4), and sbus(4) for details.
RETURN VALUES
ddiaddintr() and ddigetiblockcookie() return:
DISUCES On success.
DINTRNOTFOUND On failure to find the interrupt.
DIFAILURE On failure. DIFAILURE can also be
returned on failure to find interrupt
(sun4u).
CONTEXT
ddiaddintr(), ddiremoveintr(), and
ddigetiblockcookie() can be called from user or kernel
context.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Obsolete
SEE ALSO
driver.conf(4), isa(4), sbus(4), sysbus(4), attach(9E),
detach(9E), ddiintrhilevel(9F), Intro(9F), mutex(9F),
mutexinit(9F), rwinit(9F), rwlock(9F),
ddiidevicecookie(9S)
SunOS 5.11 Last change: 19 Oct 2005 4
Kernel Functions for Drivers ddiaddintr(9F)
Writing Device Drivers
NOTES
ddigetiblockcookie() 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 returncode != DISUCES. Checking for
specific failure codes can result in inconsistent behaviors
among platforms.
BUGS
The idevicecookiep 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.
SunOS 5.11 Last change: 19 Oct 2005 5
|
