11.6 How Does Kernel PlugIn Work?

The following sections take you through the development cycle of a Kernel PlugIn driver.

It is recommended that you first write and debug your entire driver code in user mode, and then if you encounter performance problems or require greater flexibility, porting portions of your code to a Kernel PlugIn driver.

11.6.1 Minimal Requirements for Creating a Kernel PlugIn Driver

To build a Kernel PlugIn driver you need the following tools:

• On Windows 98/Me/2000/XP/Server 2003/Vista:
  • The Visual C (VC) compiler (cl.exe, rc.exe, link.exe and nmake.exe).

  • Install the Windows Device Driver Development Kit (DDK) for your target operating system on your host machine

  ****************************************************************************************

  	NOTES
  	The Windows DDKs are available as part of the Microsoft Development Network (MSDN) subscription. You can also order them from http://www.microsoft.com/whdc/ddk/winddk.mspx Development of a Kernel PlugIn driver for a Windows 98/Me target PC should be done on a Windows 2000 or above host platform

  ****************************************************************************************

• On Linux and Solaris: You need GCC, gmake or make.

****************************************************************************************

	NOTE
	While this is not a minimal requirement, when developing a Kernel PlugIn driver it is highly recommended that you use two computers: set up one computer as your host platform and the other as your target platform. The host computer is the computer on which you develop your driver and the target computer is the computer on which you run and test the driver you develop

****************************************************************************************

11.6.2 Kernel PlugIn Implementation

11.6.2.1 Before You Begin

The functions described in this section are callback functions, implemented in the Kernel PlugIn driver, which are called when their calling event occurs - see section 11.5.4 for details. For example, KP_Init() [B.6.1] is the callback function that is called when the driver is loaded and should include any code that you want to execute upon loading.

The name of your driver is given in KP_Init(), which must be implemented with this name. For the other callback functions, it is the convention of this reference guide to mark these functions as KP_xxx() functions (e.g. KP_Open()). However, when developing your Kernel PlugIn driver you can also select different names for these callback functions. When generating Kernel PlugIn code with the DriverWizard, for example, the names of the callback functions (apart from KP_Init()) comply to the following format: KP_<Driver Name>_<Callback Function>. For example, if you named your project MyDevice the name of your Kernel PlugIn KP_Open() function will be KP_MyDevice_Open().

11.6.2.2 Write Your KP_Init() Function

Your KP_Init() function [B.6.1] should be of the following prototype:

BOOL __cdecl KP_Init(KP_INIT *kpInit);

where KP_INIT is the following structure:

typedef struct {
    DWORD dwVerWD;         /* Version of the WinDriver Kernel PlugIn library */
    CHAR cDriverName[12];  /* The Kernel PlugIn driver name (up to 8 chars) */
    KP_FUNC_OPEN funcOpen; /* The Kernel PlugIn driver's KP_Open() function */
} KP_INIT;

This function is called once, when the driver is loaded. The KP_INIT structure should be filled with the name of your Kernel PlugIn and the address of your KP_Open() function [B.6.2] (see example in WinDriver/samples/pci_diag/kp_pci /kp_pci .c).

****************************************************************************************

NOTES

The name that you select for your Kernel PlugIn driver - by setting it in the cDriverName field of the KP_INIT structure in KP_Init() [B.6.1] - should be the name of the driver that you wish to create - i.e., if you are creating a driver called XXX.sys, you should set the name "XXX" in the cDriverName field of the KP_INIT structure. You should verify that the driver name that is set in the user mode, in the call to WDC_xxxDeviceOpen() (PCI: [B.3.9] / PCMCIA: [B.3.10] / ISA: [B.3.11]) or in the pcDriverName field of the WD_KERNEL_PLUGIN structure that is passed to the low-level WD_KernelPlugInOpen() function (when not using the WDC library - see the WinDriver PCI Low-Level API Reference), is identical to the driver name that was set in the cDriverName field of the KP_INIT structure that is passed to KP_Init(). The best way to implement this is to define the driver name in a header file that is shared by the user-mode application and the Kernel PlugIn driver and use the defined value in all relevant locations.

****************************************************************************************

From the KP_PCI sample (WinDriver/samples/pci_diag/kp_pci /kp_pci .c):

/* KP_Init is called when the Kernel PlugIn driver is loaded.
   This function sets the name of the Kernel PlugIn driver and the driver's
   open callback function. */
