'\"macro stdmacro
.if n .pH ddi_dki.int @(#)int	40.8 of 1/3/90
.\" Copyright 1989 AT&T
.de IX
.ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9	\\n%
.el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.nr X
.if \nX=0 .ds x} int D2D "3B2" "DDI" "\&"
.if \nX=1 .ds x} int D2D "3B2" "DDI"
.if \nX=2 .ds x} int D2D "" "\&"
.if \nX=3 .ds x} int "" "" "\&"
.TH \*(x}
.IX "\f4int\fP(D2D)"
.SH "NAME"
\f4int\f1 \- process a device interrupt
.SH "SYNOPSIS"
.nf
.na
void \f2prefix\f4int(\f4int\f1 \f2ivec\f4);\f1
.ad
.fi
.SH "ARGUMENT"
.TP .4i
\f2ivec\f1
Number used by the operating system to associate a driver's interrupt
handler with an interrupting device.  The makeup and interpretation of
\f2ivec\f1 is specific to each system implementation.  In some systems,
this number may be the logical device number, or a combination of
logical device and logical controller numbers, used to map the correct
interrupt routine with a subdevice.  In others, this number could be the
interrupt vector number. 
.SH "DESCRIPTION"
The \f4int\f1 routine is the interrupt handler for both block and
character hardware drivers.  The interrupt handler is responsible for
determining the reason for an interrupt, servicing the interrupt, and
waking up any base-level driver processes sleeping on the interrupt
completion.  For example, when a disk drive has transfered
information to the host to satisfy a read request, the disk drive's
controller generates an interrupt.  The CPU acknowledges the interrupt
and calls the interrupt handler associated with that controller and disk drive. 
The interrupt routine services the interrupt and then wakes up the
driver base-level process waiting for data.  The base-level portion of
the driver then conveys the data to the user.
.P
In general, most interrupt routines must do the following tasks:
.PD .25
.IP
keep a record of interrupt occurrences
.IP
return immediately if no devices controlled by a driver
caused the interrupt (only for systems supporting shared interrupts)
.IP
interpret the interrupt routine argument \f2ivec\f1
.IP
reject requests for devices that are not served by the device's controller
.IP
process interrupts that happen without cause (called spurious interrupts)
.IP
handle all possible device errors
.IP
wake processes that are sleeping on the resolution of an interrupt request
.PD
.P
There are also many tasks the \f4int\f1 routine must perform that are
driver-type and device specific.  For example, the following types of
drivers require different functions from their \f4int\f1 routines:
.IP
A block driver
dequeues requests,
wakes up processes sleeping on an I/O request,
and ensures that system generation has completed.
.IP
A terminal driver
receives and sends characters.
.IP
A printer driver
ensures that characters are sent.
.P
In addition, the functions of an \f4int\f1 routine are device
dependent.  You should know the exact chip set that produces the
interrupt for your device.  You need to know the exact bit patterns of
the device's control and status register and how data is transmitted
into and out of your computer.  These specifics differ for every device
you access.
.P
The \f4int\f1 routine for an intelligent controller
that does not use individual interrupt vectors for each subdevice
must access the completion queue to determine
which subdevice generated the interrupt.
It must also update the status information,
set/clear flags, set/clear error indicators,
and so forth to complete the handling of a job.
The code should also be able to handle a
spurious completion interrupt
identified by an empty completion queue.
.ig
(\f4logstray(D3D)\f1 is provided for
this purpose).
..
When the routine finishes,
it should advance the unload pointer to
the next entry in the completion queue.
.P
If the driver called \f4biowait\f1(D3DK) or \f4sleep\f1(D3DK)
to await the completion of an operation,
the \f4int\f1 routine must call
\f4biodone\f1(D3DK) or \f4wakeup\f1(D3DK) to signal
the process to resume.
.P
\f4int\f1 is only used with hardware drivers, not software drivers.
.P
\f3CAUTION:\f1
The \f4int\f1 routine must never:
.IP
contain calls to the \f4sleep\f1 kernel function
.IP
use functions that call \f4sleep\f1
.IP
drop the interrupt priority level below the level at which the interrupt
routine was entered
.IP
call any function or routine that requires user context (that is, if
it accesses or alters information associated with the running process)
.P
\f3NOTE:\f1
\f4uiomove\f1(D3DK) cannot be used in an interrupt routine when the
\f4uio_segflg\f1 member of the \f4uio\f1(D4DK) structure 
is set to \f4UIO_USERSPACE\f1
(indicating a transfer between user and kernel space).
.SH "SEE ALSO"
.na
\f4biowait\f1(D3DK),
\f4sleep\f1(D3DK),
\f4biodone\f1(D3DK),
\f4wakeup\f1(D3DK)
.ad
