 |
Jungo WinDriver
Official Documentation
|
|
Jungo WinDriver
Official Documentation
|
| DWORD DLLCALLCONV WDC_IntEnable | ( | _In_ WDC_DEVICE_HANDLE | hDev, |
| _In_ WD_TRANSFER * | pTransCmds, | ||
| _In_ DWORD | dwNumCmds, | ||
| _In_ DWORD | dwOptions, | ||
| _In_ INT_HANDLER | funcIntHandler, | ||
| _In_ PVOID | pData, | ||
| _In_ BOOL | fUseKP | ||
| ) |
Enables interrupt handling for the device.
On Linux and Windows, when attempting to enable interrupts for a PCI device that supports Extended Message-Signaled Interrupts (MSI-X) or Message-Signaled Interrupts (MSI) (and was installed with a relevant INF file on Windows), the function first tries to enable MSI-X or MSI; if this fails, or if the target OS does not support MSI/MSI-X, the function attempts to enable legacy level-sensitive interrupts (if supported by the device). On Linux, you can use the function's dwOptions parameter to specify the types of PCI interrupts that may be enabled for the device (see the explanation in the parameter description). For other types of hardware (PCI with no MSI/MSI-X support / ISA), the function attempts to enable the legacy interrupt type supported by the device (Level Sensitive / Edge Triggered)
If the caller selects to handle the interrupts in the kernel, using a Kernel PlugIn driver, the Kernel PlugIn KP_IntAtIrql (legacy interrupts) or KP_IntAtIrqlMSI (MSI/MSI-X) function, which runs at high interrupt request level (IRQL), will be invoked immediately when an interrupt is received.
The function can receive transfer commands information, which will be performed by WinDriver at the kernel, at high IRQ level, when an interrupt is received. If a Kernel PlugIn driver is used to handle the interrupts, any transfer commands set by the caller will be executed by WinDriver after the Kernel PlugIn KP_IntAtDpc or KP_IntAtDpcMSI function completes its execution.
When handling level-sensitive interrupts (such as legacy PCI interrupts) from the user mode, without a Kernel PlugIn driver, you must prepare and pass to the function transfer commands for acknowledging the interrupt. When using a Kernel PlugIn driver, the information for acknowledging the interrupts should be implemented in the Kernel PlugIn KP_IntAtIrql function, so the transfer commands in the call to WDC_IntEnable() are not required (although they can still be used).
The function receives a user-mode interrupt handler routine, which will be called by WinDriver after the kernel-mode interrupt processing is completed. If the interrupts are handled using a Kernel PlugIn driver, the return value of the Kernel PlugIn deferred interrupt handler function KP_IntAtDpc (legacy interrupts) or KP_IntAtDpcMSI (MSI/MSI-X) will determine how many times (if at all) the user-mode interrupt handler will be called (provided KP_IntAtDpc or KP_IntAtDpcMSI itself is executed which is determined by the return value of the Kernel PlugIn KP_IntAtIrql or KP_IntAtIrqlMSI function).
| [in] | hDev | Handle to a WDC device, returned by WDC_xxxDeviceOpen() |
| [in] | pTransCmds | 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.
|
| [in] | dwNumCmds | Number of transfer commands in the pTransCmds array |
| [in] | dwOptions | A bit mask of interrupt handling flags can be set to zero for no options, or to a combination of any of the following flags: INTERRUPT_CMD_COPY: If set, WinDriver will copy any data read in the kernel as a result of a read transfer command, and return it to the user within the relevant transfer command structure. The user will be able to access the data from his user-mode interrupt handler routine (funcIntHandler).
|
| [in] | funcIntHandler | A user-mode interrupt handler callback function, which will be executed after an interrupt is received and processed in the kernel. (The prototype of the interrupt handler INT_HANDLER is defined in windrvr_int_thread.h). |
| [in] | pData | Data for the user-mode interrupt handler callback routine (funcIntHandler) |
| [in] | fUseKP | If TRUE The device's Kernel PlugIn driver's KP_IntAtIrql or KP_IntAtIrqlMSI function, which runs at high interrupt request level (IRQL), will be executed immediately when an interrupt is received. The Kernel PlugIn driver to be used for the device is passed to WDC_xxxDeviceOpen() and stored in the WDC device structure. If the caller also passes transfer commands to the function (pTransCmds), these commands will be executed by WinDriver at the kernel, at high IRQ level, after KP_IntAtIrql or KP_IntAtIrqlMSI completes its execution. If the high-IRQL handler returns TRUE, the Kernel PlugIn deferred interrupt processing routine KP_IntAtDpc or KP_IntAtDpcMSI will be invoked. The return value of this function determines how many times (if at all) the user-mode interrupt handler (funcIntHandler) will be executed once the control returns to the user mode. If FALSE When an interrupt is received, any transfer commands set by the user in pTransCmds will be executed by WinDriver at the kernel, at high IRQ level and the user-mode interrupt handler routine (funcIntHandler) will be executed when the control returns to the user mode. |
For more detailed information about interrupt handling, please refer to 10.1. Handling Interrupts
For a sample user-mode interrupt handling code, please refer to 10.1.8. Sample User-Mode WinDriver Interrupt Handling Code
1.9.2