RtAttachInterruptVectorEx

NOTE: This API call has been superseded by RtAttachInterrupt in RTSS. When writing RTSS applications, use RtAttachInterrupt, instead of RtAttachInterruptVectorEx, which may be deprecated in the future.

RtAttachInterruptVectorEx allows the user to associate an IST and ISR with a shared or non-shared hardware interrupt.

Syntax

HANDLE RtAttachInterruptVectorEx(
    PSECURITY_ATTRIBUTES pThreadAttributes,
    ULONG StackSize,
    BOOLEAN (RTFCNDCL *pRoutineIST)(PVOID Context),
    PVOID Context,
    ULONG Priority,
    INTERFACE_TYPE InterfaceType,
    ULONG BusNumber,
    ULONG BusInterruptLevel,
    ULONG BusInterruptVector,
    BOOLEAN ShareVector,
    KINTERRUPT_MODE InterruptMode,
    INTERRUPT_DISPOSITION (RTFCNDCL *pRoutineISR)(PVOID  Context)
);

Parameters

pThreadAttributes

Ignored. A security attributes structure used when the handler thread is created. See CreateThread.

StackSize

The number of bytes to allocate for the handler thread's stack. See CreateThread.

pRoutineIST

A pointer to the handler routine to be run by the Interrupt Service Thread (IST). The routine takes a single PVOID Context argument and returns BOOLEAN.

Context

The argument to the handler routines pRoutineIST and pRoutineISR, cast as a PVOID.

Priority

The thread priority for the handler routine. Executing equal and higher priority threads disable interrupts from the device; executing lower priority threads enable interrupts from the device.

InterfaceType

The type of bus interface on which the hardware is located. It can be one of the following types: Isa bus or PCIBus bus. The upper boundary on the bus types supported is always MaximumInterfaceType.

BusNumber

The bus the device is on in a multiple bus environment, with counting starting at zero. Typically, a machine has only one or two of a particular bus type, so this value is either 0 or 1. Note that this value applies to each bus type, so for a system with one ISA bus and one PCI bus, for example, each would have a BusNumber of 0.

BusInterruptLevel

A bus-specific interrupt level associated with the device.

BusInterruptVector

A bus-specific interrupt vector associated with the device.

ShareVector

Specifies whether the caller is prepared to share the interrupt vector. TRUE indicates that the caller is prepared to share. FALSE indicates that the caller is not prepared to share.

InterruptMode

Specifies whether the device interrupt is LevelSensitive or Latched.

pRoutineISR

A pointer to a routine to be run by the Interrupt Service Routine (ISR) or NULL to specify no routine. The routine takes a single PVOID Context argument and returns INTERRUPT_DISPOSITION.

Return Values

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

The function can fail for these reasons:

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

Remarks

RtAttachInterruptVectorEx allows a user to associate two handling routines with a hardware interrupt on one of the supported buses on the computer. It uses the DDK HAL routines for getting the system-wide interrupt vector based on the bus-specific interrupt level and vector. If successful, it creates a handling thread in the user's application.

RTSS threads can share a given interrupt vector, and Win32 threads can do the same. However, an RTSS thread and a Win32 thread cannot share the same interrupt. To determine what interrupts Windows is using, use Windows Diagnostics or the Windows Device Manager. You should be aware that sharing of interrupts increases the interrupt latency for the lower priority interrupt service threads; this occurs because the higher priority interrupt service thread must run and determine that a shared interrupt is to be passed along to another thread. For situation where very low interrupt latency is necessary, the extra overhead of interrupt sharing could cause problems. Devices that require very short interrupt latency should be assigned to unique interrupt lines. If your device has hard real-time interrupt latency requirements, you probably do not want it to share an interrupt line with another device.

When the interrupt occurs, the ISR calls the pRoutineISR 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 pRoutineISR 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 pRoutineIST 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 pRoutineISR 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 RtAttachInterruptVectorEx. Conversely, the user must disable interrupts before disconnecting the interrupt with RtReleaseInterruptVector, and the user must disconnect the interrupt before exiting. In the interrupt handling routine, 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 pRoutineISR is specified as NULL and ShareVector is specified as TRUE, the interrupt handling routine (pRoutineIST) 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 pRoutineISR routine is present, the returning value from pRoutineIST is ignored.

On uniprocessor systems, level-triggered interrupts cannot be used by Win32 processes because the interrupt will be reasserted when RTSS tries to return to Windows to allow the Win32 service routine to run. For level-triggered interrupts to operate correctly, the interrupt service routine must clear the interrupt condition before it unmasks the interrupt line.

Requirements

Header	Rtapi.h
Library	rtapi_w32.lib (Windows), Rtx_Rtss.lib (RTSS)