InterruptAttachThread(), InterruptAttachThread_r()

Arguments:

intr

The interrupt vector number that you want to attach a thread to; see Interrupt vector numbers, below.

flags

Flags that specify how you want to attach the interrupt thread; a bitwise OR of zero or more of the following:

• _NTO_INTR_FLAGS_END
• _NTO_INTR_FLAGS_NO_UNMASK
• _NTO_INTR_FLAGS_EXCLUSIVE
• _NTO_INTR_FLAGS_CPU_LOCAL

For more information, see Flags, below.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The InterruptAttachThread() and InterruptAttachThread_r() kernel calls attach the calling thread with an interrupt, at which point the calling thread becomes an Interrupt Service Thread (IST). The IST can then invoke other interrupt calls (e.g. InterruptWait(), InterruptDetach()) to wait,detach, etc.

The kernel automatically masks the interrupt before scheduling the attached thread. To receive interrupts after processing, you must either explicitly unmask the interrupt by calling InterruptUnmask(), or have the kernel do so automatically by passing the _NTO_INTR_WAIT_FLAGS_UNMASK when calling InterruptWait().

The InterruptAttachThread() and InterruptAttachThread_r() calls are identical except in the way they indicate errors; see the Returns section for details.

Before a process calls either of these functions, it must have the PROCMGR_AID_INTERRUPT ability enabled. For more information, go to Abilities in the System Security Guide.

Interrupt vector numbers

The interrupt values for intr are logical interrupt vector numbers grouped into related interrupt classes that generally correspond to a particular interrupt controller on the CPU.

There can be additional interrupt classes defined for specific CPUs or embedded systems. For the interrupt assignments for specific boards, see:

• some *intr.h files in the platform-specific directories under ${QNX_TARGET}/usr/include
• the init_intrinfo() function in the startup code of your BSP
• the buildfiles in the Board Support Package for your board

The mapping of logical interrupt vector numbers is completely dependent on the implementer of the startup code. Device drivers should generally allow runtime configuration of interrupt numbers.

Flags

The flags argument is a bitwise OR of zero or more of the following values:

_NTO_INTR_FLAGS_END

Put the new thread at the end of the list of existing threads (for shared interrupts) instead of the start.

_NTO_INTR_FLAGS_NO_UNMASK

Leave the interrupt masked.

Normally, InterruptAttachThread() automatically unmasks an interrupt the first time something is attached to it. If you specify _NTO_INTR_FLAGS_NO_UNMASK, the kernel leaves the interrupt masked, and you must specifically call InterruptUnmask() to enable it.

Note:

The _NTO_INTR_FLAGS_NO_UNMASK flag only applies to the first call to InterruptAttachThread(), and therefore, won't apply to subsequent calls with the same intr value.

_NTO_INTR_FLAGS_EXCLUSIVE

Request exclusive access to the interrupt vector. If another thread already called an InterruptAttach*() function with the same vector, this kernel call fails with an EBUSY error. Similarly, if this call succeeds but another thread later calls an InterruptAttach*() function with the same vector, that call fails with the same error.

_NTO_INTR_FLAGS_CPU_LOCAL

Attach the thread to the interrupt vector number for the current CPU; the thread's runmask should be set to run on a single CPU.

Blocking states

These calls don't block.

Returns:

A unique interrupt ID that corresponds with the process that called InterruptAttachThread(). If an error occurs:

• InterruptAttachThread() returns -1 and sets errno.
• InterruptAttachThread_r() returns the negative of a value from the Errors section and doesn't set errno.

Pass this interrupt ID to other calls, such as InterruptDetach() and InterruptMask().

Errors:

EAGAIN

One of the following errors occurred:

• Not enough memory is available.
• All kernel interrupt entries are in use.
• The maximum number (32) of threads or events that can be attached to an interrupt has been exceeded.

EBUSY

One of the following errors occurred:

• The specified thread is already attached to an interrupt.
• You tried to attach a thread to an interrupt, but a thread with the _NTO_INTR_FLAGS_EXCLUSIVE flag was already attached to the interrupt.
• You tried to attach a thread with the _NTO_INTR_FLAGS_EXCLUSIVE flag to an interrupt, but a thread was already attached to the interrupt.

EINVAL

The value of intr isn't a valid interrupt number, or you specified the _NTO_INTR_FLAGS_CPU_LOCAL flag but the thread's runmask isn't set to run on a single CPU.

EPERM

The process doesn't have the required permission; see procmgr_ability().

Classification:

QNX OS