11.2 Windows Driver Distribution

11.2 Windows Driver Distribution
	Chapter 11 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 12.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 12.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 wd1011.cat catalog file with the names of your new files (see information in sections 12.2.1 and 12.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,and installing the specific INF file for your device .

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

11.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 in the WinDriver package.
windrvr6.inf.
Get this file from the WinDriver\redist directory in the WinDriver package.
wd1011.cat.
Get this file from the WinDriver\redist directory in the WinDriver package.
wdapi1011.dll (for distribution of 32-bit binaries to 32-bit target platforms or for distribution of 64-bit binaries to 64-bit platforms) or wdapi1011_32.dll (for distribution of 32-bit binaries to 64-bit platforms [A.2].
Get this file from the WinDriver\redist directory in the WinDriver package.
difxapi.dll (required by the wdreg.exe utility [10.2.2]).
Get this file from the WinDriver\util directory in the WinDriver package.
An INF file for your device .
You can generate this file with the DriverWizard, as explained in section 5.2.

11.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 12.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 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 wd1011.cat to the same directory.

wd1011.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=wd1011.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 12.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 10.


	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.

Install wdapi1011.dll:
If your hardware control application/DLL uses wdapi1011.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 wdapi1011_32.dll in your distribution package to wdapi1011.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 wdapi1011.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!


Chapter 11 Distributing Your Driver		11.3 Windows CE Driver Distribution