InterruptMask()

Updated: October 28, 2024

Disable a hardware interrupt

Synopsis:

#include <sys/neutrino.h>

int InterruptMask( int intr, 
                   int id );

Arguments:

intr
The interrupt you want to mask.
id
The value returned by InterruptAttach(), InterruptAttachArray(), or InterruptAttachEvent(), or -1 if you don't want the kernel to track interrupt maskings and unmaskings for each handler.

If you set the _NTO_INTR_FLAGS_TRK_MSK flag when calling the interrupt attach function, you must pass in a proper ID value (not -1). This ID value, along with the flag setting, allows better error recovery if a process unexpectedly terminates because it lets the kernel know how many times to call InterruptUnmask().

Library:

libc

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

Description:

The InterruptMask() kernel call disables the hardware interrupt specified by intr for the handler specified by id. You can call this function from a thread or from an interrupt handler.

If id isn't -1, the calling thread must be in the process that attached the interrupt. Otherwise the function fails with an error of EPERM.

If id is -1, then before you call this function from a thread:

If you're in an ISR, you must have had proper permissions, so the call will never fail for that reason.

Reenable the interrupt by calling InterruptUnmask().

The kernel automatically enables an interrupt when the first handler attaches to it using InterruptAttach() and disables it when the last handler detaches.

This call is often used when a device presents a level-sensitive interrupt to the system that can't be easily cleared in the interrupt handler. Since the interrupt is level-sensitive, you can't exit the handler with the interrupt line active and unmasked. InterruptMask() lets you mask the interrupt in the handler and schedule a thread to do the real work of communicating with the device to clear the source. Once cleared, the thread should call InterruptUnmask() to reenable this interrupt.

To disable all hardware interrupts, use the InterruptLock() function.

Note: To ensure hardware portability, use InterruptMask() instead of writing code that talks directly to the interrupt controller.

Calls to InterruptMask() are counted; the interrupt isn't unmasked until InterruptUnmask() has been called once for every call to InterruptMask().

Returns:

The current mask level count for success; or -1 if an error occurs (errno is set).

Errors:

EINVAL
The value of intr isn't a supported hardware interrupt.
ESRCH
The id parameter is neither something returned by InterruptAttach(), InterruptAttachArray(), or InterruptAttachEvent(), nor -1.
EPERM
One of the following errors occurred:
  • The function was called from a process other than the one that called one of the InterruptAttach*() functions and obtained id.
  • The caller passed an id of -1 but didn't request I/O privileges by first calling ThreadCtl( _NTO_TCTL_IO_LEVEL, (void*)_NTO_IO_LEVEL_1 ).

Classification:

QNX Neutrino

Safety:  
Cancellation point No
Interrupt handler Yes
Signal handler Yes
Thread Yes