How to Troubleshoot WDF Driver Installation Problems | Developing Drivers with the Windows Driver Foundation (Pro Developer)

The following are suggestions for troubleshooting driver installation, along with some common errors and possible solutions. Before investigating a device installation problem, you should have the following items:

The driver package, including the INF and all files in the driver store.

For example, the Fx2_Driver driver package resides in %windir%\System32\Driver-Store\FileRepository\osrusbfx2.inf_4e4bba4c. The numbers after the .inf file name are generated automatically to create a strong name, which eliminates the possibly of a name collision.
Error logs.

See "Driver Installation Error Logs" later in this chapter for further information.
Information about any error messages and where they occurred.
Any device error codes from Device Manager.

Info Windows Vista error codes are the same as those in Windows XP. See Microsoft Knowledge Base article 310123, "Explanation of error codes generated by Device Manager," for a list of Device Manager error codes and suggested solutions-online at http://support.microsoft.com/kb/310123.
The Hardware ID for the device.

To get this information, run Device Manager and display the driver's Properties dialog box. The hardware ID is located on the Details tab.

How to Use WinDbg to Debug Installation Errors

Device installation sometimes fails because of problems in the driver's loading and startup code. For UMDF drivers, these errors usually occur in the IDriverEntry::OnDeviceAdd method. For KMDF drivers, these errors usually occur in the DriverEntry or EvtDriverDeviceAdd routine.

To debug such errors, set breakpoints in the misbehaving routines and then use WinDbg to determine why they are failing.

Chapter 22, "How to Debug WDF Drivers," provides information about driver debugging and WinDbg.

Driver Installation Error Logs

Each component that is involved in installation and setup records information in a log file. You can check these log files for information that pertains to WDF and your driver.

All versions of Windows that support WDF have the following setup log files:

SetupAPI log Contains information that SetupAPI records each time a driver is installed on the system.

This log is useful for determining whether device installation was attempted. If the log indicates that the co-installers were called, check the Setup action log for more information. If the log indicates that the system attempted to do the update, check the WDF update logs.

Windows Vista has two SetupAPI logs: the device installation log at %windir%\inf\Setupapi.dev.log and the application installation log at %windir%\inf\Setupapi.app.log.

Earlier versions of Windows have one SetupAPI log located at %systemroot%\setupapi.log.
Setup action log Contains debugging messages from the WDF co-installers.

This log is located at %windir%\setupact.log.
WDF update logs Contain information about WDF installation errors (Windows Vista only).

The KMDF update log contains information about events and errors that occur during the installation of KMDF drivers. This log is located at %windir%\wdfMMmmminst.log, where MM indicates the major version number and mmm the minor version number.

The UMDF update log contains messages from the UMDF co-installer. This log is located at %windir%\temp\wudf_update.log.
Setup error log Contains setup error messages.

This log is located at %windir%\setuperr.log.
System event log Contains information about errors that occur during dynamic binding of a KMDF driver to the library.

This log is available through Event Viewer.

You can control the amount of information for each event in the SetupAPI log by setting a registry value. It is sometimes useful to increase the logging level for all installation applications. Errors that occur while installing your driver could actually have been caused by an installation error for another driver elsewhere in the device stack. To help catch such errors, increase the logging level.

Tip See "Troubleshooting Device Installation" in the WDK for more information about SetupAPI logging-online at http://go.microsoft.com/fwlink/?LinkId=79370.

Tip

The SetupAPI and Setup action logs are a cumulative record of all installations and can be quite large. If you have a reproducible error, rename the existing log files and then reinstall the driver. The system will create new SetupAPI and Setup action logs that contain only the data associated with your driver.

Common WDF Installation Errors

A number of errors can occur during installation. Most are generic issues such as a mismatch between the files specified in the INF and the files actually in the package. This section discusses some common WDF installation errors and possible solutions.

Tip See "Guidelines for Using SetupAPI" in the WDK for a general discussion of driver installation errors-online at http://go.microsoft.com/fwlink/?LinkId=79371.

Fatal Error During Installation

Several problems can cause this error. Some common causes of this error include the following conditions:

The co-installer version is incorrect. The free version of the co-installer can be used only with a free version of Windows, and the checked version of the co-installer can be used only with a checked version of Windows. If you used the wrong co-installer, you must manually delete it from %windir%\system32\.

If you attempt to use the wrong co-installer, Setupact.log contains a message similar to the following:
```
 Message A WdfCoInstaller: [12/08/2006 22:28.25.834] Update process returned error code:error(1603) Fatal error during installation. Message B Possible causes are running free version of coinstaller on checked version of OS and vice versa. Message C WdfCoInstaller: [12/08/2006 22:28.25.864] Final status: error(1603) Fatal error during installation. 
```
Cryptographic Services is not running. Use the Services component of the Control Panel Administrative Tools application to start cryptographic services.
The system does not trust the certificate used to sign the update. This problem typically occurs when the test root certificate was not installed on the test computer.
The INF has duplicate directives. A bug in KMDF version 1.1 causes an installation failure if the INF contains more than one KmdfService or KmdfLibraryVersion directive.

This can occur with filter drivers if the filter driver and function driver services are included in the same INF. You should use KMDF version 1.5 or later, which does not have this bug.

PnP Manager Error Codes

If the PnP manager encounters an error, it returns an error code to indicate the nature of the problem. Device Manager has an entry for the device, but it is marked by a yellow exclamation point to indicate a failed installation. To view the error codes, open the device's Properties dialog box in Device Manager. This section briefly discusses two commonly encountered error codes for WDF drivers.

Tip See "Device Manager Error Messages" in the WDK for a complete list of PnP manager error codes-online at http://go.microsoft.com/fwlink/?LinkId=80068.

Error Code 37

This error can indicate a problem either with the co-installer or in the driver's DriverEntry routine. If either problem caused the error, the Setup action log probably contains one of the following messages:

 Final status: error(0) The operation completed successfully. GetLatestInstalledVersion install version major 0x1, minor 0x1 is less than or equal to latest major 0x1, minor 0x1, asking for post processing WdfCoinstaller: DIF_INSTALLDEVICE: Post-Processing

The most likely cause of this error is a problem in the driver's DriverEntry routine. Set a breakpoint in this routine and use WinDbg to determine the problem.

Error Code 31

This error is always caused by a problem in the driver. This error is often generated when the EvtDriverDeviceAdd or IDriverEntry::OnDeviceAdd callback returns a status other than STATUS_SUCCESS.

Other Installation Errors

Most of the other causes of errors during installation should be evident from the entries in the Setup action log. The following are some typical examples:

A malformed [Wdf] section in the INF.

The header version used to compile the driver does not match the library version.
Badly decorated section names in the INF.

If you use a qualifier, you must use it in all relevant sections. For example, an INF cannot have the services and co-installer sections named DDinstall.NT.Services and DDinstall.Coinstallers, respectively. You can fix this error by naming the co-installer section DDinstall.NT.Coinstallers. Use the CheckInf tool to catch such errors.
A mismatch between the co-installer version and the version specified by the KmdfLibraryVersion or UmdfLibraryVersion directive.

They must be the same version.
Device Manager using an outdated INF instead of the updated one.

You can avoid this problem in two ways: Delete the old version's oem*.inf and oem*.pnf files from the %windir%\inf folder so that the old INF is not available or specify a search path to the new driver instead of allowing Device Manager to use its default search path.