Next: 3.3 WD_IntWait() Up: 3. Low Level WD_xxx Previous: 3.1 WinDriver Low-Level Interrupt Contents

3.2 WD_IntEnable()

PURPOSE

$\bullet$ Registers an interrupt service routine (ISR) to be called upon interrupt.

PROTOTYPE

DWORD WD_IntEnable(
   HANDLE hWD,
   WD_INTERRUPT *pInterrupt);

PARAMETERS

Name Type Input/Output

$\bullet$ hWD HANDLE Input

$\bullet$ pInterrupt WD_INTERRUPT*

$\gg$ hInterrupt HANDLE Input

$\gg$ dwOptions DWORD Input

$\gg$ Cmd WD_TRANSFER* Input

$\gg$ dwCmds DWORD Input

$\gg$ kpCall WD_KERNEL_PLUGIN_CALL

$\diamond$ hKernelPlugIn HANDLE Input

$\diamond$ dwMessage DWORD N/A

$\diamond$ pData PVOID N/A

$\diamond$ dwResult DWORD N/A

$\gg$ fEnableOk DWORD Output

$\gg$ dwCounter DWORD N/A

$\gg$ dwLost DWORD N/A

$\gg$ fStopped DWORD N/A

$\gg$ dwLastMessage DWORD N/A

$\gg$ dwEnabledIntType DWORD Output

Name	Type	Input/Output
$\bullet$ hWD	HANDLE	Input
$\bullet$ pInterrupt	WD_INTERRUPT*
$\gg$ hInterrupt	HANDLE	Input
$\gg$ dwOptions	DWORD	Input
$\gg$ Cmd	WD_TRANSFER*	Input
$\gg$ dwCmds	DWORD	Input
$\gg$ kpCall	WD_KERNEL_PLUGIN_CALL
$\diamond$ hKernelPlugIn	HANDLE	Input
$\diamond$ dwMessage	DWORD	N/A
$\diamond$ pData	PVOID	N/A
$\diamond$ dwResult	DWORD	N/A
$\gg$ fEnableOk	DWORD	Output
$\gg$ dwCounter	DWORD	N/A
$\gg$ dwLost	DWORD	N/A
$\gg$ fStopped	DWORD	N/A
$\gg$ dwLastMessage	DWORD	N/A
$\gg$ dwEnabledIntType	DWORD	Output

DESCRIPTION

Name Description

HWD Handle to WinDriver's kernel-mode driver as received from WD_Open() [5.2]

pInterrupt Pointer to an interrupt information structure:

$\bullet$ hInterrupt Interrupt handle. The handle is returned by WD_CardRegister() [2.8] in pCardReg->Card.Item[i].I.Int.hInterrupt.

$\bullet$ dwOptions A bit mask flag. May be 0 for no option, or:
$\bullet$ INTERRUPT_CMD_COPY: if set, WinDriver will copy the data received from the read commands that were used to acknowledge the interrupt in the kernel, back to the user mode. The data will be available when WD_IntWait() [3.3] returns.

$\bullet$ Cmd An array of transfer commands information structures that define the operations to be performed at the kernel level upon the detection of an interrupt, or NULL if no transfer commands are required.

NOTE: When handling level sensitive interrupts (such as PCI interrupts) in the user mode (without a Kernel PlugIn driver), you must use this array to define the hardware-specific commands for acknowledging the interrupts in the kernel, immediately when they are received.

The commands in the array can be either of the following:

$\bullet$ A read/write transfer command that conforms to the following format: <dir><p>_[S]<size> - see the description of pTrans->cmdTrans in section 2.11.

$\bullet$ CMD_MASK: an interrupt mask command for determining the source of the interrupt: When this command is set, upon the arrival of an interrupt in the kernel WinDriver masks the value of the previous read command in the WD_TRANSFER commands array with the mask that is set in the relevant Data field union member of the mask transfer command. For example, for a Cmd WD_TRANSFER array, if Cmd[i-1].cmdTrans is RM_BYTE, WinDriver performs the following mask: Cmd[i-1].Data.Byte & Cmd[i].Data.Byte. If the mask is successful, the driver claims ownership of the interrupt and when the control is returned to the user mode, the interrupt handler routine that was passed to the interrupt enable function is invoked; otherwise, the driver rejects ownership of the interrupt, the interrupt handler routine is not invoked and the subsequent transfer commands in the array are not executed.
(Acceptance and rejection of the interrupt is relevant only when handling legacy interrupts; since MSI/MSI-X interrupts are not shared, WinDriver will always accept control of such interrupts.)
NOTE: A CMD_MASK command must be preceded by a read transfer command (RM_XXX / RP_XXX).

$\bullet$ dwCmds Number of transfer commands in Cmd array

$\bullet$ kpCall Pointer to a Kernel PlugIn message information structure:

$\gg$ hKernelPlugIn Handle to Kernel PlugIn returned from WD_KernelPlugInOpen() [6.1]

$\bullet$ fEnableOk Set by the function to TRUE if WD_IntEnable() [3.2] succeeds

$\bullet$ dwEnabledIntType Updated by the function to indicate the type of interrupt enabled for the device. Can be set to any of the following values:
$\bullet$ INTERRUPT_MESSAGE_X: Extended Message-Signaled Interrups (MSI-X). $^{\scriptsize {*}}$
$\bullet$ INTERRUPT_MESSAGE: Message-Signaled Interrups (MSI). $^{\scriptsize {*}}$
$\bullet$ INTERRUPT_LEVEL_SENSITIVE: legacy level sensitive interrupts.
$\bullet$ 0: Default interrupt type - legacy edge trigerred interrupts.