BOOL __cdecl KP_Init(KP_INIT *kpInit)
{
    /* Verify that the version of the WinDriver Kernel PlugIn library
        is identical to that of the windrvr.h and wd_kp.h files */
    if (WD_VER != kpInit->dwVerWD)
    {
        /* Re-build your Kernel PlugIn driver project with the compatible
            version of the WinDriver Kernel PlugIn library (kp_nt<version>.lib)
            and windrvr.h and wd_kp.h files */
        return FALSE;
    }

    kpInit->funcOpen = KP_PCI_Open;
    strcpy (kpInit->cDriverName, KP_PCI_DRIVER_NAME);

    return TRUE;
}

Note that the driver name was set using a preprocessor definition. This definition is found in the WinDriver/samples/pci_diag/pci_lib.h header file, which is shared by the pci_diag user-mode application and the KP_PCI Kernel PlugIn driver:

/* Kernel PlugIn driver name (should be no more than 8 characters) */
#define KP_PCI_DRIVER_NAME "KP_PCI"

11.6.2.3 Write Your KP_Open() Function

Your KP_Open() function [B.6.2] should be of the following prototype:

BOOL __cdecl KP_Open(KP_OPEN_CALL *kpOpenCall, HANDLE hWD, 
    PVOID pOpenData, PVOID *ppDrvContext);

This callback is called when the user-mode application calls WDC_xxxDeviceOpen() (PCI: [B.3.9], PCMCIA: [B.3.10], ISA: [B.3.11]]) with the name of a Kernel PlugIn driver, or when it calls the low-level WD_KernelPlugInOpen() function (see the WinDriver PCI Low-Level API Reference), which is called by the wrapper WDC_xxxDeviceOpen() functions.

In the KP_Open() function, define the callbacks that you wish to implement in the Kernel PlugIn.

The following is a list of the callbacks that can be implemented:

Callback	Funtionality
KP_Close() [B.6.3]	Called when the user-mode application calls WDC_xxxDeviceClose() (PCI: [B.3.12], PCMCIA: [B.3.13], ISA: [B.3.14]) for a device that was opened with a Kernel PlugIn driver, or when it calls the low-level WD_KernelPlugInClose() function (see the WinDriver PCI Low-Level API Reference), which is called by the wrapper WDC_xxxDeviceClose() functions.
KP_Call() [B.6.4]	Called when the user-mode application calls the WDC_CallKerPlug() function [B.3.17] or the low-level WD_KernelPlugInCall() function (see the WinDriver PCI Low-Level API Reference), which is called by the wrapper WDC_CallKerPlug() function. This function implements a Kernel PlugIn message handler.
KP_IntEnable() [B.6.6]	Called when the user-mode application enables Kernel PlugIn interrupts, by calling WDC_IntEnable() with the fUseKP parameter set to TRUE (after having opened the device with a Kernel PlugIn), or by calling the low-level InterruptEnable() or WD_IntEnable() functions (see the WinDriver PCI Low-Level API Reference) with a handle to a Kernel PlugIn driver (set in the hKernelPlugIn field of the WD_INTERRUPT structure that is passed to the function). This function should contain any initialization required for your Kernel PlugIn interrupt handling.
KP_IntDisable() [B.6.7]	Called when the user-mode application calls WDC_IntDisable() [B.3.44], or the low-level InterruptDisable() or WD_IntDisable() functions (see the WinDriver PCI Low-Level API Reference), if the interrupts were previously enabled with a Kernel PlugIn driver (see the description of KP_IntEnable() above.) This function should free any memory that was allocated by the KP_IntEnable() [B.6.6] callback.
KP_IntAtIrql() [B.6.8]	Called when WinDriver receives an interrupt (provided the interrupts were enabled with a handle to the Kernel PlugIn). This is the function that will handle your interrupt in the kernel mode. The function runs at high interrupt request level. Additional deferred processing can be performed in KP_IntAtDpc() and also in the user mode (see below.)
KP_IntAtDpc() [B.6.9]	Called if the KP_IntAtIrql() callback [B.6.8] has requested deferred handling of the interrupt by returning TRUE. This function should include lower-priority kernel-mode interrupt handler code. The return value of this function determines the amount of times that the application's user-mode interrupt handler routine will be invoked (if at all).
KP_Event() [B.6.5]	Called when a Plug and Play or power management event occurs, provided the user-mode application previously registered to receive notifications for this event in the Kernel PlugIn by calling WDC_EventRegister() [B.3.46] with the fUseKP parameter set to TRUE (after having opened the device with a Kernel PlugIn), or by calling the low-level EventRegister() (see the WinDriver PCI Low-Level API Reference) or WD_EventRegister() functions with a handle to a Kernel PlugIn driver (set in the hKernelPlugIn field of the WD_EVENT structure that is passed to the function).

