ATTACH_INTERRUPT_PARAMETERS
RtAttachInterrupt can be used for:
- line-based interrupts
- message-based single vector interrupts
- message-based multiple vector interrupts
Each interrupt type requires filling in a different portion of the ATTACH_INTERRUPT_PARAMETERS structure. The caller identifies which set of input arguments it is providing (and, hence, which portion of the structure has been filled in) by setting the AttachVersion field of the ATTACH_INTERRUPT_PARAMETERS structure to a particular value, as described in the Members section below.
Syntax
typedef struct _ATTACH_INTERRUPT_PARAMETERS {
ULONG AttachVersion;
union {
//Parameters for line-based interrupt
Struct {
PSECURITY_ATTRIBUTES pThreadAttributes;
ULONG StackSize;
BOOLEAN (RTFCNDCL * pRoutine)(PVOID context);
PVOID Context;
ULONG Priority;
INTERFACE_TYPE InterfaceType;
ULONG BusNumber;
PCI_SLOT_NUMBER SlotNumber;
ULONG BusInterruptLevel;
ULONG BusInterruptVector;
BOOLEAN Shared;
KINTERUPT_MODE InterruptMode;
INTERRUPT_DISPOSITION (RTFCNDCL * MyInterrupt)(PVOID context);
KAFFINITY ProcessorEnableMask;
} LineBased; //Parameters for message-based single vector interrupt
Struct {
PSECURITY_ATTRIBUTES pThreadAttributes;
ULONG StackSize;
BOOLEAN (RTFCNDCL * pRoutine)(PVOID context);
PVOID Context;
ULONG Priority;
ULONG BusNumber;
PCI_SLOT_NUMBER SlotNumber;
INTERRUPT_DISPOSITION (RTFCNDCL * MyInterrupt)(PVOID context);
KAFFINITY ProcessorEnableMask;
} MessageBased; //Parameters for message-based multiple vector interrupt
Struct {
PSECURITY_ATTRIBUTES pThreadAttributes;
ULONG StackSize;
BOOLEAN (RTFCNDCL * pRoutine)(PVOID context, ULONG MessageId);
PVOID Context;
ULONG BusNumber;
PCI_SLOT_NUMBER SlotNumber;
INTERRUPT_DISPOSITION (RTFCNDCL * MyInterrupt)(PVOID context, ULONG MessageId);
VOID (RTFCNDCL * EnableInterruptFromSpecifiedMessage)(PVOID context, ULONG MessageId, BOOLEAN bEnable);
PINTERRUPT_MESSAGE_INFO InterruptMessageTable;
} MessageBasedMvector;}; } ATTACH_INTERRUPT_PARAMETERS, *PATTACH_INTERRUPT_PARAMETERS;
AttachVersion
Specifies the operation to be performed by RtAttachInterrupt:
| AttachVersion Value | RtAttachInterrupt Operation |
|---|---|
|
ATTACH_LINE_BASED |
Associates an IST and ISR with the device’s line-based interrupts. Use the LineBased member to provide the additional parameters for the operation. |
|
ATTACH_MESSAGE_BASED |
Associates an IST and ISR with the device’s message-based single vector interrupts. Use the MessageBased member to provide the additional parameters for the operation. This value can be used by devices that support:
If the device supports both MSI and MSI-X, use of this value will adhere to Windows behavior that the device should default to MSI-X. |
|
ATTACH_MESSAGE_BASED_PREFER_MSI |
Associates an IST and ISR with the device’s message-based single vector interrupts. Use the MessageBased member to provide the additional parameters for the operation. This value can be used by devices that support:
If the device supports both MSI and MSI-X, use of this value allows you to specify that the device should default to MSI. NOTE: ATTACH_MESSAGE_BASED_PREFER_MSI is not recommended unless an MSI/MSI-X capable device is found not to work correctly when using MSI-X. MSI-X is preferred because it allows for vector masking. |
| ATTACH_MESSAGE_BASED_MULTI_VECTOR |
Associates an IST and ISR with each vector of the device’s message-based multiple vectors interrupts. Use the MessageBasedMvector member to provide the additional parameters for the operation. This value can be used by devices that support:
If the device supports both MSI and MSI-X, use of this value will adhere to Windows behavior that the device should default to MSI-X. Multiple calls of RtAttachInterrupt with this value for the same device are allowed. |
LineBased
Specifies the additional parameters of the operation to be performed by RtAttachInterrupt when AttachVersion has a value of ATTACH_LINE_BASED.
pThreadAttributes (Ignored by RTSS)
A security attributes structure used when the handler thread is created.
StackSize
The number of bytes to allocate for the handler thread's stack. The stack size defaults to the default thread size. See CreateThread.
pRoutine
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 pRoutine and MyInterrupt, cast as a PVOID.
Priority
The thread priority for the handler routine. pRoutine executes in thread context so it can be interrupted by higher priority threads.
InterfaceType
The type of bus interface on which the hardware is located. It can be one of the following types: Isa, or PCIBus. The upper boundary on the bus types supported is always MaximumInterfaceType which is defined in Rtapi.h.
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.
SlotNumber
The logical slot number. When PCIBus is specified, this is a PCI_SLOT_NUMBER type value. Otherwise, this value is ignored.
BusInterruptLevel
A bus-specific interrupt level associated with the device.
BusInterruptVector
A bus-specific interrupt vector associated with the device.
Shared
Specifies whether the caller is prepared to share the interrupt vector. TRUE when sharing is supported, otherwise FALSE.
InterruptMode
Specifies whether the device interrupt is LevelSensitive or Latched.
MyInterrupt
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.
ProcessorEnableMask
Specifies the KAFFINITY mask that represents the set of RTSS processors on which the device’s interrupts can occur. See Specifying a Processor Affinity Bitmask for more details. Once an IST has started, it cannot be moved to another processor.
MessageBased
Specifies the additional parameters of the operation to be performed by RtAttachInterrupt when AttachVersion has a value of ATTACH_MESSAGE_BASED or ATTACH_MESSAGE_BASED_PREFER_MSI.
pThreadAttributes
Ignored.
StackSize
The number of bytes to allocate for the handler thread's stack. The stack size defaults to the default thread size. See CreateThread.
pRoutine
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 pRoutine and MyInterrupt, cast as a PVOID.
Priority
The thread priority for the handler routine. pRoutine executes in thread context so it can be interrupted by higher priority threads.
BusNumber
The bus the device is on in a multiple bus environment, with counting starting at zero.
SlotNumber
The logical slot number. This is a PCI_SLOT_NUMBER type value.
MyInterrupt
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.
ProcessorEnableMask
Specifies the KAFFINITY mask that represents the set of RTSS processors on which the device’s interrupts can occur. See Specifying a Processor Affinity Bitmask for more details. Once an IST has started, it cannot be moved to another processor.
MessageBasedMvector
Specifies the additional parameters of the operation to be performed by RtAttachInterrupt when AttachVersion has a value of ATTACH_MESSAGE_BASED_MULTI_VECTOR.
pThreadAttributes
Ignored.
StackSize
The number of bytes to allocate for the handler thread's stack. The stack size defaults to the default thread size. See CreateThread.
pRoutine
A pointer to the handler routine to be run by each Interrupt Service Thread (IST) associated with each vector. The routine takes two arguments as input, PVOID Context and ULONG MessageId, and returns BOOLEAN. MessageId is the MSI-X vector, i.e., the index into the MSI-X table.
NOTE: With MessageId as input, pRoutine knows which event occurs on the device. There is no need to access device registers to identify the interrupt cause.
Context
The argument to the handler routines pRoutine and MyInterrupt, and interrupt enable/disable routine EnableInterruptFromSpecifiedMessage, cast as a PVOID.
BusNumber
The bus the device is on in a multiple bus environment, with counting starting at zero.
SlotNumber
The logical slot number. This is a PCI_SLOT_NUMBER type value.
MyInterrupt
A pointer to a routine to be run by each Interrupt Service Routine (ISR) associated with each vector, or NULL to specify no routine. The routine takes two arguments as input, PVOID Context and ULONG MessageId, and returns INTERRUPT_DISPOSITION. MessageId is the MSI-X vector, i.e., the index into the MSI-X table.
NOTE: With MessageId as input, MyInterrupt knows which event occurs on the device. There is no need to access device registers to identify the interrupt cause.
EnableInterruptFromSpecifiedMessage
A pointer to a routine to be run by the RTSS thread scheduler or NULL to specify no routine. The routine takes three arguments as input, PVOID Context, ULONG MessageId, and BOOLEAN bEnable. The routine does not return a value. MessageId is the MSI-X vector, i.e., the index into the MSI-X table. If the value of bEnable is TRUE, the routine needs to enable interrupts from the specified vector (MessageId). If the value of bEnable is FALSE, the routine needs to disable interrupts from the specified vector. The interrupts from the specified vector can be enabled or disabled by changing the corresponding mask bit on the device.
InterruptMessageTable
A pointer to a user-allocated INTERRUPT_MESSAGE_INFO structure.
Requirements
| Minimum Supported Version |
RTX64 3.3 for Multiple Vector Interrupts RTX64 2013 |
| Header | Rtapi.h |
See Also:
