15.2 Renaming the WinDriver Kernel Driver

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

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

A renamed WinDriver kernel driver can be installed on the same PC as the original windrvr6.sys/.o/.ko kernel module. You can also install multiple renamed WinDriver drivers on the same PC, simultaneously.

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

	TIP
	Try to give your driver a unique name in order to avoid a potenial conflict with other drivers on the target PCs on which your driver will be installed.

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

15.2.1 Windows Driver Rename

Rename the Windows WinDriver kernel driver - windrvr6.sys - using either of the two alternative methods described in the following sections.

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

	TIP
	It is recommended to use the first method, described in setion 15.2.1.1, since it automates most of the work for you.

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

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

NOTES

References to the WinDriver$\backslash$redist directory in this section can be replaced with WinDriver$\backslash$redist_win98_compat. The redist$\backslash$ directory contains a digitally signed, WHQL-compliant, windrvr6.sys driver and related files. The redist_win98_compat$\backslash$ directory contains an unsigned non-WHQL compliant version of the driver for Windows 98/Me and higher. 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 15.3. For guidelines for signing and certifying your renamed driver, refer to section 15.3.2.

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

15.2.1.1 Rename the Windows Driver Using DriverWizard

To rename your Windows WinDriver kernel driver using DriverWizard (recommended), follow the steps in this section.

References to xxx in this section should be replaced with the name of your generated DriverWizard driver project.

1. Use the DriverWizard utility to generate driver code for your hardware on Windows [4.2(6)], using your preferred driver name (xxx) as the name of the generated driver project.

   The generated project directory (xxx$\backslash$) will include an xxx_installation$\backslash$ directory with the following files and directories:

   • redist$\backslash$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$\backslash$ 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.

     • wdapi901.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$\backslash$redist$\backslash$ directory as the main installation directory for your driver, instead of the original WinDriver$\backslash$redist directory.

   • sys$\backslash$ 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 Development Kit (DDK).

     To modify the properties of your xxx.sys driver file:

     1. Verify that the Windows DDK is installed on your development PC, or elsewhere on its network, and set the BASEDIR environment variable to point to your DDK installation directory.

     2. Modify the xxx.rc resources file in the generated sys$\backslash$ 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$\backslash$util directory, and should be automatically identified by Windows when runnning the installation command.

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

2. Verify that your 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 projects/makefiles already set this preprocessor flag by default.

4. Install your new driver by following the instructions in section 14.2 of the manual, using the modified files from the generated xxx_installation$\backslash$ directory instead of the installation files from the original WinDriver distribution.

15.2.1.2 Manually Rename the Windows Driver

To manually rename the Windows WinDriver kernel driver, follow these steps:

1. Create a copy of the WinDriver$\backslash$redist directory and modify the files in this directory as follows:
   • Rename the windrvr6.sys and windrvr6.inf files, replacing windrvr6 in the file names with your selected driver name, e.g. my_driver.
     Note that you must leave the *.sys / *.inf file extension.

   • Modify your copy of the windrvr6.inf file:
     1. Replace all windrvr6 occurrences in the file with the name of your new driver (e.g. my_driver).

     2. Change the name of the driver service for the AddService key, under the [DriverInstall.NT.Services] section in the INF file, to your selected driver service name (e.g. MyDriver).

2. Replace any occurrences of windrvr6 in your device-INF file, which registers your device with the selected driver, with the name of your new driver module (e.g. my_driver). You can also make additional modifications to this file, if you wish, such as changing the manufacturer or driver provider strings.

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

   NOTE

   DriverWizard automatically generates a device-INF for your device under the generated driver project directory. The file's name is derived from the name selected for your driver project (e.g. <my_driver>.inf). You can also generate the device INF file yourself by selecting the INF generation option from the DriverWizard's Select Your Device screen, which is displayed when selecting to create a new host driver project. When using this method you can set your own INF strings - such as the manufacturer name, device name, and device class - directly from the wizard, and let DriverWizard generate a device-INF file that uses your definitions, as explained in section 4.2(3). Regardless of the method used to create your device-INF file, in order to use your new driver module you must change the references to windrvr6 in this file to your new driver name, as explained above.

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

3. Verify that your 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.

4. 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 projects/makefiles already set this preprocessor flag by default.

5. Install your new driver by following the instructions in section 14.2 of the manual, using the modified files from your new installation directory instead of the installation files from the original WinDriver distribution.

