intr(D2)

NAME
     intr - process a device interrupt

SYNOPSIS
     void prefixintr(int ivec);

   Arguments
     ivec      Number used by the operating system to associate a driver's
               interrupt handler with an interrupting device.  For a VME
               device, this number can be the logical device number, the
               interrupt vector number, or the address which is set by
               vme_ivec_set(). For a SCSI device, this number is a pointer to
               a scsi_request_t type structure.

DESCRIPTION
     The intr routine is the interrupt handler for both block and character
     hardware drivers, as well as for non-driver hardware modules.

   Return Values
     None

USAGE
     This entry point is only required for those modules that interface to
     hardware that interrupts the host computer.  It is not used with software
     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 any events associated with the interrupt.

     For example, when a disk drive has transferred 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.

     In general, most interrupt routines do the following tasks:

          keep a record of interrupt occurrences

          return immediately if no devices controlled by a driver caused the
          interrupt (only for systems supporting shared interrupts)

          interpret the interrupt routine argument ivec

          reject requests for devices that are not served by the device's
          controller

          process interrupts that happen without cause (called spurious
          interrupts)

          handle all possible device errors

          wake processes that are sleeping on any events associated with the
          interrupt

     There are also many tasks the intr routine must perform that are driver-
     type and device specific.  For example, the following types of drivers
     require different functions from their intr routines:

          A block driver dequeues requests and wakes up processes sleeping on
          an I/O request.

          A terminal driver receives and sends characters.

          A printer driver ensures that characters are sent.

     In addition, the functions of an intr 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.

     The intr 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.  When the routine finishes, it
     should advance the unload pointer to the next entry in the completion
     queue.

     If the driver called biowait(D3) or sleep(D3) to await the completion of
     an operation, the intr routine must call biodone(D3) or wakeup(D3) to
     signal the process to resume.

     The interrupt routine runs at the processor level associated with the
     interrupt level for the given device.  Lower priority interrupts are
     deferred while the interrupt routine is active.  Certain processor levels
     can block different interrupts.  See spl(D3) for more information.

     uiomove(D3), ureadc(D3), and uwritec(D3) cannot be used in an interrupt
     routine when the uio_segflg member of the uio(D4) structure is set to
     UIO_USERSPACE (indicating a transfer between user and kernel space).

   Synchronization Constraints
     The intr routine must never:
          use functions that sleep

          drop the interrupt priority level below the level at which the
          interrupt routine was entered

          call any function or routine that requires user context (that is, if
          it accesses or alters information associated with the running
          process)

REFERENCES
     biodone(D3), biowait(D3), spl(D3), wakeup(D3), vme_ivec_set(D3X)