io_on_interrupt(3I)

NAME

io_on_interrupt() — device interrupt (fault) control (OBSOLETED AT 10.30)

SYNOPSIS

#include <dvio.h> 

int (*io_on_interrupt( 
     int eid, 
     struct interrupt_struct *causevec, 
     int (*handler)(int, struct interrupt_struct *) 
))(int, struct interrupt_struct *); 

DESCRIPTION

eid is an entity identifier of an open HP-IB raw bus, Centronics-compatible parallel interface, or GPIO device file, obtained from an open(), dup(), fcntl(), or creat() call.

causevec is a pointer to a structure of the form:

struct interrupt_struct { 
    integer	cause; 
    integer	mask; 
}; 

The interrupt_struct structure is defined in the file dvio.h.

cause is a bit vector specifying which of the interrupt or fault events can cause the handler routine to be invoked. The interrupt causes are often specific to the type of interface being considered. Also, certain exception (error) conditions can be handled using the io_on_interrupt() capability. Specifying a zero valued cause vector effectively turns off the interrupt for that eid.

The mask parameter is used when an HP-IB parallel poll interrupt is being defined. mask is an integer that specifies which parallel poll response lines are of interest. The value of mask is viewed as an 8-bit binary number where the least significant bit corresponds to line DIO1; the most significant bit to line DIO8. For example, to activate an interrupt handler when a response occurs on lines 2 or 6, the correct binary number is 00100010. Thus a hexadecimal value of 22 is the correct argument value for mask.

When an enabled interrupt condition on the specified eid occurs, the receiving process executes the interrupt-handler function pointed to by handler. The entity identifier eid and the interrupt condition cause are returned as the first and second parameters, respectively.

When an interrupt that is to be caught occurs during a read(), write(), open(), or ioctl() system call on a slow device such as a terminal (but not a file), during a pause() system call, a sigpause() system call, or a wait() system call that does not return immediately due to the existence of a previously stopped or zombie process, the interrupt handling function is executed and the interrupted system call returns -1 to the calling process with errno set to EINTR.

Interrupt handlers are not inherited across a fork(). eids for the same device file produced by dup() share the same handler.

An interrupt for a given eid is implicitly disabled after the occurrence of the event. The interrupt condition can be re-enabled by using io_interrupt_ctl() (see io_interrupt_ctl(3I)).

When an event specified by cause occurs, the receiving process executes the interrupt handler function pointed to by handler. When the handler returns, the user process resumes at the execution point where the event occurred.

Two parameters are passed to handler: the eid associated with the event, and a pointer to a causevec structure. The cause of the interrupt can be determined by the value returned in the cause field of the causevec structure (more than 1 bit can be set, indicating that more than 1 interrupting condition has occurred). If the interrupt handler was invoked due to a parallel poll interrupt, the mask field of the causevec structure contains the parallel poll response byte.

HP-IB Interrupts

This section describes interrupt causes specific to an HP-IB device. For an HP-IB device, the cause is a bit vector which is used as follows. To enable a given event, the appropriate bit (in cause), shown below, must be set to 1:

SRQ: SRQ and active controller
TLK: Talker addressed
LTN: Listener addressed
TCT: Controller in charge
IFC: IFC has been asserted
REN: Remote enable
DCL: Device clear
GET: Group execution trigger
PPOLL: Parallel poll

GPIO Interrupts

This section describes interrupt causes specific to a GPIO device. For a GPIO device, cause is a bit vector which is used as follows. To enable a given event, the appropriate bit (in cause), shown below, must be set to 1:

EIR: External interrupt
SIE0: Status line 0
SIE1: Status line 1

Parallel Interrupts

This section describes interrupt causes specific to a Centronics-compatible parallel device. For a Centronics-compatible parallel device, cause is a bit vector which is used as follows. To enable a given event, the appropriate bit (in cause), shown below, must be set to 1:

NERROR: Nerror interrupt
SELECT: Select interrupt
PE: Paper error interrupt

RETURN VALUE

io_on_interrupt() returns a pointer to the previous handler if the new handler is successfully installed; otherwise it returns a -1 and sets errno to indicate the error.

ERRORS

io_on_interrupt() fails for any of the following reasons and sets errno to the value indicated:

[EACCES]: The interface associated with this eid is locked by another process and O_NDELAY is set for this eid (see io_lock(3I)).
[EBADF]: eid does not refer to an open file.
[ENOTTY]: eid does not refer to a GPIO, Centronics-compatible parallel, or a raw HP-IB device file.
[EFAULT]: handler points to an illegal address. The reliable detection of this error is implementation dependent.
[EFAULT]: causevec points to an illegal address. The reliable detection of this error is implementation dependent.

DEPENDENCIES

For the HP 27114 AFI interface, only the EIR interrupt is available.

AUTHOR

io_on_interrupt() was developed by HP.