How to Install a Driver | Developing Drivers with the Windows Driver Foundation (Pro Developer)

Drivers can be installed or updated by a number of different methods. Some methods are used largely for release installations, other methods are suitable only for test installations, and several methods can be used for either purpose.

Considerations for Test Installations

Test installations must be done repeatedly throughout the development cycle to test and debug new driver builds. Especially during the early part of the development cycle, test installation packages are often much more limited than the final release package:

A test package often has only those components that are essential to installing and running the driver.

Extra components, like associated user applications, are often omitted.
Test packages are typically either unsigned or signed with a test certificate.

However, packages for 64-bit versions of Windows Vista must be test signed.
Test packages are often installed by using techniques such as the DevCon tool in the WDK, rather than using the procedures that a customer would follow.

Test packages for WDF drivers often contain just the driver binaries, WDF co-installers, and an INF. For example, to install test packages for the Fx2_Driver and Osrusbfx2 samples:

The Fx2_Driver driver test package contains the driver binary, both WDF co-installers, and an INF.
The KMDF driver package contains the driver binary, the KMDF co-installer, and an INF.

Tip

To become familiar with code-signing tasks, See "Code-Signing Best Practices" on the WHDC Web site-online at http://go.microsoft.com/fwlink/?LinkId=79361. See also "Kernel-Mode Code Signing Walkthrough" on the WHDC Web site-online at http://go.microsoft.com/fwlink/?LinkId=79363.

Considerations for Release Installations

Release installations are done by end users to install drivers for a device on their systems. Developers must create a driver package that has the following characteristics:

The driver package contains all of the release components.
The driver package is typically signed with a release certificate, which must be traceable to a trusted CA.

Note Driver signing is a requirement for 64-bit editions of Windows Vista and later versions.
The package is installed by using one of the tools or procedures that are available to customers.

Developers also do release installations, typically to test the installation procedures before releasing the device to the public. However, to maintain the security of the release certificate, this testing is typically done by using a test certificate rather than the release certificate.

How to Install a Driver by Using the PnP Manager

The PnP manager automatically detects a new Plug and Play device and guides users through the process of locating and installing the correct driver. This is probably the most common installation technique for released drivers. However, this approach has limited value for installing test versions of a driver because the computer cannot have any earlier versions of the driver on it. If an earlier version of the driver is already on the system, the device is not "new" to the PnP manager, which does not intervene to update the driver.

The following process describes how to use the PnP manager to install either of the OSR USB function drivers on a clean computer. The process varies somewhat for different types of driver and different versions of Windows.

To Install a USB Sample

If you have not done so already, build either of the USB samples.

The installation procedure is much the same for both samples.
Copy the driver package to an installable medium such as a DVD or flash drive.
Copy the driver package from the installable medium to the test computer.
Plug in the OSR USB Fx2 device.

The PnP manager detects the device and displays a series of dialog boxes to guide you through the installation process.

The details of the installation process vary depending on which version of Windows the driver is being installed. They also depend on whether the driver is signed and, if so, what kind of certificate was used.

This procedure only works the first time that you plug in the Fx2 device. If a driver for the device already exists on the system, the PnP manager no longer considers the device to be new and does not run the installation process again. If your test computer already has an older version of the driver, use Device Manager to update the driver, as discussed in "How to Update a Driver by Using Device Manager" later in this chapter.

Tip

"How Setup Selects Drivers" in the WDK describes how the PnP manager handles driver installation-online at http://go.microsoft.com/fwlink/?LinkId=79364. See also "Device Installation Rules for Windows Vista" on the WHDC Web site-online at http://go.microsoft.com/fwlink/?LinkId=79365.

You can review "Code-Signing Best Practices" on the WHDC Web site for more about how the PnP manager handles driver signing-online at http://go.microsoft.com/fwlink/?LinkId=79361.

How to Install a Driver by Using DPInst or DIFxApp

The DIFx tools include two customizable redistributable installation applications-DPInst and DIFxAPP-that are part of the WDK and can be used for both test and release installations and updates. When the applications are run, they guide users through the process of installing the correct driver. They also add an entry to the Control Panel Programs and Features application (called Add or Remove Programs on Windows Server 2003 and earlier versions of Windows) that allows users to remove the driver package:

DPInst is a configurable application that can be used to install a driver package.

