WDF Driver Installation Considerations

The basics of preparing and installing a WDF driver package are essentially the same as for other Windows driver models. The primary difference is that WDF drivers depend on a particular version of the framework library. The currently installed version of the framework on the target system might be out of date or, on systems earlier than Windows Vista, not present at all.

WDF driver installation procedures must therefore ensure that the system has the appropriate version of the framework. This section discusses WDF versioning and the WDF co-installers that ensure that the correct version of the framework is installed.

WDF Versioning and Driver Installation

WDF versioning allows drivers that are bound to different major versions of UMDF or KMDF to be installed and run side by side on the same system. WDF drivers bind to the major version of the framework for which they are compiled and ignore any other major version that might be present. This feature ensures that a driver is always bound to the major version of the framework that it was designed for and tested against.

Each major version can have multiple minor versions. In addition to bug fixes, each new minor version can contain additional DDI methods or features. However, to ensure backward compatibility, existing DDI methods or features do not change when a new minor version is installed. This means that a WDF driver should run properly on any minor version of the appropriate major version, as long as the minor version on the computer is greater than or equal to the minor version for which the driver was originally compiled.

 Note-KMDF  The KMDF co-installer does not put an entry in the Control Panel Programs application, which was called Add or Remove Programs on earlier versions of Windows. This ensures that a user does not mistakenly remove the framework.

Minor Version Updates

Two minor versions of the same major version cannot co-exist on the same system. When a new minor version is installed, the new version replaces the old version. Any drivers that were using the old minor version bind to the new version.

Minor version updates can include new features and additions to the DDI. However, new minor versions are guaranteed to be completely backward compatible, so WDF drivers are not required to do anything to accommodate the installation of a new minor version. However, users might be required to reboot.

 KMDF  With KMDF, if an older minor version is already loaded when the newer version is installed, users must reboot.

 UMDF  With UMDF, if the older minor version is already loaded when the newer version is installed, the co-installer attempts to gracefully shut down all device stacks that are bound to the older minor version. If all affected device stacks support a query-remove/remove request, the co-installer can put the stacks in a Stopped state and upgrade the version without a reboot. If one or more of the affected device stacks do not support query-remove/remove or if an application has an open handle to one of the devices, users must reboot.

Regardless of whether a reboot is required, when the drivers are reloaded, all WDF drivers that were bound to the old minor version bind to the new one.

Major Version Updates

When a new major version of WDF is installed, existing drivers continue to bind to the same version as before. However, you should update your drivers for the latest major version of WDF because it includes all of the latest bug fixes and features. Note that a new major version of the framework is not guaranteed to be backward compatible with previous major versions. Always perform regression testing on your driver to be certain that it works correctly with a new major version.

Framework Distribution

Microsoft distributes the WDF frameworks in several ways:

• Windows Vista and later versions of Window include native versions of KMDF and UMDF.

• The WDK provides redistributable WDF co-installers for vendors to include in their driver packages.

  The co-installers install the framework on the target system during device installation if the system does not already have the latest version.

• A new major version of the framework is typically installed when a user installs a driver that requires that version, but it might also be distributed with Windows service packs.

  Windows Update automatically delivers a new minor version of the framework to users' systems if the update is necessary to fix a critical security issue. Otherwise, a new minor version is installed only when a user installs a driver that requires that version.

 Tip  See "Framework Library Versions" in the WDK-online at http://go.microsoft.com/fwlink/?LinkId=79355.

How Drivers Bind to the Framework

WDF drivers bind dynamically with the framework at load time. This section describes how the binding occurs for both KMDF and UMDF drivers.

KMDF Drivers

 KMDF  At build time, KMDF drivers link statically with WdfDriverEntry.lib. This library contains information about the KMDF version in a static data structure that becomes part of the driver binary. An internal function in this library wraps the driver's DriverEntry routine. When the driver is loaded, the internal function becomes the driver's entry point. At load time, the following occurs:

1. The internal function calls the KMDF loader and passes the version number of the KMDF framework library with which to bind.

2. The loader determines whether the specified major version of the framework library is already loaded. If not, the loader starts the KMDF runtime.

3. If the runtime starts successfully, the loader adds the driver as a client of the runtime and returns the relevant information to the internal function.

   If the driver requires a version of the runtime library that is newer than the one already loaded, the loader fails and logs the failed attempt in the system event log.

Boot-start drivers are those drivers that are installed during the boot process. KMDF boot-start drivers have a somewhat different loading scenario than described above because the KMDF runtime must be loaded before the driver is loaded. At installation, the co-installer reads the INF or the registry to determine whether the driver is a boot-start driver. If so, the co-installer:

• Changes the start type of the KMDF runtime so that the Windows loader starts the KMDF runtime at system boot time.

• Sets the load order so that the KMDF runtime is loaded before the client driver.

UMDF Drivers

 UMDF  Every UMDF driver must include the standard wudfddi.h header file, which exports information that specifies which version of UMDF the driver requires. When the driver is loaded, the UMDF runtime environment checks the exported value to ensure that the required version number is less than or equal to the currently installed version. If the driver requires a version that is newer than the version already installed, the loader fails.

WDF Co-installer Packages

The WDF co-installer packages are redistributable DLLs that any vendor can use under the license terms presented when the vendor installs the WDK. Each supported CPU type has its own set of co-installers:

• UMDF and KMDF have separate co-installers located at %wdk%\redist\wdf. They are discussed in more detail in the following sections.

• The WDK also includes a co-installer for the WinUSB component WinUSBCoInstaller.dll, which supports UMDF USB drivers. The WinUSB co-installer DLL is located at %wdk%\redist\winusb.

Driver packages must include the appropriate WDF co-installers, and the version number of the co-installers must be greater than or equal to the WDF version for which the driver is compiled.

The WDK includes separate checked and free builds of the three co-installers:

• The free builds of the co-installers must be used when installing WDF drivers on free builds of Windows, such as the released versions of Windows on most users' systems.

• The checked builds of the co-installers-indicated by "_chk" appended to the name of the corresponding free build-are used only for testing, to install WDF drivers on checked or partially checked versions of Windows. A partially checked build is a free build of Windows, in which the original HAL and ntoskrnl.exe components are replaced by their checked versions.

 Tip  See "Installing Just the Checked Operating System and HAL" in the WDK for information on how to create a partially checked build of Windows-online at http://go.microsoft.com/fwlink/?LinkId=79774.

It does not matter whether your driver was built with the checked or free build environment. Both types of co-installer work with either type of driver.

Important 

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.

UMDF Co-installer Package

The UMDF redistributable co-installer package is named WudfUpdate_MMmmm.dll, where:

• MM is the major version number.

• mmm is the minor version number.

For example, the co-installer DLL for UMDF version 1.5 is WUDFUpdate_01005.dll.

Because UMDF has both user-mode and kernel-mode components, the co-installer package contains a mixture of .sys, .dll, and .exe files, as shown in Table 20-1.

Table 20-1: Contents of the UMDF Co-installer
Open table as spreadsheet

Component	Installed to	Description
Wudfrd.sys	%Windir%\System32\Drivers	The reflector
Wudfhost.exe	%Windir%\System32	The driver host
Wudfsvc.dll	%Windir%\System32	The driver manager
WUDFPlatform.dll	%Windir%\System32	The user-mode component of the UMDF runtime
Wudfpf.sys	%Windir%\System32\Drivers	The kernel-mode component of the UMDF runtime
Wudfx.dll	%Windir%\System32	The UMDF framework library
Wudfcoinstaller.dll	%Windir%\System32	The UMDF configuration co-installer, which handles the configuration of UMDF devices and drivers

Chapter 4, "Overview of the Driver Frameworks," describes these components and how they fit into the UMDF architecture.

The reflector can be installed as a service, an upper filter driver, or a lower filter driver, according to the following guidelines:

• If the UMDF driver is a function driver or if the user-mode stack contains a function driver, then the reflector should be installed as a service.

• If the UMDF driver is a filter driver or if the user-mode stack contains only filter drivers, then the reflector should be installed as the highest upper filter driver in the kernel-mode stack.

• If the device is not associated with a service-that is, the device is a raw accessible device-then the reflector should be installed as the highest lower filter driver.

 Tip  See "Adding the Reflector" in the WDK-online at http://go.microsoft.com/fwlink/?LinkId=80058.

KMDF Co-installer Package

The KMDF redistributable co-installer package is named WdfCoinstallerMMmmm.dll, where MM and mmm represent the major and minor version numbers, respectively.

For example, the co-installer DLL for KMDF version 1.5 is WdfCoInstaller01005.dll. The DLL contains two .sys files, both of which are installed in %Windir%\System32\Drivers, as shown in Table 20-2.

Table 20-2: Contents of the KMDF Co-installer
Open table as spreadsheet

Component	Installed to	Description
WdfLdr.sys	%Windir%\System32\Drivers	A component that loads the framework runtime
WdfMM000.sys	%Windir%\System32\Drivers	The framework runtime itself, where MM is the major version number