NOTE:
$^{\scriptsize {*}}$ The Windows APIs do not distinguish between MSI and MSI-X; therefore, on this OS the WinDriver functions set the INTERRUPT_MESSAGE flag for both MSI and MSI-X.
$^{\scriptsize {**}}$ This field normally relevant only in the case of PCI devices that support more than one type of interrupt.

Name	Description
HWD	Handle to WinDriver's kernel-mode driver as received from `WD_Open()` [5.2]
pInterrupt	Pointer to an interrupt information structure:
$\bullet$ hInterrupt	Interrupt handle. The handle is returned by `WD_CardRegister()` [2.8] in `pCardReg->Card.Item[i].I.Int.hInterrupt`.
$\bullet$ dwOptions	A bit mask flag. May be 0 for no option, or: $\bullet$ INTERRUPT_CMD_COPY: if set, WinDriver will copy the data received from the read commands that were used to acknowledge the interrupt in the kernel, back to the user mode. The data will be available when `WD_IntWait()` [3.3] returns.
$\bullet$ Cmd	An array of transfer commands information structures that define the operations to be performed at the kernel level upon the detection of an interrupt, or `NULL` if no transfer commands are required. NOTE: When handling level sensitive interrupts (such as PCI interrupts) in the user mode (without a Kernel PlugIn driver), you must use this array to define the hardware-specific commands for acknowledging the interrupts in the kernel, immediately when they are received. The commands in the array can be either of the following: $\bullet$ A read/write transfer command that conforms to the following format: <dir><p>_[S]<size> - see the description of `pTrans->cmdTrans` in section 2.11. $\bullet$ CMD_MASK: an interrupt mask command for determining the source of the interrupt: When this command is set, upon the arrival of an interrupt in the kernel WinDriver masks the value of the previous read command in the `WD_TRANSFER` commands array with the mask that is set in the relevant `Data` field union member of the mask transfer command. For example, for a `Cmd WD_TRANSFER` array, if `Cmd[i-1].cmdTrans` is `RM_BYTE`, WinDriver performs the following mask: `Cmd[i-1].Data.Byte & Cmd[i].Data.Byte`. If the mask is successful, the driver claims ownership of the interrupt and when the control is returned to the user mode, the interrupt handler routine that was passed to the interrupt enable function is invoked; otherwise, the driver rejects ownership of the interrupt, the interrupt handler routine is not invoked and the subsequent transfer commands in the array are not executed. (Acceptance and rejection of the interrupt is relevant only when handling legacy interrupts; since MSI/MSI-X interrupts are not shared, WinDriver will always accept control of such interrupts.) NOTE: A `CMD_MASK` command must be preceded by a read transfer command (`RM_XXX / RP_XXX`).
$\bullet$ dwCmds	Number of transfer commands in Cmd array
$\bullet$ kpCall	Pointer to a Kernel PlugIn message information structure:
$\gg$ hKernelPlugIn	Handle to Kernel PlugIn returned from `WD_KernelPlugInOpen()` [6.1]
$\bullet$ fEnableOk	Set by the function to `TRUE` if `WD_IntEnable()` [3.2] succeeds
$\bullet$ dwEnabledIntType	Updated by the function to indicate the type of interrupt enabled for the device. Can be set to any of the following values: $\bullet$ INTERRUPT_MESSAGE_X: Extended Message-Signaled Interrups (MSI-X). $^{\scriptsize {}}$ $\bullet$ INTERRUPT_MESSAGE: Message-Signaled Interrups (MSI). $^{\scriptsize {}}$ $\bullet$ INTERRUPT_LEVEL_SENSITIVE: legacy level sensitive interrupts. $\bullet$ 0: Default interrupt type - legacy edge trigerred interrupts. NOTE: $^{\scriptsize {}}$ The Windows* APIs do not distinguish between MSI and MSI-X; therefore, on this OS the WinDriver functions set the INTERRUPT_MESSAGE flag for both MSI and MSI-X. $^{\scriptsize {**}}$ This field normally relevant only in the case of PCI devices that support more than one type of interrupt.

RETURN VALUE

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [A].

REMARKS

For more information regarding interrupt handling please refer to the ''ISA/EISA and PCI Interrupts'' section in the WinDriver PCI Manual.
kpCall is relevant for Kernel PlugIn implementation.

EXAMPLE

WD_INTERRUPT Intrp;
WD_CARD_REGISTER cardReg;

BZERO(cardReg);
cardReg.Card.dwItems = 1;
cardReg.Card.Item[0].item = ITEM_INTERRUPT;
cardReg.Card.Item[0].fNotSharable = TRUE;
cardReg.Card.Item[0].I.Int.dwInterrupt = 10; /* IRQ 10 */
 /* INTERRUPT_LEVEL_SENSITIVE - set to level sensitive
    interrupts, otherwise should be 0.
    ISA cards are usually edge triggered while PCI cards
    are usually level sensitive. */
cardReg.Card.Item[0].I.Int.dwOptions =
    INTERRUPT_LEVEL_SENSITIVE;
cardReg.fCheckLockOnly = FALSE;
WD_CardRegister(hWD, &cardReg);
if (cardReg.hCard == 0)
    printf("Could not lock device\n");
else
{
    BZERO(Intrp);
    Intrp.hInterrupt =
        cardReg.Card.Item[0].I.Int.hInterrupt;
    Intrp.Cmd = NULL;
    Intrp.dwCmds = 0;
    Intrp.dwOptions = 0;
    WD_IntEnable(hWD, &Intrp);
}
if (!Intrp.fEnableOk)
{
    printf("Failed enabling interrupt\n");
}

For another example please refer to WinDriver/samples/pci_diag/pci_lib.c.

Next: 3.3 WD_IntWait() Up: 3. Low Level WD_xxx Previous: 3.1 WinDriver Low-Level Interrupt Contents