This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

InterruptHookIdle()

Attach an "idle" interrupt handler

Synopsis:

#include <sys/neutrino.h>

int InterruptHookIdle(
    void (*handler)(uint64_t *, struct qtime_entry *),
    unsigned flags );

Arguments:

handler

A pointer to the handler function; see below.

flags

Flags that specify how you want to attach the interrupt handler. 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 InterruptHookIdle() kernel call attaches the specified interrupt handler to the "idle" interrupt, which is called when the system is idle. This is typically used to implement power management features.

The arguments to the handler functions are:

uint64_t*

A pointer to the time, in nanoseconds, when the next timer will expire.

struct qtime_entry *

A pointer to the section of the system page with the time information, including the current time of day.

The simplest idle handler consists of a halt instruction.

Flags

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 take over the same physical interrupt, both handlers are invoked consecutively. When a handler attaches, it's placed in front of any existing handlers for that interrupt and is called first. You can change this behavior by setting the _NTO_INTR_FLAGS_END flag in the flags argument. This adds the handler at the end of any existing handlers.

Processor interrupts are enabled during the execution of the handler. Don't attempt to talk to the interrupt controller chip. The end of interrupt command is issued to the chip by the operating system after processing all handlers at a given level.

The first process to attach to an interrupt unmasks the interrupt. When the last process detaches from an interrupt, the system masks it.

If the thread that attached the interrupt handler terminates without detaching the handler, the kernel does it automatically.

_NTO_INTR_FLAGS_PROCESS

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

_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 values.

Blocking states

This call doesn't block.

Returns:

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

Use the returned value with the InterruptDetach() function to detach this interrupt handler.

Errors:

EAGAIN

All kernel interrupt entries are in use.

EPERM

The process doesn't have superuser capabilities.

Classification:

QNX Neutrino

See also:

InterruptAttach(), InterruptAttachEvent(), InterruptDetach(), InterruptHookTrace()

Writing an Interrupt Handler chapter of the Neutrino Programmer's Guide