B.7. Kernel PlugIn Structure Reference


	Appendix B. API 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.6.13.1.

B.7.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.

Field	Type	Description
hKernelPlugIn	DWORD	Handle to a Kernel PlugIn
pcDriverName	PCHAR	Name of Kernel PlugIn driver. Should be no longer than 12 characters. Should not include the VXD or SYS extension.
pcDriverPath	PCHAR	This field should be set to NULL. WinDriver will search for the driver in the operating system's drivers/modules directory.
pOpenData	PVOID	Data to pass to the `KP_Open` [B.6.2] callback in the Kernel PlugIn.

B.7.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.46] calls InterruptEnable(), which in turn calls WD_IntEnable(), WD_IntWait() and WD_IntCount(). WDC_IntDisable() [B.3.47] calls InterruptDisable(), which calls WD_IntDisable().

Field	Type	Description
kpCall	WD_KERNEL_ PLUGIN_CALL	Kernel PlugIn message information structure [B.7.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.6.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.7.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.6.4] and KP_IntEnable [B.6.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.18]. InterruptEnable() (which calls WD_IntEnable()) is called from the high-level WDC_IntEnable() function [B.3.46].

Field	Type	Description
hKernelPlugIn	DWORD	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.17], and from the `WDC_xxxDeviceOpen`() functions (PCI [B.3.10] / PCMCIA [B.3.11] / ISA [B.3.12]) when called with the name of a Kernel PlugIn driver [12.4]
dwMessage	DWORD	Message ID to pass to the Kernel PlugIn
pData	PVOID	Pointer to data to pass to the Kernel PlugIn
dwResult	DWORD	Value set by the Kernel PlugIn, to return back to user mode

B.7.4. KP_INIT

This structure is used by the Kernel PlugIn KP_Init function [B.6.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.


`WD_KernelPlugInOpen`() is called from the high-level `WDC_KernelPlugInOpen`() [B.3.17] function. It is also called from the `WDC_xxxDeviceOpen`() functions (PCI [B.3.10] / PCMCIA [B.3.11] / ISA [B.3.12]) 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.

WD_KernelPlugInOpen() is called from the high-level WDC_KernelPlugInOpen() [B.3.17] function.
It is also called from the WDC_xxxDeviceOpen() functions (PCI [B.3.10] / PCMCIA [B.3.11] / ISA [B.3.12]) 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.

Field	Type	Description
dwVerWD	DWORD	The version of the WinDriver Kernel PlugIn library.
cDriverName	CHAR[12]	The device driver name, up to 12 characters.
funcOpen	KP_FUNC_OPEN	Standard `KP_Open` callback function [B.6.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_64	KP_FUNC_OPEN	`KP_Open` callback function [B.6.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.6.2].

B.7.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.6.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.6.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.18], 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.46]. 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.47] — 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 Vista 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 Vista 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.49] 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.

Field	Type	Description
funcClose	KP_FUNC_CLOSE	Name of your `KP_Close` [B.6.3] function in the kernel.
funcCall	KP_FUNC_CALL	Name of your `KP_Call` [B.6.4] function in the kernel.
funcIntEnable	KP_FUNC_INT_ENABLE	Name of your `KP_IntEnable` [B.6.6] function in the kernel.
funcIntDisable	KP_FUNC_INT_DISABLE	Name of your `KP_IntDisable` [B.6.7] function in the kernel.
funcIntAtIrql	KP_FUNC_INT_AT_IRQL	Name of your `KP_IntAtIrql` [B.6.8] function in the kernel.
funcIntAtDpc	KP_FUNC_INT_AT_DPC	Name of your `KP_IntAtDpc` [B.6.9] function in the kernel.
funcIntAtIrqlMSI	KP_FUNC_INT_AT_IRQL_MSI	Name of your `KP_IntAtIrqlMSI` [B.6.10] function in the kernel. Note: MSI/MSI-X is supported on Linux and Windows Vista and higher.
funcIntAtDpcMSI	KP_FUNC_INT_AT_DPC_MSI	Name of your `KP_IntAtDpcMSI` [B.6.11] function in the kernel. Note: MSI/MSI-X is supported on Linux and Windows Vista and higher.
funcEvent	KP_FUNC_EVENT	Name of your `KP_Event` [B.6.5] function in the kernel.


B.6. Kernel PlugIn Kernel-Mode Functions		B.8. User-Mode Utility Functions