12.7. Compile Your Kernel PlugIn Driver

[Note]
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.

12.7.1. Windows Kernel PlugIn Driver Compilation

The sample WinDriver\samples\pci_diag\kp_pci Kernel PlugIn directory and the generated DriverWizard Kernel PlugIn <project_dir>\kermode directory (where <project_dir> is the directory in which you selected to save the generated driver project) contain the following Kernel PlugIn project files (where xxx is the driver name — pci for the sample / the name you selected when generating the code with the wizard):

  • x86 — 32-bit project files:
    • msdev_<version>\kp_xxx.vcproj — 32-bit MS Visual Studio project file (where <version> signifies the IDE version — e.g., "2012")
    • win_gcc/makefile — 32-bit Windows GCC (MinGW/Cygwin) makefile
  • amd64 — 64-bit project files:
    • msdev_<version>\kp_xxx.vcproj — 64-bit MS Visual Studio project file (where <version> signifies the IDE version — e.g., "2012")
    • win_gcc/makefile — 64-bit Windows GCC (MinGW/Cygwin) makefile

The sample WinDriver\samples\pci_diag directory and the generated <project_dir> directory contain the following project files for the user-mode application that drives the respective Kernel PlugIn driver (where xxx is the driver name — pci for the sample / the name you selected when generating the code with the wizard):

  • x86 — 32-bit project files:
    • msdev_<version>\xxx_diag.vcproj — 32-bit MS Visual Studio project file (where <version> signifies the IDE version — e.g., "2012")
    • win_gcc/makefile — 32-bit Windows GCC (MinGW/Cygwin) makefile
  • amd64 — 64-bit project files:
    • msdev_<version>\xxx_diag.vcproj — 64-bit MS Visual Studio project file (where <version> signifies the IDE version — e.g., "2012")
    • win_gcc/makefile — 64-bit Windows GCC (MinGW/Cygwin) makefile

The msdev_<version> MS Visual Studio directories listed above also contain xxx_diag.sln solution files that include both the Kernel PlugIn and user-mode projects.

If you used DriverWizard to generate your code and you selected to generate a dynamic-link library (DLL) (Step 6.c), the generated <project_dir> directory will also have a libproj DLL project directory. This directory has x86 (32-bit) and/or amd64 (64-bit) directories that contain msdev_<version> directories for your selected IDEs, and each IDE directory has an xxx_libapi.vcproj project file for building the DLL. The DLL is used from the wizard-generated user-mode diagnostics project (xxx_diag.vcproj).

