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

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

Name	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.17]. InterruptEnable() (which calls WD_IntEnable()) is called from the high-level WDC_IntEnable() function [B.3.43].

Name	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 the WDC_xxxDeviceOpen() functions when opening a device with a Kernel PlugIn driver
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_xxxDeviceOpen() functions (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11]) when these functions are called with a valid Kernel PlugIn driver (set in the pcKPDriverName parameter).

Name	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	The KP_Open() [B.6.2] kernel-mode function that WinDriver should 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_xxxDeviceOpen() functions (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11]) when these functions are called with a valid Kernel PlugIn driver (set in the pcKPDriverName parameter).

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 7 different 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.17], 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.43]. 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.44] - after having enabled interrupts using a Kernel PlugIn driver.

funcIntAtIrql

- High-priority kernel-mode interrupt handler. This callback function is called at high interrupt request level when WinDriver processes the 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.

funcIntAtDpc

- Most of your interrupt handler code should be written in this callback. It is called as a deferred procedure call, if funcIntAtIrql() returns a value greater than zero.

funcEvent

- Called when a Plug-and-Play or power management event occurs, if the user-mode process first called WDC_EventRegister() [B.3.46] 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.

Name	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.
funcEvent	KP_FUNC_EVENT	Name of your KP_Event() [B.6.5] function in the kernel.