B.9. Kernel PlugIn Structure Reference

This section contains detailed information about the different Kernel PlugIn related structures. WD_XXX structures are used in user-mode functions and KP_XXX structures are used in kernel-mode functions.

The Kernel PlugIn synchronization types are documented in Section B.8.13.1.

B.9.1. WD_KERNEL_PLUGIN

Defines a Kernel PlugIn open command.

This structure is used by the low-level WD_KernelPlugInOpen() and WD_KernelPlugInClose() functions — see the WinDriver PCI Low-Level API Reference.

FieldTypeDescription
hKernelPlugInDWORDHandle to a Kernel PlugIn
pcDriverNamePCHAR Name of Kernel PlugIn driver.
The name should be no longer than 12 characters and should not include the *.sys extension.
pcDriverPathPCHAR This field should be set to NULL. WinDriver will search for the driver in the operating system's drivers/modules directory.
pOpenDataPVOID Data to pass to the KP_Open [B.8.2] callback in the Kernel PlugIn.

B.9.2. WD_INTERRUPT

Interrupt information structure.

This structure is used by the low-level InterruptEnable(), InterruptDisable(), WD_IntEnable(), WD_IntDisable(), WD_IntWait() and WD_IntCount() functions.
WDC_IntEnable() [B.3.41] calls InterruptEnable(), which in turn calls WD_IntEnable(), WD_IntWait() and WD_IntCount(). WDC_IntDisable() [B.3.42] calls InterruptDisable(), which calls WD_IntDisable().

FieldTypeDescription
kpCallWD_KERNEL_ PLUGIN_CALL Kernel PlugIn message information structure [B.9.3]. This structure contains the handle to the Kernel PlugIn and additional information that should be passed to the kernel-mode interrupt handler. If the Kernel PlugIn handle is zero, the interrupt is installed without a Kernel PlugIn interrupt handler. If a valid Kernel PlugIn handle is set, this structure will passed as a parameter to the KP_IntEnable [B.8.6] Kernel PlugIn callback function.

For information about the other members of WD_INTERRUPT, see the description of InterruptEnable() in the WinDriver PCI Low-Level API Reference.

B.9.3. WD_KERNEL_PLUGIN_CALL

Kernel PlugIn message information structure. This structure contains information that will be passed between a user-mode process and the Kernel PlugIn. The structure is used when passing messages to the Kernel PlugIn or when installing a Kernel PlugIn interrupt.

This structure is passed as a parameter to the Kernel PlugIn KP_Call [B.8.4] and KP_IntEnable [B.8.6] callback functions and is used by the low-level WD_KernelPlugInCall(), InterruptEnable() and WD_IntEnable() functions. WD_KernelPlugInCall() is called from the high-level WDC_CallKerPlug() function [B.3.16]. InterruptEnable() (which calls WD_IntEnable()) is called from the high-level WDC_IntEnable() function [B.3.41].

FieldTypeDescription
hKernelPlugInDWORD Handle to a Kernel PlugIn, returned by WD_KernelPlugInOpen() (see the WinDriver PCI Low-Level API Reference) — which is called from WDC_KernelPlugInOpen() [B.3.15], and from the WDC_xxxDeviceOpen() functions (PCI [B.3.10] / ISA [B.3.11]) when called with the name of a Kernel PlugIn driver [12.4]
dwMessageDWORDMessage ID to pass to the Kernel PlugIn
pDataPVOIDPointer to data to pass to the Kernel PlugIn
dwResultDWORDValue set by the Kernel PlugIn, to return back to user mode

B.9.4. KP_INIT

This structure is used by the Kernel PlugIn KP_Init function [B.8.1]. Its primary use is to notify WinDriver of the given driver's name and of which kernel-mode function to call when WD_KernelPlugInOpen() (see WinDriver PCI Low-Level API Reference) is called from the user mode.

[Note]
WD_KernelPlugInOpen() is called from the high-level WDC_KernelPlugInOpen() [B.3.15] function.
It is also called from the WDC_xxxDeviceOpen() functions (PCI [B.3.10] / ISA [B.3.11]) when these functions are called with a valid Kernel PlugIn driver (set in the pcKPDriverName parameter). However, to ensure the correct execution of your code in all scenarios — including execution of a 32-bit application with a 64-bit Kernel PlugIn driver — do not use the device-open functions to open a handle to the Kernel PlugIn driver.
FieldTypeDescription
dwVerWDDWORDThe version of the WinDriver Kernel PlugIn library.
cDriverNameCHAR[12]The device driver name, up to 12 characters.
funcOpenKP_FUNC_OPEN Standard KP_Open callback function [B.8.2], which will be called when a user-mode application opens a handle to a Kernel PlugIn driver [12.4], except when opening a handle to a 64-bit driver from a 32-bit application (in which case funcOpen_32_64 will be used).
funcOpen_32_64KP_FUNC_OPEN KP_Open callback function [B.8.2] that will be called when a 32-bit application opens a handle to a 64-bit Kernel PlugIn driver [12.4], except for a 32-bit application request to open a handle to a 64-bit driver (when funcOpen_32_64 will be used) [B.8.2].