DPInst is typically used when the driver package is the only component to be installed.
DIFxApp is a configurable Windows Installer custom action.

DIFxApp is typically used with drivers that are distributed as part of an application package.

Both applications can also be configured to uninstall the driver.

Tip

DPInst and DIFxApp are recommended solutions, as described in "Using the Driver Install Framework (DIFx)" in the WDK-online at http://go.microsoft.com/fwlink/?LinkId=79366.

How to Install a Driver by Using a Custom Installation Application

The approaches described in previous sections work well for many installation scenarios. However, some devices have more specialized requirements that these approaches cannot handle or the vendor prefers its own branded installation procedure. In such a case, the best approach is to implement a custom installation application. This is a normal user-mode application-typically similar to a wizard-that installs the driver and performs any other installation tasks. The application typically also can uninstall the driver, if necessary.

Tip

The DIFx tools also include an API (DIFxAPI), which is the recommended API for implementing custom driver installation applications. See "Writing a Device Installation Application" in the WDK-online at http://go.microsoft.com/fwlink/?LinkId=79367.

How to Install or Update a Driver by Using DevCon

DevCon is a WDK command-line tool that can be used to manage the devices on a computer, including installing and updating drivers. DevCon is intended for use only by developers.

DevCon is typically used to install or update the driver on test computers: The following command installs a driver:

 Devcon install INF_FileName Hardware_ID

INF_FileName is the path and file name of the package's INF. If you omit the path, DevCon assumes that the INF is in the current folder. Hardware_ID is the device's hardware ID.

Note To use this DevCon command, the driver binary, INF, and co-installers must be in the same folder.

To update a driver, replace install in the previous example with update.

Tip

The WDK includes a version of DevCon for each supported CPU architecture in subdirectories under %WDK%\tools\devcon. Read the DevCon documentation in the WDK- online at http://go.microsoft.com/fwlink/?LinkId=79777.

How to Update a Driver by Using Device Manager

Drivers must be installed multiple times during testing, so installing updated driver builds on test computers is a common occurrence during the development process. One convenient way to update drivers is by using Device Manager. Users can also use Device Manager to update drivers, but it is typically used only by relatively advanced users.

To use Device Manager to Update a Driver

Run Device Manager.
In Device Manager, right-click the device and select Update Driver Software.
Use the Update Driver Software Wizard to specify the location of the driver package and install the new driver.

How to Uninstall a Driver

Windows is designed so that users typically do not need to know anything about uninstalling drivers. If a driver must be uninstalled, the process usually occurs silently, without user interaction. However developers must understand how to uninstall drivers from two perspectives:

Developers must implement installation applications to correctly uninstall the driver.
Developers must sometimes explicitly uninstall drivers to prepare computers for some testing scenarios.

For example, you cannot test how the PnP manager installs a driver if an old version of the driver is still installed on the test computer.

Tip See "Uninstalling Drivers and Devices on Windows Vista" in the WDK for more information on uninstalling drivers-online at http://go.microsoft.com/fwlink/?LinkId=80089.

Driver Installation Process

Before designing a procedure to uninstall a driver, you must first understand the process that Windows uses to install a WDF driver and how an uninstall action can undo various parts of the process. The Windows Vista installation process involves three basic phases. Each phase consists of one or more actions that can be undone later by an uninstall procedure. The actions are numbered for reference later in the chapter-they are not necessarily performed in numbered order.

Phase 1: Install the Required WDF Framework, if Necessary

If the system has an older version of the framework-or no version at all-the co-installer installs the current version of UMDF or KMDF-as required by the driver.

Phase 2: Create a Devnode for the Device

The PnP manager creates a devnode for the device and associates it with the device tree.

Phase 3: Stage the Driver Package in the Driver Store

This phase of installation involves two actions:

All the drivers in the package are copied to the driver store, a repository for driver packages that is managed by DIFx. The process uncompresses any compressed files and duplicates the package's source media directory structure. The PnP manager's internal database is automatically updated with the driver package's metadata.
The INF file is copied to the %Windir%\Inf folder.

Phase 4: Install the Driver on a Device

This phase has several separate actions:

The driver's binary files are copied to their target destination.
The Service Control Manager (SCM) is called.
The registry keys are updated.
COM is used to register components (UMDF only).

Uninstall Actions