To build your Kernel PlugIn driver and respective user-mode application on Windows, follow these steps:

  1. Verify that the Windows Driver Kit (WDK) is installed.
  2. Set the BASEDIR environment variable to point to the location of the directory in which WDK is installed.
  3. Build the Kernel PlugIn SYS driver (kp_pci.sys — sample / kp_xxx.sys — wizard-generated code):
    • Using MS Visual Studio — Start Microsoft Visual Studio, and do the following:
      1. From your driver project directory, open the Visual Studio Kernel PlugIn solution file — <project_dir>\msdev_<version>\xxx_diag.sln, where <project_dir> is your driver project directory (pci_diag for the sample code / the directory in which you selected to save the generated DriverWizard code), msdev_<version> is your target Visual Studio directory (e.g., msdev_2012), and xxx is the driver name (pci for the sample / the name you selected when generating the code with the wizard).

        [Note]
        • When using DriverWizard to generate code for MS Visual Studio, you can use the IDE to Invoke option to have the wizard automatically open the generated solution file in your selected IDE, after generating the code files.
        • To successfully build a Kernel PlugIn project using MS Visual Studio, the path to the project directory must not contain any spaces.
      2. Set the Kernel PlugIn project (kp_pci.vcproj / kp_xxx.vcproj) as the active project.
      3. Select the active configuration for your target platform: From the Build menu, choose Configuration Manager..., and select the desired configuration.
        [Note]
        To build the driver for multiple operating systems, select the lowest OS version that the driver must support. For example, to support Windows 7 and higher (32-bit), select either Win32 win7 free (release mode) or Win32 win7 checked (debug mode).
      4. Build your driver: Build the project from the Build menu or using the relevant shortcut key (e.g., F7 in Visual Studio 2008).
    • Using Windows GCC — Do the following from your selected Windows GCC development environment (MinGW/Cygwin):
      1. Change directory to your target Windows GCC Kernel PlugIn project directory — <project_dir>/<kernel_dir>/<CPU>/win_gcc, where <project_dir> is your driver project directory (pci_diag for the sample code / the directory in which you selected to save the generated DriverWizard code), <kernel_dir> is the project's Kernel PlugIn directory (kp_pci for the sample code / kermode for the generated code), and <CPU> is the target CPU architecture (x86 for x86 platforms, and amd64 for x64 platforms).

        For example:

        • When building a 32-bit version of the sample KP_PCI driver —
          $ cd WinDriver/samples/pci_diag/kp_pci/x86/win_gcc
        • When building a 64-bit wizard-generated Kernel PlugIn driver —
          $ cd <project_dir>/kermode/amd64/win_gcc
          — where <project_dir> signifies the path to your generated DriverWizard project directory (for example, ~/WinDriver/wizard/my_projects/my_kp).

      2. Edit the ddk_make.bat command in the Kernel PlugIn makefile, to set the desired build configuration — namely, the target OS and build mode (release — free, or debug — checked). By default, the WinDriver sample and wizard-generated makefiles set the target OS parameter to Windows 7 (win7 for 32-bit / x64 for 64-bit), and the build mode to release (free).
        [Note]
        • The ddk_make.bat utility is provided under the WinDriver\util directory, and should be automatically identified by Windows when running the build command. Run ddk_make.bat with no parameters to view the available options for this utility.
        • The selected build OS must match the CPU architecture of your WinDriver installation. For example, you cannot select the 64-bit win7_x64 OS flag when using a 32-bit WinDriver installation.
        • To build the driver for multiple operating systems, select the lowest OS version that the driver must support. For example, to support Windows 7 and higher, set the OS parameter to win7 (for 32-bit) or x64 (for 64-bit).
      3. Build the Kernel PlugIn driver using the make command.
  4. Build the user-mode application that drives the Kernel PlugIn driver (pci_diag.exe — sample / xxx_diag.exe — wizard-generated code):
    • Using MS Visual Studio —
      1. Set the user-mode project (pci_diag.vcproj — sample / xxx_diag.vcproj — wizard-generated code) as the active project.
      2. Build the application: Build the project from the Build menu or using the relevant shortcut key (e.g., F7 in Visual Studio 2008).
    • Using Windows GCC — Do the following from your selected Windows GCC development environment (MinGW/Cygwin):
      1. Change directory to your target Windows GCC application directory — <project_dir>/<CPU>/win_gcc, where <project_dir> is your driver project directory (pci_diag for the sample code / the directory in which you selected to save the generated DriverWizard code), and <CPU> is the target CPU architecture (x86 for x86 platforms, and amd64 for x64 platforms).

        For example:

        • When building a 32-bit version of the sample pci_diag application, which drives the sample KP_PCI driver —
          $ cd WinDriver/samples/pci_diag/x86/win_gcc
        • When building a 64-bit wizard-generated user-mode application that drivers a wizard-generated Kernel PlugIn driver —
          $ cd <project_dir>/amd64/win_gcc
          — where <project_dir> signifies the path to your generated DriverWizard project directory (for example, ~/WinDriver/wizard/my_projects/my_kp).

      2. Build the application using the make command.

12.7.2. Linux Kernel PlugIn Driver Compilation

To build your Kernel PlugIn driver and respective user-mode application on Linux, follow these steps:

  1. Open a shell terminal.
  2. Change directory to your Kernel PlugIn directory.

    For example:

    • When building the sample KP_PCI driver —
      $ cd WinDriver/samples/pci_diag/kp_pci
    • When building a wizard-generated Kernel PlugIn driver —
      $ cd <project_dir>/kermode/linux/
      — where <project_dir> signifies the path to your generated DriverWizard project directory (for example, ~/WinDriver/wizard/my_projects/my_kp).

  3. Generate the makefile using the configure script:
    $ ./configure
    [Note]
    If you have renamed the WinDriver kernel module [15.2], be sure to uncomment the following line in your Kernel PlugIn configuration script (by removing the pound sign — "#"), before executing the script, in order to build the driver with the -DWD_DRIVER_NAME_CHANGE flag (see Section 15.2.2, Step 3):
    # ADDITIONAL_FLAGS="-DWD_DRIVER_NAME_CHANGE"
    [Note]
    • The configuration script creates a makefile based on the running kernel. You may select to use another installed kernel source, by executing the script with the --with-kernel-source=<path> option, where <path> is the full path to the kernel source directory — e.g., /usr/src/linux.
    • If the Linux kernel version is 2.6.26 or higher, the configuration script generates makefiles that use kbuild to compile the kernel modules. You can force the use of kbuild on earlier versions of Linux, by executing the configuration script with the --enable-kbuild flag.
    [Note]
    For a full list of the configuration script options, use the --help option:
    ./configure --help
  4. Build the Kernel PlugIn module using the make command.
    This command creates a new LINUX.<kernel version>.<CPU> directory, which contains the created kp_xxx_module.o/.ko driver.
  5. Change directory to the directory that holds the makefile for the sample user-mode diagnostics application.

    For the KP_PCI sample driver —
    $ cd ../LINUX/

    For the generated DriverWizard Kernel PlugIn driver —
    $ cd ../../linux/

  6. Compile the sample diagnostics program using the make command.