InterruptAttachEvent(), InterruptAttachEvent_r()

Attach an event to an interrupt source

Synopsis:

#include <sys/neutrino.h>

int InterruptAttachEvent( 
       int intr,
       const struct sigevent* event,
       unsigned flags );

int InterruptAttachEvent_r( 
       int intr,
       const struct sigevent* event,
       unsigned flags );

Library:

libc

Description:

The InterruptAttachEvent() and InterruptAttachEvent_r() kernel calls attach the event to an interrupt specified by intr. They automatically enable (i.e unmask) the interrupt level.

The intr variable represents an interrupt vector number; see "Interrupt vector numbers" in the InterruptAttach() documentation for details.

Before calling this function, the thread must request I/O privity by calling:

 
ThreadCtl( _NTO_TCTL_IO, 0 );

If the thread doesn't do this, it might SIGSEGV when InterruptUnlock() is called.

To prevent infinite interrupt recursion, the kernel automatically does an InterruptMask() for intr when delivering the event. After the interrupt-handling thread has dealt with the event, it must call InterruptUnmask() to reenable the interrupt.

The event delivered when this interrupt occurs is a sigevent structure.

Consider the following when choosing an event type:

• Message-driven processes that block in a receive loop using MsgReceivev() should consider using SIGEV_PULSE to trigger a channel.
• Threads that block at a particular point in their code and don't go back to a common receive point, should consider using SIGEV_INTR as the event notification type and InterruptWait() as the blocking call.

  ---

  The thread that calls InterruptWait() must be the one that called InterruptAttachEvent().

  ---

• Using SIGEV_SIGNAL, SIGEV_SIGNAL_CODE, or SIGEV_SIGNAL_THREAD is discouraged. It is less efficient than the other mechanisms for interrupt event delivery.

flags summary

The flags argument is a bitwise OR of the following values, or 0:

_NTO_INTR_FLAGS_END

The interrupt structure allows hardware interrupts to be shared. For example if two processes call InterruptAttachEvent() for the same physical interrupt, both events are sent consecutively. When an event attaches, it'll be placed in front of any existing events for that interrupt and be delivered first. This behavior can be changed by setting the _NTO_INTR_FLAGS_END flag in the flags argument. This adds the event at the end of any existing events.

_NTO_INTR_FLAGS_PROCESS

Adding _NTO_INTR_FLAGS_PROCESS to flags associates the interrupt event with the process instead of the attaching thread. The interrupt event is removed when the process exits, instead of when the attaching thread exits.

The kernel automatically attempts to set the _NTO_INTR_FLAGS_PROCESS flag if the event is directed at the process in general (for SIGEV_SIGNAL, SIGEV_SIGNAL_CODE, and SIGEV_PULSE events).

_NTO_INTR_FLAGS_TRK_MSK

The _NTO_INTR_FLAGS_TRK_MSK flag and the id argument to InterruptMask() and InterruptUnmask() let the kernel track the number of times a particular interrupt handler or event has been masked. Then, when an application detaches from the interrupt, the kernel can perform the proper number of unmasks to ensure that the interrupt functions normally. This is important for shared interrupt levels.

Advantages & disadvantages

InterruptAttachEvent() has several advantages over InterruptAttach():

• Less work is done at interrupt time (you avoid the context switch necessary to map in an interrupt handler).
• Interrupt handling code runs at the thread's priority, which lets you prioritize interrupt handling.
• You can use process-level debugging on your interrupt handler code.

There are also some disadvantages:

• It'll take longer before the interrupt handling code runs (until the thread is scheduled to run).
• For multiple devices sharing an event, the amount of time with the interrupt masked increases.

You can freely mix calls to InterruptAttach() and InterruptAttachEvent() for a particular interrupt.

Blocking states

This call doesn't block.

Returns:

An interrupt function ID; or -1 if an error occurs (errno is set).

Use this ID with the InterruptDetach() function to detach this interrupt event.

Errors:

EAGAIN

All kernel interrupt entries are in use.

EFAULT

A fault occurred when the kernel tried to access the buffers provided.

EINVAL

The value of intr isn't a valid interrupt number.

EPERM

The process doesn't have superuser capabilities.

Classification:

QNX 6

See also:

InterruptAttach(), InterruptDetach(), InterruptLock(), InterruptMask(), InterruptUnlock(), InterruptUnmask(), InterruptWait(), sigevent