As indicated above, these handlers will be called (respectively) when the user-mode program opens/closes a Kernel PlugIn driver (using WDC_xxxDeviceOpen() / WD_KernelPlugInOpen(), WDC_xxxDeviceClose()/WD_KernelPlugInClose()), sends a message to the Kernel PlugIn driver (by calling WDC_CallKerPlug() / WD_KernelPlugInCall()), enables interrupts with a Kernel PlugIn driver (by calling WDC_IntEnable() with the fUseKP parameter set to TRUE, after having opened the device with a Kernel PlugIn / calling InterruptEnable() or WD_InterruptEnable() with a handle to the Kernel PlugIn set in the hKernelPlugIn field of the WD_INTERRUPT structure that is passed to function), or disables interrupts (WDC_IntDisable() / InterruptDisable() / WD_IntDisable()) that have been enabled using a Kernel PlugIn driver;
The Kernel PlugIn interrupt handlers will be called when an interrupt occurs, if the interrupts were enabled using a Kernel PlugIn driver (see above.)
The Kernel PlugIn event handler will be called when a Plug and Play or power management event occurs, if the application registered to receive notifications for the event that occurred using a Kernel PlugIn driver (by calling WDC_EventRegister() with the fUseKP parameter set to TRUE, after having opened the device with a Kernel PlugIn / calling EventRegister() (see the WinDriver PCI Low-Level API Reference) or WD_EventRegister() with a handle to a Kernel PlugIn driver set in the hKernelPlugIn field of the WD_EVENT structure that is passed to the function).

In addition to defining the Kernel PlugIn callback functions, you can implement code to perform any required initialization for the Kernel PlugIn in KP_Open(). In the sample KP_PCI driver and in the generated DriverWizard Kernel PlugIn driver, for example, KP_Open() also calls the shared library's initialization function and allocates memory for the Kernel PlugIn driver context, which is then used to store the device information that was passed to the function from the user mode.

From the KP_PCI sample (WinDriver/samples/pci_diag/kp_pci /kp_pci .c):

/* KP_PCI_Open is called when WD_KernelPlugInOpen() is called from the user mode.
   pDrvContext will be passed to the rest of the Kernel PlugIn callback functions. */
BOOL __cdecl KP_PCI_Open(KP_OPEN_CALL *kpOpenCall, HANDLE hWD, PVOID pOpenData,
    PVOID *ppDrvContext)
{
    PWDC_DEVICE pDev;
    WDC_ADDR_DESC *pAddrDesc;
    DWORD dwSize, dwStatus;
    void *temp;

    KP_PCI_Trace("KP_PCI_Open entered\n");
    
    kpOpenCall->funcClose = KP_PCI_Close;
    kpOpenCall->funcCall = KP_PCI_Call;
    kpOpenCall->funcIntEnable = KP_PCI_IntEnable;
    kpOpenCall->funcIntDisable = KP_PCI_IntDisable;
    kpOpenCall->funcIntAtIrql = KP_PCI_IntAtIrql;
    kpOpenCall->funcIntAtDpc = KP_PCI_IntAtDpc;
    kpOpenCall->funcEvent = KP_PCI_Event;

    /* Initialize the PCI library */
    dwStatus = PCI_LibInit();
    if (WD_STATUS_SUCCESS != dwStatus)
    {
        KP_PCI_Err("KP_PCI_Open: Failed to initialize the PCI library: %s",
            PCI_GetLastErr());
        return FALSE;
    }

    /* Create a copy of device information in the driver context */
    dwSize = sizeof(WDC_DEVICE);
    pDev = malloc(dwSize);
    if (!pDev)
        goto malloc_error;

    COPY_FROM_USER(&temp, pOpenData, sizeof(void *));
    COPY_FROM_USER(pDev, temp, dwSize);

    dwSize = sizeof(WDC_ADDR_DESC) * pDev->dwNumAddrSpaces;
    pAddrDesc = malloc(dwSize);

    if (!pAddrDesc)
        goto malloc_error;
    
    COPY_FROM_USER(pAddrDesc, pDev->pAddrDesc, dwSize);
    pDev->pAddrDesc = pAddrDesc;

    *ppDrvContext = pDev;

    KP_PCI_Trace("KP_PCI_Open: Kernel PlugIn driver opened successfully\n");
    
    return TRUE;
    
malloc_error:
    KP_PCI_Err("KP_PCI_Open: Failed allocating %ld bytes\n", dwSize);
    PCI_LibUninit();
    return FALSE;
}

