[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 1

i_init Kernel Service

Purpose

Defines an interrupt handler.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/intr.h>
int i_init 
(handler)
struct intr *handler;

Parameter

handler Designates the address of the pinned interrupt handler structure.

Description

Attention: The interrupt handler structure must not be altered between the call to the i_init service to define the interrupt handler and the call to the i_clear service to remove the interrupt handler. The structure must also stay pinned. If this structure is altered at those times, a kernel panic may result.

The i_init service allows device drivers to define an interrupt handler to the kernel. The interrupt handler intr structure pointed to by the handler parameter describes the interrupt handler. The caller of the i_init service must initialize all the fields in the intr structure. The /usr/include/sys/intr.h file defines these fields and their valid values.

The i_init service enables interrupts by linking the interrupt handler structure to the end of the list of interrupt handlers defined for that bus level. If this is the first interrupt handler for the specified bus interrupt level, the i_init service enables the bus interrupt level by calling the i_unmask service.

The interrupt handler can be called before the i_init service returns if the following two conditions are met:

On multiprocessor systems, all interrupt handlers defined with the i_init kernel service run by default on the first processor started when the system was booted. This ensures compatibility with uniprocessor interrupt handlers. If the interrupt handler being defined has been designed to be multiprocessor-safe, or is an EPOW (Early Power-Off Warning) or off-level interrupt handler, set the INTR_MPSAFE flag in the flags field of the intr structure passed to the i_init kernel service. The interrupt handler will then run on any available processor.

Coding an Interrupt Handler

The kernel calls the interrupt handler when an enabled interrupt occurs on that bus interrupt level. The interrupt handler is responsible for determining if the interrupt is from its own device and processing the interrupt. The interface to the interrupt handler is as follows:

int interrupt_handler (handler)
struct intr *handler;

The handler parameter points to the same interrupt handler structure specified in the call to the i_init kernel service. The device driver can pass additional parameters to its interrupt handler by declaring the interrupt handler structure to be part of a larger structure that contains these parameters.

The interrupt handler can return one of two return values. A value of INTR_SUCC indicates that the interrupt handler processed the interrupt and reset the interrupting device. A value of INTR_FAIL indicates that the interrupt was not from this interrupt handler's device.

Registering Early Power-Off Warning (EPOW) Routines

The i_init kernel service can also be used to register an EPOW (Early Power-Off Warning) notification routine.

The return value from the EPOW interrupt handler should be INTR_SUCC, which indicates that the interrupt was successfully handled. All registered EPOW interrupt handlers are called when an EPOW interrupt is indicated.

Execution Environment

The i_init kernel service can be called from the process environment only.

Return Values

INTR_SUCC Indicates a successful completion.
INTR_FAIL Indicates an unsuccessful completion. The i_init service did not define the interrupt handler.

An unsuccessful completion occurs when there is a conflict between a shared and a nonshared bus interrupt level. An unsuccessful completion also occurs when more than one interrupt priority is assigned to a bus interrupt level.

Implementation Specifics

The i_init kernel service is part of Base Operating System (BOS) Runtime.

Related Information

Understanding Interrupts, I/O Kernel Services, in AIX Kernel Extensions and Device Support Programming Concepts.

[ Previous | Next | Contents | Home | Search ]