Three basic types of uninstall actions can be performed on a driver or device: uninstall the device, delete the driver package, and delete the driver's binary files. This section provides brief descriptions of the three basic uninstall actions.

Note The standard uninstall techniques and tools discussed in this chapter cannot remove the frameworks from a system. The frameworks should be updated only as necessary, not uninstalled. Leaving the frameworks in place ensures that they are still available for any other WDF drivers on the system that depend on them. In Windows Vista and later versions of Windows, the frameworks are native to the system and cannot be removed at all. This restriction ensures that the frameworks are available for system components that depend on them.

Uninstall a Device

This uninstall action removes the devnode that is associated with the device. After the action is finished, the device instance no longer exists but the device package remains in the driver store. If the device is unplugged and then plugged in again, the PnP manager treats it as a new device.

This uninstall action is done automatically by the PnP manager and undoes Phase 2 of the installation process plus some of the actions of Phase 4.

When the PnP manager uninstalls a device, it simply removes a subset of the system states that were created during installation. The driver package and binaries remain where they are, and registry keys that were created by the class installer or co-installer and some other registry operations are not changed. However, this uninstall action is enough to prevent Windows from loading the driver for all common user scenarios.

Delete a Driver Package From the Driver Store

This uninstall action deletes the package's files from the driver store and removes the associated metadata from the PnP manager's internal database. This action also deletes the package's INF from %Windir%\Inf. After the package has been removed from the driver store, it is no longer available to be installed on a device. The package must be restaged from the original source, such as optical media, a network share, or Windows Update.

This uninstall action undoes Phase 3 of the installation process. The PnP manager automatically does these actions if users select the Delete the driver software for this device option when they start the uninstall process.

Important

Do not manually delete the driver package from the driver store. This can cause an inconsistency between the INF, the driver store catalog, and the driver in the driver store, which might leave users unable to stage the driver again.

Delete the Installed Driver's Binary Files

This uninstall action deletes the driver's binary files from the target folder, typically %Windir%\System32\Drivers.

This action undoes some of the actions of Phase 4 of the installation process. The PnP manager does not support this uninstall action; it must be performed with the DIFx tools. DIFx tools check for consistency between the file on the target destination and the file on the driver store-they do not rely on the file path and file name. Therefore, Microsoft strongly recommends that this type of uninstaller be based only on the DIFx tools, which are designed to support robust uninstall procedures.

Important

The DIFx tools do not track how many devices depend on a driver binary or whether that binary is in use by other components. When you uninstall a device, the associated driver binaries might still be in use by other devices or applications, so removing the binaries usually causes failure. Before removing any driver binaries, an uninstaller must verify that the binaries are not being used by any other component on the system and can be safely removed.

Tools for Uninstalling Drivers and Devices

You can uninstall drivers and devices in two basic ways: by using Windows Device Manager and by using the DIFx tools. This section discusses how to use these tools to implement the uninstall actions discussed in the previous section. This section provides brief descriptions of the tools and their capabilities.

Device Manager

You can use Device Manager to uninstall drivers, but not to delete the driver binaries. In Windows Vista, Device Manager is a Control Panel application. In earlier versions of Windows, Device Manager can be accessed through the Control Panel Administrative Tools application.

Note Uninstalling a device or driver with Device Manager requires membership in the local Administrators group or the equivalent.

DIFx Tools

When DIFx tools are used to uninstall a driver, they remove the driver package and binaries. After uninstalling the driver with DIFx tools, you usually use Device Manager to uninstall the device.

Important

You must use the same DIFx tool for both install and uninstall procedures. For example, you cannot use DIFxApp to install a driver and use DPInst to uninstall the driver.

Microsoft recommends using only the DIFx tools to create driver uninstallers. Applications that use DIFx tools to uninstall drivers will work correctly with future versions of Windows. Although other approaches might be successful with the current versions of Windows, they are not guaranteed to work correctly with future versions.

Devcon

You can also use DevCon to uninstall devices, typically on test computers running versions of Windows earlier than Windows Vista.

To Use Devcon to Uninstall a Driver

Run the following command:
- devcon remove ID
where ID is the device's hardware ID. This action deletes the device stack and removes the devnode, but does not delete driver binaries or the driver and INF from the driver store.

To Remove the Driver and INF From the Driver Store

Run the following command:
- devcon dp_delete INF_File
where INF_File is the path and name of the package's INF, which is located in %Windir%\Inf.