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 the user mode. Then, if you encounter performance problems or require greater flexibility, port 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: The Windows Driver Kit (WDK), including its C build tools.
    [Note]
    The WDK is available as part of a Microsoft Development Network (MSDN) subscription, or from Microsoft Connect. For more information, refer to Microsoft's Windows Driver Kit (WDK) page — http://msdn.microsoft.com/en-us/library/windows/hardware/gg487428.aspx.
  • On Linux:
    • 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.8.1] is the callback function that is called when the driver is loaded.

The name of your driver is given in KP_Init. The Kernel PlugIn driver's implementation of this callback must be named KP_Init. The names of the other Kernel PlugIn callback functions (which are passed to KP_Init) are left to the discretion of the driver developer. It is the convention of this reference guide to refer to these callbacks using the format KP_<Functionality> — for example, KP_Open.
When generating Kernel PlugIn code with the DriverWizard, the names of the callback functions (apart from KP_Init) conform to the following format: KP_<Driver Name>_<Functionality>. For example, if you named your project MyDevice, the name of your Kernel PlugIn KP_Call callback will be KP_MyDevice_Call.

11.6.2.2. Write Your KP_Init Function

Your KP_Init function [B.8.1] should be of the following prototype:

BOOL __cdecl KP_Init (KP_INIT *kpInit);

This function is called once, when the driver is loaded. The function should fill the received KP_INIT structure [B.9.4] with the name of the Kernel PlugIn driver, the name of the WinDriver Kernel PlugIn driver library, and the driver's KP_Open callback(s) [B.8.2] (see example in WinDriver/samples/pci_diag/kp_pci/kp_pci.c).