11.6.2.4 Write the Remaining PlugIn Callbacks

Implement the remaining Kernel PlugIn routines that you wish to use (such as the KP_Intxxx() functions - for handling interrupts, or KP_Event() - for handling Plug and Play and power management events.)

11.6.3 Sample/Generated Kernel PlugIn Driver Code Overview

You can use the DriverWizard to generate a skeletal Kernel PlugIn driver for your device, and use it as the basis for your Kernel PlugIn driver development (recommended), or use the Kernel PlugIn sample (KP_PCI ), found under the WinDriver/samples/pci_diag/kp_pci directory.

The Kernel PlugIn driver is not a stand-alone module. It requires a user-mode application that initiates the communication with the drive. A relevant application will be generated for your when using the DriverWizard to generate Kernel PlugIn code. The pci_diag application (found under the WinDriver/samples/pci_diag/ directory) communicates with the sample KP_PCI driver.

Both the KP_PCI sample and the generated wizard code demonstrate communication between a user-mode application (pci_diag / xxx_diag - where xxx is the name you selected for your generated driver project) and a Kernel PlugIn driver (kp_pci .sys/.o/.ko / kp_xxx.sys/.o/.ko).

The sample/generated code demonstrates how to pass data to the Kernel PlugIn's KP_Open() function and how to use this function to allocate and store a global Kernel PlugIn driver context, which can be used by other functions in the Kernel PlugIn.

The sample/generated Kernel PlugIn code implements a message for getting the driver's version number, in order to demonstrate how to initiate specific functionality in the Kernel PlugIn from the user mode and how to pass data between the Kernel PlugIn driver and a user-mode WinDriver application via messages.