15.2.2 Linux Driver Rename

Rename the Linux WinDriver kernel driver - windrvr6.o/.ko - using either of the two alternative methods described in the following sections.

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

	TIP
	It is recommended to use the first method, described in setion 15.2.2.1, since it automates most of the work for you.

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

15.2.2.1 Rename the Linux Driver Using DriverWizard

To rename your Linux WinDriver kernel driver using DriverWizard (recommended), follow the steps in this section.

References to xxx in this section should be replaced with the name of your generated DriverWizard driver project.

1. Use the DriverWizard utility to generate driver code for your hardware on Linux [4.2(6)], 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 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 projects/makefiles already set this preprocessor flag by default.

4. Install your new driver by following the instructions in section 14.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 by following the instructions in section 14.4.1, using the files from your new installation directory.

15.2.2.2 Manually Rename the Linux Driver

To manually rename the Linux WinDriver kernel driver, follow these steps:

1. Create a new installation directory and copy the redist/, lib/ and include/ directories from the original WinDriver distribution to this new directory.

2. Make the following changes to the files in your copy of the redist/ directory:
   1. Replace any occurrences of the %DRIVER_NAME% string in the linux_wrappers.c file with your new driver name (e.g. my_driver).

   2. Replace the configure script in the new directory with a copy of the WinDriver/wizard/.windrvr6_configure.src file; rename this file to configure; and replace the %DRIVER_NAME_CHANGE_FLAG% string in this file with -DWD_DRIVER_NAME_CHANGE.

   Note: The copies of the lib/ and include/ directories should not be modified. These copies are created since the supported WinDriver Linux kernel driver build method relies on the existence of these directories directly under the same parent directory as the redist/ directory.

3. Verify that your 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.

4. 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 projects/makefiles already set this preprocessor flag by default.

5. Install your new driver by following the instructions in section 14.4 of the manual, using the modified files from your new installation directory instead of the installation files from the original WinDriver distribution. As part of the installation, build your new kernel driver module by following the instructions in section 14.4.1, using the files from your new installation directory.

15.2.3 Solaris Driver Rename

Rename the Solaris WinDriver kernel driver - windrvr6 - using either of the two alternative methods described in the following sections.

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

	TIP
	It is recommended to use the first method, described in setion 15.2.3.1, since it automates most of the work for you.

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

15.2.3.1 Rename the Solaris Driver Using DriverWizard

To rename your Solaris WinDriver kernel driver using DriverWizard (recommended), follow the steps in this section.

References to xxx in this section should be replaced with the name of your generated DriverWizard driver project.

1. Use the DriverWizard utility to generate driver code for your hardware on Solaris [4.2(6)], 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 provides modified versions of the files from the original WinDriver/redist directory - i.e. the windrvr6 kernel module and windrvr6.conf installation file - which have been modified to use your new driver name (xxx).

   • lib/ directory: This directory is simply a copy of the lib/ directory from the original WinDriver distribution. It is copied here since the driver's installation method relies on the existence of this directory directly under the same parent directory as the redist/ directory.

   • install_xxx and remove_xxx scripts: Copies of the install_windrvr and rename_windrvr files from the original WinDriver/ directory, which have been modified to refer to your new driver.

2. Verify that your 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 projects/makefiles already set this preprocessor flag by default.

4. Install your new driver by following the instructions in section 14.5 of the manual, using the modified files from the generated xxx_installation/ directory instead of the installation files from the original WinDriver distribution.

15.2.3.2 Manually Rename the Solaris Driver

To manually rename the Solaris WinDriver kernel driver, follow these steps:

1. Create a new installation directory and copy the redist/ and lib/ directories, and the install_windrvr and remove_windrvr files, from the original WinDriver distribution to your new directory.

2. Modify your copies of the redist/ directory files and the install_windrvr and remove_windrvr files by replacing all occurrences of windrvr6 or windrvr, both in the file names and in the files themselves, with your selected driver name (e.g. my_driver).

   Note: The copy of the lib/ directory should not be modified. This copy is created since the the driver's installation method relies on the existence of this directory directly under the same parent directory as the redist/ directory.

3. Verify that your 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.

4. 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 projects/makefiles already set this preprocessor flag by default.

5. Install your new driver by following the instructions in section 14.5 of the manual, using the modified files from your new installation directory instead of the installation files from the original WinDriver distribution.