RtAttachInterrupt

RtAttachInterrupt allows the user to associate an Interrupt Service Thread (IST) and Interrupt Service Routine (ISR) with a line-based or message-based single vector interrupt, or with each vector in a message-based multiple vector interrupt.

NOTE: RtAttachInterrupt is only supported in the RTSS environment. It cannot be called from a Windows application linked to RTX64.

Syntax

HANDLE RtAttachInterrupt(
    PATTACH_INTERRUPT_PARAMETERS Parameters
);

Parameters

Parameters

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

Return Value

An RTX64-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.
Not enough free vectors on target processors in the case of multiple vector attachment
The requesting MessageId is invalid or already used by a previous attachment in the case of multiple vector attachment

When AttachVersion is ATTACH_MESSAGE_BASED_MULTI_VECTOR, RtAttachInterrupt will return two custom error codes which contain MessageId as follows:

MACRO to get failed MessageId for not enough free vectors. When RtAttachInterrupt returns NULL, you need to call GetLastError. Based on the returned LastError, if NOT_ENOUGH_FREE_VECTOR(LastError) macro is TRUE, use the GET_FAILED_MESSAGE_ID(LastError) macro to get the failed MessageId.
MACRO to get invalid MessageId for invalid message parameters. When RtAttachInterrupt returns NULL, you need to call GetLastError. Based on the returned LastError, if INVALID_MESSAGE_PARAMETER(LastError) macro is TRUE, use the GET_INVALID_MESSAGE_ID(LastError) macro to get the invalid MessageId.

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 single vector interrupt or with each vector in a multiple vector 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 micro-seconds 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. For line-based interrupts or message based single vector interrupts, 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. For message-based multiple vector interrupts, interrupt (per vector) enabling or disabling is internally controlled by the thread scheduler. Therefore, the user should not enable or disable interrupt generation on the device between the calls of RtAttachInterrupt and 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.

For message-based multiple vector interrupts, multiple calls of RtAttachInterrupt (with AttachVersion as ATTACH_MESSAGE_BASED_MULTI_VECTOR) and RtReleaseInterrupt with a different set of MSI-X messages for the same device function are allowed.

NOTE: For the same device or the same function in multi-function devices, the following are not allowed:

Mixed calls of RtAttachInterrupt with different AttachVersion values

Multiple calls of RtAttachInterrupt with an AttachVersion value other than ATTACH_MESSAGE_BASED_MULTI_VECTOR

IMPORTANT! MSI support is limited to one vector per device. For multi-function devices, there is one vector per function, due to vector resource constraints. Therefore, MSI support is limited to single vector attachment (AttachVersion as ATTACH_MESSAGE_BASED). MSI-X support covers both single vector attachment (AttachVersion as ATTACH_MESSAGE_BASED) and multiple vector attachment (AttachVersion as ATTACH_MESSAGE_BASED_MULTI_VECTOR).

NOTE: RtAttachInterrupt is not able to detect if a device has been converted to RTX64 control. If a device is not under RTX64 control, unexpected behavior may result.

Requirements

Minimum Supported Version

RTX64 3.3 for Multiple Vector Interrupts

RTX64 2013 for line-based interrupts and message-based single vector interrupts

Header

Rtapi.h

RtApi.lib

Rtx_Rtss.lib

ExampleS:

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

See the MultiVectorI350 topic for an example of using Message Signaled Interrupts (MSI-X) with multiple vectors attachment on Intel Ethernet Controller I350 with Dual or Quad ports.