Drivers must be installed before they can be
used—either by the developer to test and debug the driver or by the end
user who wants to use the related device. The procedures for installing
a driver are distinctly different from those that are used to install
applications. This section discusses how to create a WDF installation package and install it on a system.
There is a variety of ways to install drivers on a
user’s system. One common way is to simply attach the associated
hardware to the user’s system. The Plug and Play manager detects new
hardware and prompts the user to insert a disk that contains the driver package. The system then installs the driver. Users can also install drivers manually with the New Hardware application in Control Panel.
KMDF driver packages contain at least three files in addition to the driver binaries:
Driver packages can optionally contain files such as icons, property sheet providers, supporting DLLs, and so on. This section discusses the relatively simple driver package and test-installation procedure for Featured Toaster.
1. The WDF Co-Installer
A KMDF driver package must include the redistributable WDF co-install DLL. Its primary purpose is to install the KMDF run time. The WDF co-installer is located under the WinDDK\BuildNumber\Redis\Wdf
folder. There are six co-installers—a checked and a free build for each
supported process architecture (x86, Intel Itanium, and amd64). To
install the WDF co-installer, add the appropriate DLL to the driver package and add the appropriate directives to the INF file.
The WDF co-installer
version number must be greater than or equal to the KMDF version with
which the driver is compiled. The version number is embedded in the DLL’s name. For example, the co-installer for KMDF version 1.5 is named WdfCoInstaller01005.dll. The KMDF run-time version and the KMDF co-installer version that are specified in the project’s INF
must be identical. The build type of the co-installer must match that
of the Windows version on which the driver will be installed. You
cannot use the checked build of a co-installer to install a driver on a
free build of Windows, or vice versa.
2. The INF
The INF is the
core of the installation package. It is a text file that contains most
of the information that the system uses to install a driver, including
General information about the device such as the device’s manufacturer, installation class, and version number.
Names and locations of files on the distribution disk and where they should be installed on the user’s system.
Directives for creating or modifying registry entries for the driver or device.
Installation
directives for which drivers are to be installed, which binaries
contain the driver, and a list of drivers to be loaded on the device.
Directives for setting KMDF-specific configuration information.
The INF format is much like the earlier Windows .ini files. Each line contains a single entry, and there are two basic types of entries:
Section— Each INF contains a number of sections, indicated by square brackets—for example, [Version].
Directive—
Each section contains one or more directives. A directive is a
key-value pair and is used to specify various types of
installation-related data. For example, the Class=Mouse directive in the Version section specifies the mouse device class.
3. INFs for KMDF Drivers
Most of the contents of an INF for a KMDF driver are similar to those that are used for WDM drivers and aren’t discussed here. For further information, see the WDK document or examine the INF for Featured Toaster, wdffeatured.inf. The major difference is that INFs
for KMDF drivers must contain several additional sections that are
devoted to the KMDF co-installer. These sections instruct the system to
run the co-installer and provide it with necessary data. The
co-installer unpacks and installs a number of files that KMDF drivers
require, including the KMDF run-time library.
4. wdffeatured.inf
The following sample shows the WDF co-installer sections from the Featured Toaster sample’s INF file, wdffeatured.inf. It was produced from an INX file by the build described earlier.
[DestinationDirs]
ToasterClasInstallerCopyFiles = 11
[Toaster_Device.NT.CoInstallers]
AddReg=Toaster_Device_CoInstaller_AddReg
CopyFiles=Toaster_Device_CoInstaller_CopyFiles
[Toaster_Device_CoInstaller_AddReg]
HKR, ,CoInstallers32, 0x00010000,
"WdfCoinstaller01000.dll,WdfCoInstaller"
[Toaster_Device_CoInstaller_CopyFiles]
WdfCoinstaller01000.dll
[SourceDisksFiles]
WdfCoinstaller01000.dll=1
[Toaster_Device.NT.Wdf]
KmdfService = wdffeatured, wdffeatured_wdfsect
[wdffeatured_wdfsect]
KmdfLibraryVersion = 1.1
To modify this code for your driver, replace the text that is specific to Featured Toaster
with custom text of your choosing. The following example is a generic
version of the co-installer section for a driver that is named MyDevice:
[DestinationDirs]
MyDeviceClassInstallerCopyFiles = 11
[MyDevice.NT.CoInstallers]
AddReg=MyDevice_CoInstaller_AddReg
CopyFiles= MyDeviceClassInstallerCopyFiles
[MyDevice_CoInstaller_AddReg]
HKR, ,CoInstallers32,0x00010000,
"WdfCoinstaller01000.dll,WdfCoInstaller"
[MyDevice_CoInstaller_CopyFiles]
wdfCoinstller01000.dll
[SourceDisksFiles]
wdfCoinstaller01000.dll=1 ;
[MyDevice.NT.Wdf]
KmdfService = MyDevice, MyDevice_wdfsect
[MyDevice_wdfsect]
KmdfLibraryVersion = 1.0
