Troubleshooting KMDF Driver Installation
Updated: June 26, 2006
Are you having trouble with your Kernel-Mode Driver Framework (KMDF) 1.1 driver installation procedure? The following are some suggestions for troubleshooting driver installation, along with some common errors and possible solutions.
Installation and Setup Error Logging
Each of the components that are involved in installation and setup records information in a log file. You can check these log files for information that pertains to KMDF and your driver:
| • | The KMDF 1.1 installation log (%windir%\wdf01001inst.log) contains information about events and errors that occur during KMDF 1.1 installation. |
| • | The Setup action log (%windir%\setupact.log) contains debugging messages from the KMDF co-installer. |
| • | The SetupAPI log (%systemroot%\setupapi.log) contains information that SetupAPI records each time a driver is installed on the system. |
You can control the amount of information for each event in the SetupAPI log by setting registry keys that affect logging. Logging more information can often help you find the source of an installation problem. Errors that occur while installing your driver might actually be the result of errors in installing another driver elsewhere in the device stack. Consequently, it is sometimes useful to increase the logging level for all installation applications.
To control the amount of information that is logged for all device installation programs, check the value of the LogLevel entry for the following registry subkey:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion
\Setup
If this subkey does not contain a LogLevel entry, create one as a new REG_DWORD value. Then set the value of the LogLevel entry to the logging level that you prefer.
To control the amount of information that is logged only for your driver's installation application, check the value of the following registry subkey:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows
\CurrentVersion\Setup\AppLogLevels
To enable verbose logging for your driver, create an entry that has the same file name as the installation application and assign the logging level to that name. For example:
MyDriverInstaller = 0x2000FFFF
The most commonly used logging levels are the following:
| • | 0x00000000, which specifies default logging with no special flags. |
| • | 0x00006060, which causes most messages to be logged. However, this level does not log all the INF files that are included in a search for matching INF files. |
| • | 0x2000FFFF, which specifies that everything should be logged and that the log file should not be flushed to disk after each message is written. This level is recommended for verbose logging. |
Common KMDF Installation Errors
Fatal Error during Installation
Any of several problems can cause this error. To resolve it, try the following steps:
1. | Ensure that you are using the free co-installer on the free version of Microsoft Windows and the checked co-installer on the checked version of Windows. Note:
If you previously received this message and have already edited your INF to use the correct co-installer, you must also manually delete the following file: %windir%\system32\wdfcoinstaller01001.dll Setup API does not overwrite this file. |
2. | Ensure that Cryptographic Services is running: | • | Right-click My Computer, and then click Manage. | | • | In the Computer Management dialog box, expand the Services and Applications file by clicking the plus sign (+), and then click Services. | | • | In the Services panel on the right, scroll down to and click Cryptographic Services. | | • | In the Cryptographic Services Properties dialog box, on the General tab, ensure that Service status is Started. |
|
3. | In KMDF version 1.1, the Wdf section of the INF file can contain only one KmdfService directive and one KmdfLibraryVersion directive. (This is a bug in KMDF 1.1 that will be fixed in a later release.) If you use a single INF to install more than one KMDF driver (such as a function driver and a filter driver), comment out the KmdfService and KmdfLibraryVersion directives that apply to any other drivers. For example, the following INF snippet contains information to install two drivers and thus contains two KmdfService and two KmdfLibraryVersion directives. In the following example, the lines in bold should be commented out to resolve the error: [ToasterFilter.NT.Wdf]
;KmdfService = DevUpper, DevUpper_wdfsect
KmdfService = wdffeatured, wdffeatured_wdfsect
[DevUpper_wdfsect]
KmdfLibraryVersion = 1.1
;[wdffeatured_wdfsect]
;KmdfLibraryVersion = 1.1 |
4. | If the preceding steps do not resolve the problem, look at the KMDF 1.1 installation log (%windir%\wdf01001inst.log), which contains information that might help you troubleshoot the installation. |
Error Code 37
This error can indicate either a problem with the co-installer or a problem in the DriverEntry routine.
If one of the following messages appears in the Setup action log (%windir%\setupact.log), a failure in the DriverEntry routine is probably the cause of the error:
| • | 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 |
Error code 37 can also occur when you update a KMDF 1.0 driver to KMDF 1.1. If the existing driver is already loaded in memory when you try to install the new driver, the new driver tries to bind dynamically to the already-loaded KMDF 1.0 run-time library. The binding fails, and the error is logged in the system's event log. (To view the system event log, click Start, click Control Panel, double-click Administrative Tools, double-click Event Viewer, and then click System.)
Error Code 31
This error is always the result of a problem in the driver. Ensure that the EvtDriverDeviceAdd callback returns 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 (%windir%\setupact.log).
The co-installer reports errors such as a malformed [Wdf] section in the setupact.log file. For example:
WdfCoInstaller: ReadComponents: Error Non-existent wdf section
Please refer to the Kmdf samples/documentation to add the Wdf Section
The setupact.log file also indicates the major and minor KMDF versions that the INF uses. You should see a line similar to the following:
ReadComponents setting the WdfSection for Driver Service
Ramdisk using KMDF lib version Major 0x1, minor 0x1
Both the major and minor versions should be 1. If you do not update the INF file to use the KMDF 1.1 co-installer (WdfCoInstaller01001.dll), the log file indicates that the INF is using version 1.0. You must also update the KmdfLibraryVersion directive to specify 1.1.
Some installations fail because Device Manager uses an outdated INF instead of the updated one. To avoid this problem, do either of the following:
| • | Delete the version 1.0 oem*.inf and oem*.pnf files from the %windir%\inf folder so that the incorrect INF is not available. |
| • | Specify the search path to the new driver instead of allowing Device Manager to use its defaults. |
What should you do?
| • | Check the log files for information that pertains to your driver installation. |
| • | Set the SetupAPI logging level to provide verbose information at driver installation. |
| • | Use the correct KMDF co-installer for the KMDF version and operating system platform. |
| • | Use the correct version of the INF to install the driver. |
| • | In INF files for use with KMDF 1.1, specify only one KmdfService directive and one KmdfLibraryVersion directive. |
| • | Check the system event log for errors that occur during dynamic binding of the KMDF driver to the library. |
For more information:
White Papers:
An Introduction to How to Build, Install, Test, and Debug KMDF Drivers
Troubleshooting Device Installation with the SetupAPI Log File
Windows Driver Kit (WDK):
"Installing a Framework-based Driver"
MSDN:
Using SetupAPI Logging