[Note]
  • The name that you select for your Kernel PlugIn driver — by setting it in the cDriverName field of the KP_INIT structure [B.9.4] that is passed to KP_Init [B.8.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 used when opening a handle to the Kernel PlugIn driver in the user mode [12.4] — in the pKPOpenData parameter of the WDC_KernelPlugInOpen() [B.3.15] or WDC_xxxDeviceOpen() (PCI [B.3.10] / ISA [B.3.11]) functions, or in the pcDriverName field of the pKernelPlugIn parameter passed to the low-level WD_KernelPlugInOpen() function — is identical to the driver name that was set in the cDriverName field of the KP_INIT structure [B.9.4] that is passed to KP_Init [B.8.1].
    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(s). */
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)
    {
        /* Rebuild 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;
    kpInit->funcOpen_32_64 = KP_PCI_VIRT_Open_32_64;
    strcpy (kpInit->cDriverName, KP_PCI_DRIVER_NAME);

    return TRUE;
}

Note that the driver name in the sample is 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(s)

You can implement either one or two KP_Open functions, depending on your target configuration [B.8.2]. The KP_Open function(s) 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 opening a handle to the Kernel PlugIn driver from the user mode — i.e., when WD_KernelPlugInOpen() is called, either directly or via WDC_KernelPlugInOpen() [B.3.15] or WDC_xxxDeviceOpen() (PCI [B.3.10] / ISA [B.3.11]), as explained in Section 12.4.

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:

CallbackFunctionality
KP_Close [B.8.3] Called when the WD_KernelPlugInClose() function (see the WinDriver PCI Low-Level API Reference) is called from the user mode — either directly, or via one of the high-level WDC_xxxDeviceClose() functions (PCI [B.3.12] / ISA [B.3.13]) when called for a device that contains an open Kernel PlugIn handle [12.4].
KP_Call [B.8.4] Called when the user-mode application calls the WDC_CallKerPlug() function [B.3.16] 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.8.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 a Kernel PlugIn handle), 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.8.7] Called when the user-mode application calls WDC_IntDisable() [B.3.42], 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 callback [B.8.6].
KP_IntAtIrql [B.8.8] Called when WinDriver receives a legacy interrupt, provided the received interrupt was enabled with a handle to the Kernel PlugIn. This is the function that will handle your legacy interrupt in the kernel mode. The function runs at high interrupt request level. Additional deferred processing of the interrupt can be performed in KP_IntAtDpc and also in the user mode (see below).
KP_IntAtDpc [B.8.9] Called if the KP_IntAtIrql callback [B.8.8] has requested deferred handling of a legacy 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_IntAtIrqlMSI [B.8.10] Called when WinDriver receives an MSI or MSI-X, provided MSI/MSI-X was enabled for the received interrupt with a handle to the Kernel PlugIn. This is the function that will handle your MSI/MSI-X in the kernel mode. The function runs at high interrupt request level. Additional deferred processing of the interrupt can be performed in KP_IntAtDpcMSI and also in the user mode (see below).
Note: MSI/MSI-X is supported on Linux and Windows 7 and higher.
KP_IntAtDpcMSI [B.8.11] Called if the KP_IntAtIrqlMSI callback [B.8.10] has requested deferred handling of an MSI/MSI-X interrupt by returning TRUE.
This function should include lower-priority kernel-mode MSI/MSI-X 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).
Note: MSI/MSI-X is supported on Linux and Windows 7 and higher.
KP_Event [B.8.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.45] with the fUseKP parameter set to TRUE (after having opened a Kernel PlugIn handle), 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 handle to Kernel PlugIn driver [12.4], 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 a handle to the 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 your KP_Open callback(s) [B.8.2]. In the sample KP_PCI driver and in the generated DriverWizard Kernel PlugIn driver, for example, the Kernel PlugIn open callbacks also call the shared library's initialization function and allocate 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)
{
    PCI_DEV_ADDR_DESC *pDevAddrDesc;
    WDC_ADDR_DESC *pAddrDesc;
    DWORD dwSize;
    DWORD dwStatus;

    /* 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;
    }

    KP_PCI_Trace("KP_PCI_Open entered. PCI library initialized.\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->funcIntAtIrqlMSI = KP_PCI_IntAtIrqlMSI;
    kpOpenCall->funcIntAtDpcMSI = KP_PCI_IntAtDpcMSI;
    kpOpenCall->funcEvent = KP_PCI_Event;

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

    COPY_FROM_USER(pDevAddrDesc, pOpenData, dwSize);
    dwSize = sizeof(WDC_ADDR_DESC) * pDevAddrDesc->dwNumAddrSpaces;
    pAddrDesc = malloc(dwSize);
    if (!pAddrDesc)
        goto malloc_error;

    COPY_FROM_USER(pAddrDesc, pDevAddrDesc->pAddrDesc, dwSize);
    pDevAddrDesc->pAddrDesc = pAddrDesc;
    *ppDrvContext = pDevAddrDesc;

    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);
    if (pDevAddrDesc)
        free(pDevAddrDesc);
    PCI_LibUninit();
    return FALSE;
}
[Note]
The KP_PCI sample also defines a similar KP_PCI_Open_32_64 callback, for use when opening a handle to a 64-bit Kernel PlugIn from a 32-bit application.

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 DriverWizard to generate a skeletal Kernel PlugIn driver for your device, and use the generated code as the basis for your Kernel PlugIn driver development (recommended); alternatively, you can use one of the Kernel PlugIn WinDriver samples as the basis for your Kernel PlugIn development.

[Note]
The Kernel PlugIn documentation in this manual focuses on the generated DriverWizard code, and the generic PCI Kernel PlugIn sample — KP_PCI, located in the WinDriver/samples/pci_diag/kp_pci directory.
If you are using the a PCI Express card with the Xilinx Bus Master DMA (BMD) design, you can also use the KP_BMD Kernel PlugIn sample as the basis for your development; the WinDriver/xilinx/bmd_design directory contains all the relevant sample files — see the Xilinx BMD Kernel PlugIn directory structure note at the end of Section 11.6.4.1.

The Kernel PlugIn driver is not a standalone module. It requires a user-mode application that initiates the communication with the driver. A relevant application will be generated for your driver when using 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 wizard-generated 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/.kext / kp_xxx.sys/.o/.ko/.kext — depending on the OS).

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 that 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 and interrupt handlers, including deferred processing interrupt handling, which is used to notify the user-mode application of the arrival of every fifth incoming interrupt.
The KP_PCI sample's KP_IntAtIrql [B.8.8] and KP_IntAtDpc [B.8.9] functions demonstrate legacy level-sensitive PCI interrupt handling. 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 sample KP_IntAtIrqlMSI [B.8.10] and KP_IntAtDpcMSI [B.8.11] functions demonstrate handling of Message-Signaled Interrupts (MSI) and Extended Message-Signaled Interrupts (MSI-X) (see detailed information in Section 9.2).
The generated DriverWizard code will include sample interrupt handler code for the selected device (PCI/ISA). The generated KP_IntAtIrql function will include code to implement any interrupt transfer commands defined in the wizard (by assigning registers read/write commands to the card's interrupt in the Interrupt tab). For legacy PCI interrupts, which need to be acknowledged in the kernel when the interrupt is received (see Section 9.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. It is also recommended that you prepare such transfer commands when handling interrupts for hardware that supports MSI/MSI-X, in case enabling of MSI/MSI-X fails and the interrupt handling defaults to using level-sensitive interrupts (if supported by the hardware).
Note: Memory allocated for the transfer commands must remain available until the interrupts are disabled .

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 you will need to modify or remove the hardware-specific transfer commands in the sample's KP_IntAtIrql function, as explained above.

11.6.4. Kernel PlugIn Sample/Generated Code Directory Structure

11.6.4.1. pci_diag and kp_pci Sample Directories

The KP_PCI Kernel PlugIn sample code 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 APIs 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/samples/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/make files are located in subdirectories for the target development environment (msdev_<version>/win_gcc) under x86 (32-bit) and amd64 (64-bit) directories.
      The Linux makefile is generated using a configure script, located directly under the kp_pci directory.
    • A pre-compiled version of the KP_PCI Kernel PlugIn driver for the target OS:
      • Windows x86 32-bit: WINNT.i386\kp_pci.sys — a 32-bit version of the driver, built for Windows 7 and higher.
      • Windows x64: WINNT.x86_64\kp_pci.sys — a 64-bit version of the driver, built for Windows Server 2003 and higher.
      • Linux: There is no pre-compiled version of the driver for Linux, 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. NOTE: To use this file, change the vendor and device IDs in the file to comply with those of your specific device.
    [Note]
    To use Message-Signaled Interrupts (MSI) or Extended Message-Signaled Interrupts (MSI-X) on Windows 7 and higher (for PCI cards that support MSI/MSI-X) you will need to modify or replace the sample INF file so that your INF file includes specific MSI information; otherwise WinDriver will attempt to use legacy level-sensitive interrupt handling for your card, as explained in Section 9.2.7.1 of the manual.
  • Project and/or make files for building the pci_diag user-mode application.
    The Windows project/make files are located in subdirectories for the target development environment (msdev_<version>/win_gcc) under x86 (32-bit) and amd64 (64-bit) directories. The msdev_<version> MS Visual Studio directories also include solution files for building both the Kernel PlugIn driver and user-mode application projects.
    The Linux makefile is located under a LINUX subdirectory.
  • A pre-compiled version of the user-mode application (pci_diag) for your target operating system:
    • Windows: WIN32\pci_diag.exe
    • Linux: LINUX/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.
[Note]Xilinx BMD Kernel PlugIn Directory Structure
The structure of the sample directory for PCI Express cards with the Xilinx Bus Master DMA (BMD) design — WinDriver/xilinx/bmd_design — is similar to that of the generic PCI sample's pci_diag directory, except for the following issues: the bmd_diag user-mode application files are located under a diag subdirectory, and the kp subdirectory, which contains the Kernel PlugIn driver's (KP_BMD) source files, currently has make files only for Windows.

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 wizard-generated 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 legacy PCI 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 DriverWizard, before generating the code, thus enabling the generated interrupt handler code to utilize the hardware-specific information that you defined. It is also recommended that you prepare such transfer commands when handling interrupts for hardware that supports MSI/MSI-X, in case enabling of MSI/MSI-X fails and the interrupt handling defaults to using level-sensitive interrupts (if supported by the hardware).
Note: Memory allocated for the transfer commands must remain available until the interrupts are disabled .

Following is an outline of the generated DriverWizard files when selecting to generate Kernel PlugIn code (where xxx signifies the name that you selected for the driver when generating 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/make files are located in subdirectories for the target development environment (msdev_<version>/win_gcc) under x86 (32-bit) and amd64 (64-bit) directories.
      The Linux makefile is generated using a configure script, located in a linux subdirectory.
  • 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/make files are located in subdirectories for the target development environment (msdev_<version>/win_gcc) under x86 (32-bit) and amd64 (64-bit) directories. The msdev_<version> MS Visual Studio directories also include solution files for building both the Kernel PlugIn driver and user-mode application projects.
    The Linux makefile is located in a linux subdirectory.
  • xxx_files.txt: A list of the generated files and instructions for building the code.
  • xxx.inf (Windows): A WinDriver INF file for your device. This file is required only when creating a Windows driver for a Plug-and-Play device, such as PCI.

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 high-IRQL handler — KP_IntAtIrql [B.8.8] (legacy interrupts) or KP_IntAtIrqlMSI [B.8.10] (MSI/MSI-X). If the high-IRQL handler returns TRUE, the relevant deferred Kernel PlugIn interrupt handler — KP_IntAtDpc [B.8.9] (legacy interrupts) or KP_IntAtDpcMSI [B.8.11] (MSI/MSI-X) — will be called after the high-IRQL handler completes its processing and returns. The return value of the DPC function 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. The high-IRQL handler — KP_IntAtIrql [B.8.8] or KP_IntAtIrqlMSI [B.8.10] — returns TRUE every five interrupts to activate the DPC handler — KP_IntAtDpc or KP_IntAtDpcMSI — and the DPC function returns the number of accumulated DPC calls from the high-IRQL handler. As a result, the user-mode interrupt handler will be executed once for every 5 interrupts.

11.6.5.1. Interrupt Handling in the User Mode (Without the 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.41] 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

Interrupt Handling Without Kernel PlugIn

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

To have the interrupts handled by the Kernel PlugIn, the user-mode application should open a handle to a Kernel PlugIn driver (as explained in Section 12.4), and then call WDC_IntEnable() [B.3.41] 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

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.8.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 the relevant high-IRQL handler, based on the type of interrupt that was enabled — KP_IntAtIrql [B.8.8] (legacy interrupts) or KP_IntAtIrqlMSI [B.8.10] (MSI/MSI-X) — will be called for each incoming interrupt. The code in the high-IRQL handler 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.

Code running at high IRQL 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.23], or the low-level WD_Transfer(), WD_MultiTransfer(), or WD_DebugAdd() functions (see the WinDriver PCI Low-Level API Reference).
    • Specific kernel OS functions (such as WDK 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 the high-IRQL handler (KP_IntAtIrql [B.8.8] or KP_IntAtIrqlMSI [B.8.10]) 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 the DPC function (KP_IntAtDpc [B.8.9] or KP_IntAtDpcMSI [B.8.11]), which runs at a deferred interrupt level and does not face the same limitations as the high-IRQL handlers. The DPC function is called after its matching high-IRQL function returns, provided the high-IRQL handler returns TRUE.

You can also leave some additional interrupt handling to the user mode. The return value of your DPC function — KP_IntAtDpc [B.8.9] or KP_IntAtDpcMSI [B.8.11] — 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.16] 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.8.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.16].