Technical Document #62

Technical Document #62
Kernel PlugIn Driver Installation — General Guidelines

When using WinDriver's Kernel PlugIn feature you are creating your own driver file, which is used in addition to the generic WinDriver kernel driver— windrvr<version>.sys/.o/.ko in the newer versions (e.g., windrvr1200.sys/.o/.ko).

Please be sure to diligently follow the instructions in the WinDriver User's Manual for building and installing your Kernel PlugIn driver.

You should specifically pay attention to the following points:

  • If you have used WinDriver's Kernel PlugIn sample driver (KP_PCI / KPTEST in v6.2.3-) as the basis for your Kernel PlugIn application, be sure to replace the driver name ("KP_PCI" / "KPTEST") in all locations in the sample files with your chosen driver name.

    The driver name should be indicated in the code in Capital Letters and without the sys/vxd/kext/o/ko extension.

    In v7.0.0+ of WinDriver, verify specifically that you have specified the driver name correctly in the definition of KP_PCI_DRIVER_NAME in the equivalent of the sample's pci_lib.h file.

    For earlier versions of WinDriver (v6.2.3-), modify the equivalent of the following line in KP_Init():
      strcpy(kpInit->cDriverName, "KPTEST");
    and change the assignment to the pcDriverName member of the WD_KERNEL_PLUGIN structure, which is passed to WD_KernelPlugInOpen() in the user-mode project.

  • When developing a SYS driver for Windows (Windows 98 and higher), remember to install Microsoft's driver development kit for your OS (WDK / DDK) and set the BASEDIR environment variable to the location of your WDK/DDK directory before attempting to build your Kernel PlugIn SYS driver (as explained in the manual). (For version 5.0.5 of WinDriver and earlier, it is recommended to build your code with the Windows NT DDK. For Windows NT 4.0 — in WinDriver versions that support this OS — you also need to install the NT SDK.)

    For earlier versions of WinDriver (v6.0x-), which supported development of VxD drivers on Windows 95/98/Me, when developing a VxD driver you do not need to install the WDK/DDK (unless you added your own DDK function calls to the Kernel PlugIn code). When using the compile.bat file from the KPTEST sample to compile your VxD driver, comment-out or remove the following line:
       nmake %1 /f kptest.mak
    leaving only the line:
       nmake %1 /f kptest.mak WIN95=1

    Beginning with v5.2.0 of WinDriver, the DriverWizard can also be used to generate Kernel PlugIn code and a compatible user-mode application for your device, including the required project or makefiles for building the code (depending on the target OS).
    For Windows, you can build the generated MS Visual Studio (Visual C++) project into a SYS driver on a Windows NT and higher machine, by simply opening the generated workspace/solution file — xxx.dsw/sln — and building the code, after setting the Active Build Configuration according to the OS for which you are developing. (SYS drivers for Windows 98/Me — supported in earlier versions of WinDriver — should be built on a Windows NT or higher machine.)
    Beginning with v11.0.0 of WinDriver, you can also use the generated Windows GCC makefile to build the generated Kernel PlugIn code in your selected environment Windows GCC environment (MinGW/Cygwin).

    Note: When building a kernel project with MS Visual Studio, the project path must not contain any spaces.

  • Verify that the WinDriver kernel module is installed: Before installing your Kernel PlugIn driver, verify that the WinDriver driver — windrvr<version>.sys/.o/.ko in the newer WinDriver versions (e.g., windrvr1200.sys/.o/.ko) — is installed, since the Kernel PlugIn module depends on the WinDriver module for its successful operation. (You can run the Debug Monitor to verify that WinDriver is loaded).

  • Install your Kernel PlugIn driver:

    • Remember to copy your Kernel PlugIn driver (my_kp/.sys/.vxd/.kext/.o/.ko) to the operating system's drivers/modules directory before attempting to install the driver. On Linux, beginning with v6.2.3 of WinDriver you do not need to copy the driver file, since the driver installation (make install) will handle this for you.

    • Don't forget to install your Kernel PlugIn driver before running your application:

      On Windows: Use the wdreg installation utility (or wdreg_gui/wdreg16 — depending on the WinDriver version and OS that you are using) to install the driver:

      To install a my_kp.sys driver, run this command:
          wdreg -name MY_KP install

      To install a my_kp.vxd driver (in the WinDriver versions that support this driver type), use the -vxd flag:
           wdreg -name -vxd MY_KP install

      On Linux: For v6.2.3+ of WinDriver, from the kermode/ Kernel PlugIn directory run this command:
          make install
      For earlier versions of WinDriver, use insmod to install the driver module.

      On Solaris: Use add_drv to install the driver.

The Kernel PlugIn is not backward compatible. Therefore, when switching to a different version of WinDriver, you need to rebuild your Kernel PlugIn driver using the new version.