Technical Document #132

This document outlines the basic steps for installing a driver developed with version 8.1.x or newer of WinDriver on a target Windows PC. Detailed driver distribution instructions can be found in the WinDriver User's Manual for your WinDriver version.

This document includes

• Documentation Notes
• Installation Notes
• Installation Steps

Documentation Notes:

• All OS references in this document are applicable only to WinDriver versions that officially support these operating systems (refer to Technical Document #4 for the list of operating systems supported by the latest WinDriver version).

  For example, references to Windows 98/Me (and the related wdreg16.exe utility) are applicable only to version 9.2.0 and below of WinDriver.



• The windrvr6.sys, windrvr6.inf and wd<version>.cat files, mentioned in this document, can be found under the WinDriver\redist directory on the development PC. wdreg.exe / wdreg_gui.exe / wdreg16.exe and difxapi.dll (v8.1.1+) can be found under the WinDriver\util directory. (The source code of the wdreg utility is found under the WinDriver\samples\wdreg directory).


• Beginning with version 8.0.0 of WinDriver you can rename the WinDriver driver module (windrvr6.sys) and the related INF file (windrvr6.inf). You can also submit the driver for WHQL certification or have it Authenticode signed yourself, using your own WinDriver catalog file (xxx.cat), as explained in the WinDriver User's Manual. If you have selected to rename any of the provided WinDriver files, replace the references to these files in the present document with the names of your new files.


• The wdreg.exe and wdreg_gui.exe utilities provide the same functionality. The difference is in the way the installation messages are displayed — graphical messages (wdreg_gui.exe) or console messages (wdreg.exe). You can therefore replace any reference to wdreg.exe in the following instructions with wdreg_gui.exe.
  When installing windrvr6.sys on Windows 98/Me, you should use the wdreg16.exe utility.


• Beginning with version 8.1.1 of WinDriver the wdreg utility is dependent on the difxapi.dll DLL.

Installation Notes:

• You must have administrative privileges in order to install drivers on Windows.


• When distributing your driver, take care not to overwrite a newer version of the driver file (windrvr6.sys) with an older version of this file.
  The provided windrvr6.inf file uses the COPYFLG_NO_VERSION_DIALOG directive, which is designed to avoid overwriting a file in the destination directory with the source file if the existing file is newer than the source file. There is also a similar COPYFLG_OVERWRITE_OLDER_ONLY INF directive that is designed to ensure that the source file is copied to the destination directory only if the destination file is superseded by a newer version. Note, however, that both of these INF directives are irrelevant to digitally signed drivers. As explained in the Microsoft INF CopyFiles Directive documentation, if a driver package is digitally signed, Windows installs the package as a whole and does not selectively omit files in the package based on other versions already present on the computer. The windrvr6.sys driver in the newer WinDriver versions is digitally signed with an Authenticode signature (refer to the WinDriver User's Manual for more information on driver signature and certification).


• If you wish to distribute drivers for both 32-bit and 64-bit target platforms, you must prepare a separate driver installation package for each platform.


• When upgrading the driver from a previous version of WinDriver that also uses the windrvr6.sys driver module (v6.0.0 and above), make sure that there are no open handles to the old WinDriver service (windrvr6.sys or your renamed driver), and that there are no connected and enabled Plug-and-Play devices that are registered with this service. This includes closing any applications that may be using the driver; uninstalling your old Kernel PlugIn driver (if you had created such a driver):
  \> wdreg -name OLD_KP uninstall
  and either disabling, uninstalling, or physically disconnecting any device that is registered to work with the WinDriver service.


• On Windows 2000, remove any INF file(s) previously installed for your Plug-and-Play device (such as files created with an earlier version of WinDriver) from the %windir%\inf directory, before installing the new INF file that you created for the device. This will prevent Windows from automatically detecting and installing an obsolete file. You can search the INF directory for the device's vendor ID and device/product ID to locate the file(s) associated with the device (see Technical Document 49 for additional information).

Installation Steps:

NOTE: For Windows 98/Me, replace the references to wdreg.exe below with wdreg16.exe.

1. Copy windrvr6.sys, windrvr6.inf and wd<version>.cat to the same directory.

   NOTE:
   

   • If you select to copy wd<version>.cat to a different location you will need to modify the CatalogFile entry in the windrvr6.inf file to point to the location of the catalog file.
   • You can also select not to distribute the wd<version>.cat catalog file, in which case you need to remove or comment-out the CatalogFile line in the windrvr6.inf file. However, note that if you do so the installation will not utilize the driver's Authenticode digital signature (see the WinDriver User's Manual for more information).



2. Use the utility wdreg.exe to install WinDriver's kernel module on the target computer:
   \> wdreg -inf <path to windrvr6.inf> install

   NOTE: Remember that wdreg requires the difxapi.dll DLL (v8.1.1+).

   TIP: If you copy wdreg.exe and difxapi.dll to the same directory as windrvr6.sys and windrvr6.inf, you can simply run the following command from your installation directory in order to install the driver:
   install_dir:] wdreg -inf windrvr6.inf install

3. If you have created a Kernel PlugIn driver (e.g., my_kp.sys), copy this driver to Windows drivers directory — %windir%\system32\drivers — and install it using the wdreg.exe utility:
   \> wdreg -name MY_KP install
   

   NOTE: The driver name is indicated without the *.sys extension.



4. On Windows 98/Me, reboot the PC to complete the driver installation.


5. For Plug-and-Play devices (PCI/USB): install the device INF file, which registers your device to work with the windrvr6.sys service (normally this file is created using WinDriver's DriverWizard utility).

   On Windows 2000 and higher, you can use the wdreg.exe utility with the install command to automatically install the INF file:
   \> wdreg -inf <path to device.inf> install
   You can also use the preinstall wdreg.exe command to pre-install an INF file for a device that is not currently connected to the PC:
   \> wdreg -inf <path to device.inf> preinstall

   On Windows 98/Me, install the device INF file manually, using Windows' Update Driver wizard (from the Device Manager) or New Hardware Wizard, as explained in the instructions that will be displayed when generating the file with DriverWizard, and in the WinDriver User's Manual for the relevant WinDriver version. Alternatively, copy the INF file to Windows' INF directory
   (%windir%\inf) and reboot to let Windows locate and install the file.



6. If your project uses the wdapi<version>.lib library (for example wdapi900.lib) — as is the case for the sample and generated DriverWizard projects — you need to distribute the wdapi DLL:
   
   
   • When distributing 32-bit applications/DLLs to 32-bit targets OR when distributing 64-bit applications/DLLs to 64-bit targets: Copy WinDriver\redist\wdapi<version>.dll (e.g., wdapi900.dll) to the target's %windir%\system32 directory.

     NOTE: If you attempt to copy the 64-bit DLL to the
     %windir%\system32 directory using a 32-bit installation program, you may find that the DLL file is actually copied to the 32-bit %windir%\sysWOW64 directory. The reason for this is that Windows x64 platforms translate references to 64-bit directories from 32-bit commands into references to 32-bit directories. You can avoid the problem by using 64-bit commands to perform the necessary installation steps from your 32-bit installation program. The system64.exe program, provided in the WinDriver\redist directory of the Windows x64 WinDriver distributions, enables you to do this.

   
   
   • When distributing 32-bit applications to 64-bit targets: Rename the file WinDriver\redist\wdapi<version>_32.dll to wdapi<version>.dll (for example, rename wdapi900_32.dll to wdapi900.dll) and copy the renamed file to the target's %windir%\sysWOW64 directory.


7. Copy your driver application/DLL to the target and run it!