14.2 Windows Driver Distribution

14.2 Windows Driver Distribution
	Chapter 14. Distributing Your Driver

All references to wdreg in this section can be replaced with wdreg_gui, which offers the same functionality as wdreg but displays GUI messages instead of console-mode messages.
If you have renamed the WinDriver kernel module (windrvr6.sys), as explained in section 15.2, replace the relevant windrvr6 references with the name of your driver, and replace references to the WinDriver\redist directory with the path to the directory that contains your modified installation files. For example, when using the generated DriverWizard renamed driver files for your driver project, as explained in section 15.2.1, you can replace references to the WinDriver\redist directory with references to the generated xxx_installation\redist directory (where xxx is the name of your generated driver project).
If you have created new INF and/or catalog files for your driver, replace the references to the original WinDriver INF files and/or to the wd1021.cat catalog file with the names of your new files (see information in sections 15.2.1 and 15.3.2 regarding renaming of the original files).
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. The required files for each package are located within the WinDriver installation directory for the respective platform.

Distributing the driver you created is a multi-step process. First, create a distribution package that includes all the files required for the installation of the driver on the target computer. Second, install the driver on the target machine. This involves installing windrvr6.sys and windrvr6.inf, installing the specific INF file for your device (for Plug-and-Play hardware – PCI/PCI Express/PCMCIA), and installing your Kernel PlugIn driver (if you have created one).

Finally, you need to install and execute the hardware control application that you developed with WinDriver. These steps can be performed using wdreg utility.


	This section refers to distribution of .sys files. Starting from WinDriver version 6.21 .vxd drivers are no longer supported.

14.2.1 Preparing the Distribution Package

Your distribution package should include the following files:

Your hardware control application/DLL.
windrvr6.sys.
Get this file from the WinDriver\redist directory of the WinDriver package.
windrvr6.inf.
Get this file from the WinDriver\redist directory of the WinDriver package.
wd1021.cat.
Get this file from the WinDriver\redist directory of the WinDriver package.
wdapi1021.dll (for distribution of 32-bit binaries to 32-bit target platforms or for distribution of 64-bit binaries to 64-bit platforms) or wdapi1021_32.dll (for distribution of 32-bit binaries to 64-bit platforms [A.2].
Get this file from the WinDriver\redist directory of the WinDriver package.
difxapi.dll (required by the wdreg.exe utility [13.2.2]).
Get this file from the WinDriver\util directory of the WinDriver package.
An INF file for your device (required for Plug-and-Play devices, such as PCI and PCMCIA) .
You can generate this file with DriverWizard, as explained in section 4.2.
If you have created a Kernel PlugIn driver [11]: Your Kernel PlugIn driver – <KP driver name>.sys.

14.2.2 Installing Your Driver on the Target Computer


	Driver installation on Windows requires administrator privileges.

Follow the instructions below in the order specified to properly install your driver on the target computer:

Preliminary Steps:
- To successfully install your driver, make sure that there are no open handles to the WinDriver service (windrvr6.sys or your renamed driver (refer to section 15.2), and that there are no connected and enabled Plug-and-Play devices that are registered with this service. This is relevant, for example, when upgrading the version of the driver (for WinDriver v6.0.0 and above; earlier versions used a different module name). If the service is being used, attempts to install the new driver using wdreg will fail.
  You can disable or uninstall connected devices from the Device Manager (Properties | Disable/Uninstall) or using wdreg, or otherwise physically disconnect the device(s) from the PC.
- 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.

Install WinDriver's kernel module:

Copy windrvr6.sys, windrvr6.inf, and wd1021.cat to the same directory.

wd1021.cat contains the driver's Authenticode digital signature. To maintain the signature's validity this file must be found in the same installation directory as the windrvr6.inf file. If you select to distribute the catalog and INF files in different directories, or make any changes to these files or to any other files referred to by the catalog file (such as windrvr6.sys), you will need to do either of the following:

Create a new catalog file and re-sign the driver using this file.
Comment-out or remove the following line in the windrvr6.inf file:
CatalogFile=wd1021.cat
and do not include the catalog file in your driver distribution. However, note that this option invalidates the driver's digital signature.

For more information regarding driver digital signing and certification and the signing of your WinDriver-based driver, refer to section 15.3 of the manual.

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

For example, if windrvr6.inf and windrvr6.sys are in the d:\MyDevice directory on the target computer, the command should be:
wdreg -inf d:\MyDevice\windrvr6.inf install

You can find the executable of wdreg in the WinDriver package under the WinDriver\util directory. For a general description of this utility and its usage, please refer to Chapter 13.


	wdreg is dependent on the difxapi.dll DLL. wdreg is an interactive utility. If it fails, it will display a message instructing the user how to overcome the problem. In some cases the user may be asked to reboot the computer.

When distributing your driver, take care not to overwrite a newer version of windrvr6.sys with an older version of the file in Windows drivers directory (%windir%\system32\drivers). You should configure your installation program (if you are using one) or your INF file so that the installer automatically compares the time stamp on these two files and does not overwrite a newer version with an older one.

Install the INF file for your device (registering your Plug-and-Play device with windrvr6.sys):

Run the utility wdreg with the install command to automatically install the INF file and update Windows Device Manager:
wdreg -inf <path to your INF file> install

You can also use the wdreg utility's preinstall command to pre-install an INF file for a device that is not currently connected to the PC:
wdreg -inf <path to your INF file> preinstall

On Windows 2000, if another INF file was previously installed for the device, which registered the device to work with the Plug-and-Play driver used in earlier versions of WinDriver remove any INF file(s) for the device from the %windir%\inf directory before installing the new INF file that you created. 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.
If the installation fails with an ERROR_FILE_NOT_FOUND error, inspect the Windows registry to see if the RunOnce key exists in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion. This registry key is required by Windows Plug-and-Play in order to properly install drivers using INF files. If the RunOnce key is missing, create it; then try installing the INF file again.

Install your Kernel PlugIn driver: If you have created a Kernel PlugIn driver, install it by following the instructions in section 14.2.3.

Install wdapi1021.dll:
If your hardware control application/DLL uses wdapi1021.dll (as is the case for the sample and generated DriverWizard WinDriver projects), copy this DLL to the target's %windir%\system32 directory.
If you are distributing a 32-bit application/DLL to a target 64-bit platform [A.2], rename wdapi1021_32.dll in your distribution package to wdapi1021.dll, and copy the renamed file to the target's %windir%\sysWOW64 directory.

If you attempt to write a 32-bit installation program that installs a 64-bit program, and therefore copies the 64-bit wdapi1021.dll DLL to the %windir%\system32 directory, you may find that the 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.

Install your hardware control application/DLL: Copy your hardware control application/DLL to the target and run it!

14.2.3 Installing Your Kernel PlugIn on the Target Computer


	Driver installation on Windows requires administrator privileges.

If you have created a Kernel PlugIn driver, follow the additional instructions below:

Copy your Kernel PlugIn driver (<KP driver name>.sys) to Windows drivers directory on the target computer (%windir%\system32\drivers).
Use the utility wdreg to add your Kernel PlugIn driver to the list of device drivers Windows loads on boot. Use the following installation command:
To install a SYS Kernel PlugIn Driver:
wdreg -name <Your driver name, without the *.sys extension> install
You can find the executable of wdreg in the WinDriver package under the WinDriver\util directory. For a general description of this utility and its usage, please refer to Chapter 13 (see specifically section 13.2.4 for Kernel PlugIn installation).


Chapter 14. Distributing Your Driver		14.3 Windows CE Driver Distribution