RtAttachInterrupt

RtAttachInterrupt allows the user to associate an Interrupt Service Thread (IST) and Interrupt Service Routine (ISR) with a line-based or message-based hardware interrupt. RtAttachInterrupt is only supported in the RTSS environment. It cannot be called from a Windows application linked to RTX.

NOTE: This API call supersedes RtAttachInterruptVector and RtAttachInterruptVectorEx in RTSS. When writing RTSS applications, use RtAttachInterrupt, instead of RtAttachInterruptVector or RtAttachInterruptVectorEx, which may be deprecated in the future. This is applicable only to RTSS process, not Win32 process.

Syntax

HANDLE RtAttachInterrupt(
    PATTACH_INTERRUPT_PARAMETERS Parameters
);

Parameters

Parameters

Pointer to an ATTACH_INTERRUPT_PARAMETERS structure that describes the requested interrupt attachment.

Return Values

An RTX-specific interrupt handle if the function succeeds, a NULL handle if the function fails

This call can fail for these reasons:

An argument is invalid
Failure to connect the interrupt
A device is already using the bus resources requested and either a previous attachment or this attachment specified Shared as FALSE.

Remarks

NOTE: The ISR should be as short-lived as possible. You should not call any non-deterministic functions. Note, however, that you can still call Port I/O.

RtAttachInterrupt allows a user to associate two handling routines with a hardware interrupt on one of the supported buses on the computer.

When the interrupt occurs, the ISR calls the MyInterrupt routine (if present). This optional routine should be used to determine which attachment of a group of shared attachments should handle the interrupt. Since it is called at interrupt level, this routine should complete its work quickly; 1-2 msec is recommended. The routine should restrict itself to the calls in the Port I/O or mapped data transfer API (RtReadPort. . ., RtWritePort. . .). The routine pointed to by MyInterrupt returns one of three values:

It returns PassToNextDevice if its associated device did not generate the interrupt.
It returns CallInterruptThread if its associated device generated the interrupt and the function pointed to by pRoutine is called to handle the interrupt.
It returns Dismiss if its associated device generated the interrupt and no further action is required of the handling thread (presumably because this routine has done all that is necessary).

When called, the handling routines are passed Context as an argument.

IMPORTANT! The handling routine called via pRoutine must not change its thread priority.

As in a typical device driver, the user is responsible for initializing the hardware device, enabling the generation of interrupts, and acknowledging interrupts in the appropriate manner. Interrupt generation on the device can be enabled after a successful call to RtAttachInterrupt. Conversely, the user must disable interrupts before disconnecting the interrupt with RtReleaseInterrupt. The user must disconnect the interrupt before exiting the process. In the interrupt handling routine pRoutine, the user should perform the appropriate steps to acknowledge the device's interrupt. Typically, these operations are performed by writing commands to a device's command/status register, which is either memory-mapped or in the I/O address space of the system.

If MyInterrupt is specified as NULL and Shared is specified as TRUE, the interrupt handling routine (pRoutine) must be prepared to share the specified interrupt vector with other devices. When an interrupt occurs and the handling routine is run, it should check the device in an appropriate manner to determine if the interrupt came from its device. If so, it handles and acknowledges the interrupt in the usual way, and returns TRUE. If its device did not generate the interrupt, the handling routine returns FALSE. The interrupt is passed to the interrupt handling routine in the next attachment.

If the MyInterrupt routine is present, the returning value from pRoutine is ignored.

Message-based interrupts (MSI) with or without masking capability and MSI-X are supported.

For MSI capable devices that do not support masking capability through the PCI MSI capability structure, but implement masking in the devices' registers, the driver should set the mask bit upon entering the ISR and clear the bit upon exiting the IST.

For message-based interrupts that support both MSI and MSI-X, RtAttachInterrupt allows the user to specify that the device should default to MSI.

IMPORTANT! MSI/MSI-X support is limited to one vector per device. For multi-function devices, there is one vector per function, due to vector resource constraints.

NOTE: RtAttachInterrupt is not able to detect if a Network Interface Card (NIC) device has been converted to RTX control. If the card is not under RTX control, unexpected behavior may result.

Requirements

Header	Rtapi.h
Library	Rtx_Rtss.lib

Example:

See the IntelPro1000 topic for information on an example that uses the RtAttachInterrupt function.