12.2. Renaming the WinDriver Kernel Driver

The WinDriver APIs are implemented within the WinDriver kernel driver module (windrvr6.sys/.dll/.o/.ko — depending on the OS), which provides the main driver functionality and enables you to code your specific driver logic from the user mode [1.5].

On Windows and Linux you can change the name of the WinDriver kernel module to your preferred driver name, and then distribute the renamed driver instead of default kernel module — windrvr6.sys/.o/.ko. The following sections explain how to rename the driver for each of the supported operating systems.

[Note]
A renamed WinDriver kernel driver can be installed on the same machine as the original kernel module.
You can also install multiple renamed WinDriver drivers on the same machine, simultaneously.
[Tip]
Try to give your driver a unique name in order to avoid a potenial conflict with other drivers on the target machine on which your driver will be installed.

12.2.1. Windows Driver Renaming

DriverWizard automates most of the work of renaming the Windows WinDriver kernel driver — windrvr6.sys.

[Note]
  • When renaming the driver, the CPU architecture (32-/64-bit) of the development platform and its WinDriver installation, should match the target platform.
  • Renaming the signed windrvr6.sys driver nullifies its signature. In such cases you can select either to sign your new driver, or to distribute an unsigned driver. For more information on driver signing and certification, refer to Section 12.3. For guidelines for signing and certifying your renamed driver, refer to Section 12.3.2.
[Note]
References to xxx in this section should be replaced with the name of your generated DriverWizard driver project.

To rename your Windows WinDriver kernel driver, follow these steps:

  1. Use the DriverWizard utility to generate driver code for your hardware on Windows (refer to Section 5.2, Step 7), using your preferred driver name (xxx) as the name of the generated driver project. The generated project directory (xxx) will include an xxx_installation directory with the following files and directories:
    • redist directory:
      • xxx.sys — Your new driver, which is actually a renamed copy of the windrvr6.sys driver. Note: The properties of the generated driver file (such as the file's version, company name, etc.) are identical to the properties of the original windrvr6.sys driver. You can rebuild the driver with new properties using the files from the generated xxx_installation sys directory, as explained below.
      • xxx_driver.inf — A modified version of the windrvr6.inf file, which will be used to install your new xxx.sys driver.
        You can make additional modifications to this file, if you wish — namely, changing the string definitions and/or comments in the file.
      • xxx_device.inf — A modified version of the standard generated DriverWizard INF file for your device, which registers your device with your driver (xxx.sys).
        You can make additional modifications to this file, if you wish, such as changing the manufacturer or driver provider strings.
      • wdapi1100.dll — A copy of the WinDriver API DLL. The DLL is copied here in order to simplify the driver distribution, allowing you to use the generated xxx\redist directory as the main installation directory for your driver, instead of the original WinDriver\redist directory.
      • wdreg.exe, wdreg_gui.exe, and difxapi.dll — Copies of the CUI and GUI versions of the wdreg WinDriver driver installation utility, and the Driver Install Frameworks API (DIFxAPI) DLL required by this utility [10.2.2], (respectively). These files are copied from the WinDriver\util directory, to simplify the installation of the renamed driver.
      • xxx_install.bat — An installation script that executes the wdreg commands for installing the xxx_driver.inf and xxx_device.inf files. This script is designed to simplify the installation of the renamed xxx_driver.sys driver, and the registration of your device with this driver.
    • sys directory: This directory contains files for advanced users, who wish to change the properties of their driver file. Note: Changing the file's properties requires rebuilding of the driver module using the Windows Driver Kit (WDK).
      To modify the properties of your xxx.sys driver file:

      1. Verify that the WDK is installed on your development PC, or elsewhere on its network, and set the BASEDIR environment variable to point to the WDK installation directory.
      2. Modify the xxx.rc resources file in the generated sys directory in order to set different driver file properties.
      3. Rebuild the driver by running the following command:
        ddk_make <OS> <build mode (free/checked)>
        For example, to build a release version of the driver for Windows XP:
        ddk_make winxp 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.

      After rebuilding the xxx.sys driver, copy the new driver file to the generated xxx_installation\redist directory.

  2. Verify that your user-mode application calls the WD_DriverName() function [B.1] with your new driver name before calling any other WinDriver function.
    Note that the sample and generated DriverWizard WinDriver applications already include a call to this function, but with the default driver name (windrvr6), so all you need to do is replace the driver name that is passed to the function in the code with your new driver name.
  3. Verify that your user-mode driver project is built with the WD_DRIVER_NAME_CHANGE preprocessor flag (e.g., -DWD_DRIVER_NAME_CHANGE).
    Note: The sample and generated DriverWizard WinDriver kernel projects/makefiles already set this preprocessor flag by default.
  4. Install your new driver by following the instructions in Section 11.2 of the manual, using the modified files from the generated xxx_installation directory instead of the installation files from the original WinDriver distribution. Note that you can use the generated xxx_install.bat installation script (see Step 1) to simplify the installation.

12.2.2. Linux Driver Renaming

DriverWizard automates most of the work of renaming the Linux WinDriver kernel driver — windrvr6.o/.ko.

[Note]
When renaming windrvr6.o/.ko, the windrvr6_usb.o/.ko WinDriver USB Linux GPL driver is automatically renamed to <new driver name>_usb.o/.ko.
[Note]
References to xxx in this section should be replaced with the name of your generated DriverWizard driver project.

To rename your Linux WinDriver kernel driver, follow these steps:

  1. Use the DriverWizard utility to generate driver code for your hardware on Linux (refer to Section 5.2, Step 7), using your preferred driver name (xxx) as the name of the generated driver project. The generated project directory (xxx) will include an xxx_installation directory with the following files and directories:
    • redist directory: This directory contains copies of the files from the original WinDriver/redist installation directory, but with the required modifications for building your xxx.o/.ko driver instead of windrvr6.o/.ko.
    • lib and include directories: Copies of the library and include directories from the original WinDriver distribution. These copies are created since the supported Linux WinDriver kernel driver build method relies on the existence of these directories directly under the same parent directory as the redist directory.
  2. Verify that your user-mode application calls the WD_DriverName() function [B.1] with your new driver name before calling any other WinDriver function.
    Note that the sample and generated DriverWizard WinDriver applications already include a call to this function, but with the default driver name (windrvr6), so all you need to do is replace the driver name that is passed to the function in the code with your new driver name.
  3. Verify that your user-mode driver project is built with the WD_DRIVER_NAME_CHANGE preprocessor flag (-DWD_DRIVER_NAME_CHANGE).
    Note: The sample and generated DriverWizard WinDriver kernel projects/makefiles already set this preprocessor flag by default.
  4. Install your new driver by following the instructions in Section 11.4 of the manual, using the modified files from the generated xxx_installation directory instead of the installation files from the original WinDriver distribution.
    As part of the installation, build your new kernel driver module(s) by following the instructions in Section 11.4, using the files from your new installation directory.