B.9.5. KP_OPEN_CALL

This is the structure through which the Kernel PlugIn defines the names of its callback functions (other than KP_Open). It is used from the KP_Open [B.8.2] Kernel PlugIn function, which sets the callbacks in the structure.

A Kernel PlugIn may implement the following callback functions (other than KP_Open [B.8.2]):

  • funcClose — Called when the user-mode process is done with this instance of the driver.
  • funcCall — Called when the user mode process calls WDC_CallKerPlug() [B.3.16], or the low-level WD_KernelPlugInCall() function (see the WinDriver PCI Low-Level API Reference), which is called from WDC_CallKerPlug().
    This is a general-purpose function. You can use it to implement any functionality that should run in kernel mode (except the interrupt handler, which is a special case). The funcCall callback determines which function to execute according to the message passed to it from the user mode.
  • funcIntEnable — Called when the user-mode process calls WD_IntEnable() with a Kernel PlugIn handle. WD_IntEnable() is called from InterruptEnable() (see WinDriver PCI Low-Level API Reference), which is called from the high-level WDC_IntEnable() function [B.3.41]. When calling WDC_IntEnable() with fUseKP = TRUE, the function calls InterruptEnable() with a Kernel PlugIn handle.
    This callback function should perform any initialization required when enabling an interrupt.
  • funcIntDisable — Interrupt cleanup function, which is called when the user-mode process calls WD_IntDisable() — called from InterruptDisable() (see WinDriver PCI Low-Level API Reference), which is called from WDC_IntDisable() [B.3.42] — after having enabled interrupts using a Kernel PlugIn driver.
  • funcIntAtIrql — High-priority kernel-mode legacy interrupt handler. This callback function is called at high interrupt request level when WinDriver processes a legacy interrupt that is assigned to this Kernel PlugIn. If this function returns a value greater than zero, the funcIntAtDpc() callback is called as a Deferred Procedure Call (DPC).
  • funcIntAtDpc — Most of your legacy interrupt handler code should be written in this callback. It is called as a Deferred Procedure Call (DPC) if funcIntAtIrql() returned a value greater than zero.
  • funcIntAtIrqlMSI — High-priority kernel-mode PCI Message-Signaled Interrupts (MSI) and Extended Message-Signaled Interrupts (MSI-X) handler. This callback function is called at high interrupt request level when WinDriver processes an MSI/MSI-X that is assigned to this Kernel PlugIn. If this function returns a value greater than zero, the funcIntAtDpcMSI() callback is called as a Deferred Procedure Call (DPC).
    Note: MSI/MSI-X is supported on Linux and Windows 7 and higher.
  • funcIntAtDpcMSI — Most of your PCI MSI/MSI-X handler code should be written in this callback. It is called as a Deferred Procedure Call (DPC) if funcIntAtIrqlMSI() returned a value greater than zero.
    Note: MSI/MSI-X is supported on Linux and Windows 7 and higher.
  • funcEvent — Called when a Plug-and-Play or power management event occurs, if the user-mode process first called WDC_EventRegister() [B.3.45] with fUseKP = TRUE (or if the low-level EventRegister() function was called with a Kernel PlugIn handle — see WinDriver PCI Low-Level API Reference). This callback function should implement the desired kernel handling for Plug-and-Play and power management events.

FieldTypeDescription
funcCloseKP_FUNC_CLOSEName of your KP_Close [B.8.3] function in the kernel.
funcCallKP_FUNC_CALLName of your KP_Call [B.8.4] function in the kernel.
funcIntEnableKP_FUNC_INT_ENABLEName of your KP_IntEnable [B.8.6] function in the kernel.
funcIntDisableKP_FUNC_INT_DISABLE Name of your KP_IntDisable [B.8.7] function in the kernel.
funcIntAtIrqlKP_FUNC_INT_AT_IRQLName of your KP_IntAtIrql [B.8.8] function in the kernel.
funcIntAtDpcKP_FUNC_INT_AT_DPC Name of your KP_IntAtDpc [B.8.9] function in the kernel.
funcIntAtIrqlMSIKP_FUNC_INT_AT_IRQL_MSI Name of your KP_IntAtIrqlMSI [B.8.10] function in the kernel.
Note: MSI/MSI-X is supported on Linux and Windows 7 and higher.
funcIntAtDpcMSIKP_FUNC_INT_AT_DPC_MSI Name of your KP_IntAtDpcMSI [B.8.11] function in the kernel.
Note: MSI/MSI-X is supported on Linux and Windows 7 and higher.
funcEventKP_FUNC_EVENTName of your KP_Event [B.8.5] function in the kernel.