The sample/generated code also demonstrates how to handle interrupts in the Kernel PlugIn.
The Kernel PlugIn implements an interrupt counter. The Kernel PlugIn interrupt handler performs deferred processing and notifies the user-mode application of the arrival of the interrupt for every fifth incoming interrupt.
The KP_PCI sample demonstrates PCI interrupt handling. However, as indicated in the comments of the sample KP_IntAtIrql() function, you will need to modify this function in order to implement the correct code for acknowledging the interrupt on your specific device, since interrupt acknowledgment is hardware-specific.
The generated DriverWizard code will include sample interrupt code for the selected device (PCI/PCMCIA/ISA). The generated Kp_IntAtIrql() function will include code to implement the interrupt transfer commands that you defined in the wizard (by assigning registers read/write commands to the card's interrupt in the Interrupt tab, if indeed such commands were defined). For PCI and PCMCIA interrupts, which need to be acknowledged in the kernel when the interrupt is received (see section 9.2.2), it is recommended that you use the wizard to define the commands for acknowledging (clearing) the interrupt, before generating the Kernel PlugIn code, so that the generated code will already include the required code for executing the commands you defined.

In addition, the sample/generated code demonstrates how to receive notifications of Plug and Play and power management events in the Kernel PlugIn.

****************************************************************************************

TIP

We recommend that you build and run the sample/generated Kernel PlugIn project (and corresponding user-mode application) ''as-is'' before modifying the code or writing your own Kernel PlugIn driver. (Note, however, that as explained above, you cannot use the generic KP_PCI driver to handle the interrupts on your specific PCI device without first modifying the code in order to implement the required interrupt acknowledged for your device.)

****************************************************************************************

11.6.4 Kernel PlugIn Sample/Generated Code Directory Structure

11.6.4.1 pci_diag and kp_pci Sample Directories

The Kernel PlugIn sample code - KP_PCI - is implemented in the kp_pci .c file. This sample driver is part of the WinDriver PCI diagnostics sample - pci_diag - which contains, in addition to the KP_PCI driver, a user-mode application that communicates with the driver (pci_diag) and a shared library that includes API that can be utilized by both the user-mode application and the Kernel PlugIn driver. The source files for this sample are implemented in C.

Following is an outline of the files found in the WinDriver/pci_diag/ directory:

• kp_pci / - Contains the KP_PCI Kernel PlugIn driver files:
  • kp_pci .c: The source code of the KP_PCI driver.
  • Project and/or make files and related files for building the Kernel PlugIn driver. The Windows project files are located in sub-directories for the target IDE (msdev2005 / msdev2003 / msdev_6) under x86$\backslash$ (32-bit) and amd64$\backslash$ (64-bit) directories. The Solaris makefile is located under a SOLARIS/ sub-directory.
  • A pre-compiled version of the KP_PCI Kernel PlugIn driver for the target OS:
    
    • Windows x86 32-bit: WINNT.i386$\backslash$kp_pci .sys - a 32-bit version of the driver, built with the WinNT DDK.
      
    • Windows x64: WINNT.x86_64$\backslash$kp_pci .sys - a 64-bit version of the driver, built with the Windows Server 2003 DDK.
      
    • Solaris: SOLARIS/kp_pci .
      
    • Linux there is no pre-compiled version since Linux kernel modules must be compiled with the header files from the kernel version installed on the target - see section 14.4.

• pci_lib.c: Implementation of a library for accessing PCI devices using WinDriver's WDC API [B.2].
  The library's API is used both by the user-mode application (pci_diag.c) and by the Kernel PlugIn driver (kp_pci .c).

• pci_lib.h: Header file, which provides the interface for the pci_lib library.

• pci_diag.c: Implementation of a sample diagnostics user-mode console (CUI) application, which demonstrates communication with a PCI device using the pci_lib and WDC libraries.
  The sample also demonstrates how to communicate with a Kernel PlugIn driver from a user-mode WinDriver application. By default, the sample attempts to open the selected PCI device with a handle to the KP_PCI Kernel PlugIn driver. If successful, the sample demonstrates how to interact with a Kernel PlugIn driver, as detailed in section 11.6.3. If the application fails to open a handle to the Kernel PlugIn driver, all communication with the device is performed from the user mode.

• pci.inf (Windows): A sample WinDriver PCI INF file for Windows 98 / Me / 2000 / XP / Server 2003 / Vista. NOTE: To use this file, change the vendor and device IDs in the file to comply comply with those of your specific device.

• Project and/or make files for building the pci_diag user-mode application.
  The Windows project files are located in sub-directories for the target IDE (msdev2005 / msdev2003 / msdev_6 / cbuilder4 / cbuilder3) under x86$\backslash$ (32-bit) and amd64$\backslash$ (64-bit) directories.
  The MSDEV directories also include workspace/solution files for building both the Kernel PlugIn driver and user-mode application projects.
  The Linux and Solaris makefiles are located under LINUX/ and SOLARIS/ sub-directories (respectively).

• A pre-compiled version of the user-mode application (pci_diag) for your target operating system:
  
  • Windows: WIN32$\backslash$pci_diag.exe.
    
  • Linux: LINUX/pci_diag.
    
  • Solaris: SOLARIS/pci_diag.

• files.txt: A list of the sample pci_diag files.

• readme.txt: An overview of the sample Kernel PlugIn driver and user-mode application and instructions for building and testing the code.

11.6.4.2 The Generated DriverWizard Kernel PlugIn Directory

The generated DriverWizard Kernel PlugIn code for your device will include a kernel-mode Kernel PlugIn project and a user-mode application that communicates with it. As opposed to the generic KP_PCI and pci_diag sample, the generated wizard code will utilize the resources information detected and/or defined for your specific device, as well as any device-specific information that you define in the wizard before generating the code.

As indicated in section 11.6.3, when using the driver to handle PCI or PCMCIA interrupts, it is highly recommended that you define the registers that need to be read/written in order to acknowledge the interrupt, and set up the relevant read/write commands from/to these registers in the DriverWizard, before generating the code, thus enabling the generated interrupt handler code to utilize the hardware-specific information that you defined.

Following is an outline of the generated DriverWizard files when selecting to generate Kernel PlugIn code (where xxx represents the name that you selected for the driver when generating the code and kp_xxx is the directory in which you selected to save the code). NOTE: The outline below relates to the generated C code, but on Windows you can also generate similar C# code, which includes a C Kernel PlugIn driver (since kernel-mode drivers cannot be implemented in C#), a .NET C# library, and a C# user-mode application that communicates with the Kernel PlugIn driver.

• kermode/ - Contains the KP_XXX Kernel PlugIn driver files:
  • kp_xxx.c: The source code of the KP_XXX driver.
  • Project and/or make files and related files for building the Kernel PlugIn driver. The Windows project files are located in sub-directories for the target IDE (msdev2005 / msdev2003 / msdev_6) under x86$\backslash$ (32-bit) and amd64$\backslash$ (64-bit) directories. The Linux and Solaris files are located under linux/ and solaris/ sub-directories (respectively).

• xxx_lib.c: Implementation of a library for accessing your device using WinDriver's WDC API [B.2].
  The library's API is used both by the user-mode application (xxx_diag) and by the Kernel PlugIn driver (KP_XXX).

• xxx_lib.h: Header file, which provides the interface for the xxx_lib library.

• xxx_diag.c: Implementation of a sample diagnostics user-mode console (CUI) application, which demonstrates communication your device using the xxx_lib and WDC libraries.
  The application also demonstrates how to communicate with a Kernel PlugIn driver from a user-mode WinDriver application. By default, the application attempts to open your device with a handle to the KP_XXX Kernel PlugIn driver. If successful, the application demonstrates how to interact with a Kernel PlugIn driver, as detailed in section 11.6.3. If the application fails to open a handle to the Kernel PlugIn driver, all communication with the device is performed from the user mode.

• Project and/or make files for building the xxx_diag user-mode application.
  The Windows project files are located in sub-directories for the target IDE (msdev2005 / msdev2003 / msdev_6 / cbuilder4 / cbuilder3) under x86$\backslash$ (32-bit) and amd64$\backslash$ (64-bit) directories.
  The MSDEV directories also include workspace/solution files for building both the Kernel PlugIn driver and user-mode application projects.
  The Linux and Solaris makefiles are located under linux/ and solaris/ sub-directories (respectively).

• xxx_files.txt: A list of the generated files and instructions for building the code.

• xxx.inf: A WinDriver INF file for your device (relevant only for Plug and Play devices, such as PCI or PCMCIA, on Windows 98/Me/2000/XP/Server 2003/Vista).

11.6.5 Handling Interrupts in the Kernel PlugIn

Interrupts will be handled in the Kernel PlugIn driver if enabled using a Kernel PlugIn driver, as explained below [11.6.5.2].

If Kernel PlugIn interrupts were enabled, when WinDriver receives a hardware interrupt, it calls the Kernel PlugIn driver's KP_IntAtIrql() function [B.6.8]. If KP_IntAtIrql() returns TRUE, the deferred KP_IntAtDpc() Kernel PlugIn function [B.6.9] will be called, after KP_IntAtIrql() completes its processing and returns TRUE. The return value of KP_IntAtDpc() determines how many times (if at all) the user-mode interrupt handler routine will be executed.
In the KP_PCI sample, for example, the Kernel PlugIn interrupt handler code counts five interrupts and notifies the user mode on every fifth interrupt, thus WD_IntWait() (see the WinDriver PCI Low-Level API Reference) will return on only one out of every five incoming interrupts in the user mode. (KP_IntAtIrql() returns TRUE every five interrupts to activate KP_IntAtDpc(), and KP_IntAtDpc() returns the number of accumulated deferred DPC calls from KP_IntAtIrql(), so all at all the user-mode interrupt handler will be executed once for every 5 interrupts.)

11.6.5.1 Interrupt Handling in User Mode (Without Kernel PlugIn)

If the Kernel PlugIn interrupt handle is not enabled, then each incoming interrupt will cause WD_IntWait() to return and your user-mode interrupt handler routine will be invoked once WinDriver completes the kernel processing of the interrupts (mainly executing the interrupt transfer commands passed in the call to WDC_IntEnable() [B.3.43] or the low-level InterruptEnable() or WD_IntEnable() functions - see the WinDriver PCI Low-Level API Reference) - see Figure 11.2.

Figure 11.2: Interrupt Handling Without Kernel PlugIn

11.6.5.2 Interrupt Handling in the Kernel (Using a Kernel PlugIn)

To have the interrupts handled by the Kernel PlugIn, the user-mode application should open a handle to the device with a Kernel PlugIn driver, by passing the name of a Kernel PlugIn driver to the WDC_xxxDeviceOpen() function (PCI: [B.3.9], PCMCIA: [B.3.10], ISA: [B.3.11]), and then call WDC_IntEnable() [B.3.43] with the fUseKP parameter set to TRUE.

If your are not using the WDC_xxx API [B.2], your application should pass a handle to the Kernel PlugIn driver to the WD_IntEnable() function or the wrapper InterruptEnable() function (which calls WD_IntEnable() and WD_IntWait()). This enables the Kernel PlugIn interrupt handler. (The Kernel PlugIn handle is passed within the hKernelPlugIn field of the WD_INTERRUPT structure that is passed to the functions.) For details regarding the low-level WD_xxx() API, refer to the WinDriver PCI Low-Level API Reference.

Figure 11.3: Interrupt Handling With the Kernel PlugIn

When calling WDC_IntEnable()/InterruptEnable()/WD_IntEnable() to enable interrupts in the Kernel PlugIn, your Kernel PlugIn's KP_IntEnable() callback function [B.6.6] is activated. In this function you can set the interrupt context that will be passed to the Kernel PlugIn interrupt handlers, as well as write to the device to actually enable the interrupts in the hardware and implement any other code required in order to correctly enable your device's interrupts.

If the Kernel PlugIn interrupt handler is enabled, then KP_IntAtIrql() [B.6.8] for each incoming interrupt. The code in the KP_IntAtIrql() function is executed at high interrupt request level. While this code is running, the system is halted, i.e., there will be no context switches and no lower-priority interrupts will be handled.

The code in the KP_IntAtIrql() function is limited in the following ways:

• It may only access non-pageable memory.

• It may only call the following functions (or wrapper functions that call these functions):
  • WDC_xxx read/write address or configuration space functions.
  • WDC_MultiTransfer() [B.3.24], WD_Transfer(), WD_MultiTransfer() or WD_DebugAdd() (see the WinDriver PCI Low-Level API Reference).
  • Specific kernel OS functions (such as WinDDK functions) that can be called from high interrupt request level. (Note that the use of such functions may break the code's portability to other operating systems).

• It may not call malloc(), free() or any WDC_xxx or WD_xxx API other than those listed above

Because of the aforementioned limitations, the code in KP_IntAtIrql() should be kept to a minimum, such as acknowledgment (clearing) of level sensitive interrupts. Other code that you want to run in the interrupt handler should be implemented in KP_IntAtDpc() [B.6.9], which runs at a deferred interrupt level and does not face the same limitations as KP_IntAtIrql(). KP_IntAtDpc() is called after KP_IntAtIrql() returns (provided it returns TRUE).

You can also leave some additional interrupt handling to the user mode. The return value of KP_IntAtDpc() [B.6.9] determines the amount of times (if any) that your user-mode interrupt handler routine will be called after the kernel-mode interrupt processing is completed.

11.6.6 Message Passing

The WinDriver architecture enables a kernel-mode function to be activated from the user mode by passing a message from the user mode to the Kernel PlugIn driver using WDC_CallKerPlug() [B.3.17] or the low-level WD_KernelPlugInCall() function (see the WinDriver PCI Low-Level API Reference).
The messages are defined by the developer in a header file that is common to both the user-mode and kernel-mode plugin parts of the driver. In the pci_diag KP_PCI sample and the generated DriverWizard code, the messages are defined in the shared library header file - pci_lib.h in the sample or xxx_lib.h in the generated code.

Upon receiving the message from the user mode, WinDriver will execute the KP_Call() [B.6.4] Kernel PlugIn callback function, which identifies the message that has been received and executes the relevant code for this message (as implemented in the Kernel PlugIn).

The sample/generated Kernel PlugIn code implement a message for getting the driver's version in order to demonstrate Kernel PlugIn data passing. The code that sets the version number in KP_Call() is executed in the Kernel PlugIn whenever the Kernel PlugIn receives a relevant message from the user-mode application. You can see the definition of the message in the shared pci_lib.h/xxx_lib.h shared header file. The user-mode application (pci_diag.exe/xxx_diag.exe) sends the message to the Kernel PlugIn driver via the WDC_CallKerPlug() function [B.3.17].