driver writing != bus driving

So Long, Farewell, Auf Wiedersehen, Good-bye...

2010-09-01T23:10:19Z

This is my last post in this blog. After 4 years at Microsoft, it's time for me to move on. This fall I'm starting a MBA degree at Northwestern University's Kellogg School of Management (Go Wildcats!). My experiences at Microsoft have been excellent, but at some point all good things need to come to an end. Hopefully, my blog will still be informative for everybody, who wants to find concentrated information about driver development.

So Long, Farewell, Auf Wiedersehen, Good-bye...

New Blog: USB Core Team

2009-10-07T02:37:00Z

The USB core team has started a new blog: http://blogs.msdn.com/usbcoreblog/. They'll be discussing about everything that is related to USB.

Welcome to the blogosphere USB Team :)

KMDF Debugging Videos

2009-09-22T22:29:00Z

A while ago, I wrote a blog post about our UMDF debugging videos, which were created by my teammate Abhishek.

Now, I'm really excited to announce that we've released KMDF debugging videos, which can be found at http://www.microsoft.com/whdc/devtools/debugging/kmdf.mspx. These videos were created by my teammate Kumar. They present 3 important aspects of KMDF debugging:

1) How to debug the KMDF log

2) How to get information about a driver and its objects

3) How to dump all the devices and queues

WDF Logo Requirements Regarding Coinstallers

2009-08-14T02:51:00Z

I've been asked many times, if a driver developer can avoid using WDF coinstallers. The answer is "yes, if the system already has the needed version of WDF installed (e.g. you want to install a WDF 1.5 driver in Vista RTM)". So, the next question that usually comes up is "Will I be able to have my WDF driver, which has no coinstaller, WHQL-signed". So, in this post I'll explain our WDF Logo requirements that are related to the coinstallers.

PART 1: WDF Logo Requirement

The official name of the requirement is “DEVFUND-0039: Windows Driver Framework (WDF) drivers are packaged to contain the RTM fre versions of redistributables”, but the title is very misleading!

The current situation (in WLK 1.4) for WHQL-signing is:

Win7 + WDF 1.9: No coinstaller restrictions. This means that you can use any WDF 1.9 coinstaller (beta, RC, RTM, intermediate builds, etc) or you can use no coinstaller. Since the coinstaller is not used to update a Win7 system, we wanted to allow driver submissions before Win7 RTMed, so this is a temporary policy. Now that the WDF 1.9 RTM coinstallers are out, it is suggested that you use those. We might update WLK 1.4 with a QFE to make the usage of the RTM coinstallers mandatory.
Win7 + WDF 1.0-1.7: You can use either an RTM coinstaller or no coinstaller
Windows 2000-Vista + WDF 1.9: You need to use the RTM WDF 1.9 coinstaller or no coinstaller. If you use the coinstaller, then you need to install the latest errata filters from http://winqual.microsoft.com, (under the name “WLK Update Filters”) and apply them on the DTM controller.
Windows 2000-Vista + WDF 1.0-1.7: You can use any RTM WDF coinstaller or no coinstaller (of course, you need to make sure that the needed version of WDF is already inbox if you don't submit a coinstaller).

After WLK 1.5 comes out (October 2009) the WHQL-signing situation will be:

For all operating systems and all versions of WDF (1.0 - 1.9) you can use either an RTM coinstaller or no coinstaller (if you don't submit a coinstaller, then the same restrictions as above will apply).

NOTES:

If you don't submit a coinstaller, then you'll get a warning (not an error) saying that you it's possible that in downlevel operating systems your driver might not be working (e.g. a WDF 1.7 driver will work in Vista SP1 without a coinstaller but not in Vista RTM).
As noted above, if you have an older version of the WDK, you can still compile a WDF 1.5 driver, submit it for WHQL-signing bundled with the WDF 1.5 RTM coinstaller (or no coinstaller in Vista+). Of course, this means that you'll be using older tools (compiler, prefast, etc) to build/validate your driver.

PART 2: Sample INFs

Now let's go to the inf files. What changes need to be made, if you are sure that you don't need a coinstaller?

1) KMDF: Remove all references to wdfcoinstaller0100X.dll from the inx. I'm using the echo sample from the Win7 RTM WDK as an example:

;
; echo.inf
;

[Version]
Signature="$WINDOWS NT$"
Class=Sample
ClassGuid={78A1C341-4539-11d3-B88D-00C04FAD5171}
Provider=%MSFT%
DriverVer=06/21/2006,6.1.7600.16385
CatalogFile=KmdfSamples.cat

[DestinationDirs]
DefaultDestDir = 12

; ================= Class section =====================

[ClassInstall32]
Addreg=SampleClassReg

[SampleClassReg]
HKR,,,0,%ClassName%
HKR,,Icon,,-5

[SourceDisksNames]
1 = %DiskId1%,,,""

[SourceDisksFiles]
ECHO.sys = 1,,

;*****************************************
; ECHO Install Section
;*****************************************

[Manufacturer]
%StdMfg%=Standard,NTx86

; Following section is meant for Windows 2000 as it
; cannot parse decorated model sections
[Standard]
;
; Hw Id is root\ECHO
;
%ECHO.DeviceDesc%=ECHO_Device, root\ECHO

; Decorated model section take precedence over undecorated
; ones on XP and later.
[Standard.NTx86]
%ECHO.DeviceDesc%=ECHO_Device, root\ECHO

[ECHO_Device.NT]
CopyFiles=Drivers_Dir

[Drivers_Dir]
ECHO.sys

;-------------- Service installation
[ECHO_Device.NT.Services]
AddService = ECHO,%SPSVCINST_ASSOCSERVICE%, ECHO_Service_Inst

; -------------- ECHO driver install sections
[ECHO_Service_Inst]
DisplayName    = %ECHO.SVCDESC%
ServiceType    = 1               ; SERVICE_KERNEL_DRIVER
StartType      = 3               ; SERVICE_DEMAND_START
ErrorControl   = 1               ; SERVICE_ERROR_NORMAL
ServiceBinary = %12%\ECHO.sys
LoadOrderGroup = Extended Base

;
;--- ECHO_Device Coinstaller installation ------
;

[DestinationDirs]
ECHO_Device_CoInstaller_CopyFiles = 11

[Strings]
SPSVCINST_ASSOCSERVICE= 0x00000002
MSFT = "Microsoft"
StdMfg = "(Standard system devices)"
DiskId1 = "WDF Sample ECHO Installation Disk #1"
ECHO.DeviceDesc = "Sample WDF ECHO Driver"
ECHO.SVCDESC = "Sample WDF ECHO Service"
ClassName = "Sample Device"

I've removed the sections ECHO_Device.NT.CoInstallers, ECHO_Device_CoInstaller_AddReg, ECHO_Device_CoInstaller_CopyFiles, SourceDiskFiles (the one at the bottom) and ECHO_Device.NT.Wdf.

2) UMDF: You need to replace WUDFUpdate_0100X.dll with the inbox coinstaller wudfcoinstaller.dll, which is always installed as part of UMDF (i.e. you don't need to have it as part of your driver package). I'm using the UMDF echo sample from the Win7 RTM WDK.

;
; WUDFEchoDriver.inf
;

[Version]
Signature="$WINDOWS NT$"
Class=Sample
ClassGuid={78A1C341-4539-11d3-B88D-00C04FAD5171}
Provider=%MSFTWUDF%
CatalogFile=WUDF.cat
DriverVer=06/21/2006,6.1.7600.16385

[Manufacturer]
%MSFTWUDF%=Microsoft,NTx86

[Microsoft.NTx86]
%EchoDeviceName%=Echo_Install,WUDF\Echo

[ClassInstall32]
AddReg=SampleClass_RegistryAdd

[SampleClass_RegistryAdd]
HKR,,,,%ClassName%
HKR,,Icon,,"-10"

[SourceDisksFiles]
WUDFEchoDriver.dll=1

[SourceDisksNames]
1 = %MediaDescription%

; =================== WUDF Echo Test Driver ==================================

[Echo_Install.NT]
CopyFiles=UMDriverCopy

[Echo_Install.NT.hw]

[Echo_Install.NT.Services]
AddService=WUDFRd,0x000001fa,WUDFRD_ServiceInstall

[Echo_Install.NT.CoInstallers]
AddReg = CoInstallers_AddReg
CopyFiles = CoInstallers_CopyFiles

[Echo_Install.NT.Wdf]
UmdfService=WUDFEchoDriver,WUDFEchoDriver_Install
UmdfServiceOrder=WUDFEchoDriver

[WUDFEchoDriver_Install]
UmdfLibraryVersion=1.9.0
DriverCLSID={7AB7DCF5-D1D4-4085-9547-1DB968CCA720}
ServiceBinary=%12%\UMDF\WUDFEchoDriver.dll

[WUDFRD_ServiceInstall]
DisplayName = %WudfRdDisplayName%
ServiceType = 1
StartType = 3
ErrorControl = 1
ServiceBinary = %12%\WUDFRd.sys
LoadOrderGroup = Base

[CoInstallers_AddReg]
HKR,,CoInstallers32,0x00010000,"WudfCoinstaller.dll"

[CoInstallers_CopyFiles]

[DestinationDirs]
UMDriverCopy=12,UMDF ; copy to drivers\UMDF
CoInstallers_CopyFiles=11

[UMDriverCopy]
WUDFEchoDriver.dll

; =================== Generic ==================================

[Strings]
MSFTWUDF="Microsoft Internal (WUDF)"
MediaDescription="Microsoft WUDF Sample Driver Installation Media"
ClassName="Sample Device"
WudfRdDisplayName="Windows Driver Foundation - User-mode Driver Framework Reflector"
EchoDeviceName="Sample WUDF Echo Driver"

3) KMDF 1.9 + UMDF 1.9 + WinUSB 1.9: In the Win7 RTM WDK we do have the sample WudfBioUsbSample.inf that uses all 3 frameworks. This would normally use 3 coinstallers, however, since the sample is Win7-only and these components are all inbox, we don't need to use coinstallers. I've pasted the inf file directly from the WDK with minor stylistic modifications.

;
; WudfBioUsbSample.inf - Install the OSR USB user-mode driver - WBDI sample
;

[Version]
Signature="$Windows NT$"
Class=Biometric
ClassGuid={53D29EF7-377C-4D14-864B-EB3A85769359}
Provider=%MSFTUMDF%
CatalogFile=biometrics.cat
DriverVer=06/21/2006,6.1.7600.16385

[Manufacturer]
%MSFTUMDF%=Microsoft,NTx86

[Microsoft.NTx86]
%OsrUsbDeviceName%=Biometric_Install, USB\VID_0547&PID_1002

[ClassInstall32]
AddReg=BiometricClass_RegistryAdd

[BiometricClass_RegistryAdd]
HKR,,,,%ClassName%
HKR,,Icon,,"-201"
HKR,,IconPath,0x00010000,"%SYSTEMROOT%\system32\SysClass.dll,-201"

[SourceDisksFiles]
WudfBioUsbSample.dll=1
EngineAdapter.dll=1 ; Vendor engine adapter

[SourceDisksNames]
1 = %MediaDescription%

; =================== UMDF OsrUsb Device - WBDI IOCTL interface ==================================

[Biometric_Install.NT]
CopyFiles=UMDriverCopy, WinBioEngineAdapterCopy
AddProperty=Device_Properties
Include=WINUSB.INF ; Import sections from WINUSB.INF
Needs=WINUSB.NT ; Run the CopyFiles & AddReg directives for WinUsb.INF

[Biometric_Install.NT.hw]
AddReg=Biometric_Device_AddReg
AddReg=DriverPlugInAddReg, DatabaseAddReg

[Device_Properties]
DeviceIcon,,,,"%SYSTEMROOT%\system32\SysClass.dll,-201" ; This is where a device specific icon can be specified.

[Biometric_Install.NT.Services]
AddService=WUDFRd,0x000001fa,WUDFRD_ServiceInstall ; flag 0x2 sets this as the service for the device
AddService=WinUsb,0x000001f8,WinUsb_ServiceInstall ; this service is installed because its a filter.

[Biometric_Install.NT.Wdf]
KmdfService=WINUSB, WinUsb_Install
UmdfDispatcher=WinUsb
UmdfService=WudfBioUsbSample, WudfBioUsbSample_Install
UmdfServiceOrder=WudfBioUsbSample

[Biometric_Install.NT.CoInstallers]
AddReg=CoInstallers_AddReg
CopyFiles=CoInstallers_CopyFiles

[WinUsb_Install]
KmdfLibraryVersion = 1.9

[WudfBioUsbSample_Install]
UmdfLibraryVersion=1.9.0
DriverCLSID = "{F1CB3C15-A916-47bc-BEA1-D5D4163BC6AE}"
ServiceBinary = "%12%\UMDF\WudfBioUsbSample.dll"

[Biometric_Device_AddReg]
HKR,,"DeviceCharacteristics",0x10001,0x0100 ; Use same security checks on relative opens
HKR,,"Security",,"D:P(A;;GA;;;BA)(A;;GA;;;SY)" ; Allow generic-all access to Built-in administrators and Local system
HKR,,"LowerFilters",0x00010008,"WinUsb" ; FLG_ADDREG_TYPE_MULTI_SZ | FLG_ADDREG_APPEND
HKR,,"Exclusive",0x10001,1
HKR,,"SystemWakeEnabled",0x00010001,1
HKR,,"DeviceIdleEnabled",0x00010001,1
HKR,,"UserSetDeviceIdleEnabled",0x00010001,1
HKR,,"DefaultIdleState",0x00010001,1
HKR,,"DefaultIdleTimeout",0x00010001,5000

[DriverPlugInAddReg]
HKR,WinBio\Configurations,DefaultConfiguration,,"0"
HKR,WinBio\Configurations\0,SensorMode,0x10001,1                                ; Basic - 1, Advanced - 2
HKR,WinBio\Configurations\0,SystemSensor,0x10001,1                              ; UAC/Winlogon - 1
HKR,WinBio\Configurations\0,SensorAdapterBinary,,"WinBioSensorAdapter.DLL"      ; Windows built-in WBDI sensor adapter.
HKR,WinBio\Configurations\0,EngineAdapterBinary,,"EngineAdapter.DLL"            ; Vendor engine
HKR,WinBio\Configurations\0,StorageAdapterBinary,,"WinBioStorageAdapter.DLL"    ; Windows built-in storage adapter
HKR,WinBio\Configurations\0,DatabaseId,,"6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50" ; Unique database GUID

[DatabaseAddReg]
HKLM,System\CurrentControlSet\Services\WbioSrvc\Databases\{6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50},BiometricType,0x00010001,0x00000008
HKLM,System\CurrentControlSet\Services\WbioSrvc\Databases\{6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50},Attributes,0x00010001,0x00000001
HKLM,System\CurrentControlSet\Services\WbioSrvc\Databases\{6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50},Format,,"00000000-0000-0000-0000-000000000000"
HKLM,System\CurrentControlSet\Services\WbioSrvc\Databases\{6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50},InitialSize,0x00010001,0x00000020
HKLM,System\CurrentControlSet\Services\WbioSrvc\Databases\{6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50},AutoCreate,0x00010001,0x00000001
HKLM,System\CurrentControlSet\Services\WbioSrvc\Databases\{6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50},AutoName,0x00010001,0x00000001
HKLM,System\CurrentControlSet\Services\WbioSrvc\Databases\{6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50},FilePath,,""
HKLM,System\CurrentControlSet\Services\WbioSrvc\Databases\{6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50},ConnectionString,,""

[WUDFRD_ServiceInstall]
DisplayName = %WudfRdDisplayName%
ServiceType = 1
StartType = 3
ErrorControl = 1
ServiceBinary = %12%\WUDFRd.sys
LoadOrderGroup = Base

[WinUsb_ServiceInstall]
DisplayName     = %WinUsb_SvcDesc%
ServiceType     = 1
StartType       = 3
ErrorControl    = 1
ServiceBinary   = %12%\WinUSB.sys

[CoInstallers_AddReg]
HKR,,CoInstallers32,0x00010000,"WudfCoinstaller.dll"

[CoInstallers_CopyFiles]

[DestinationDirs]
UMDriverCopy=12,UMDF ; copy to \Windows\System32\drivers\UMDF
WinBioEngineAdapterCopy=11,WinBioPlugins ; copy to \Windows\System32\WinBioPlugins

[UMDriverCopy]
WudfBioUsbSample.dll

[WinBioEngineAdapterCopy]
EngineAdapter.dll

; =================== Generic ==================================

[Strings]
MSFTUMDF="Microsoft Internal (WDF:UMDF)"
MediaDescription="Microsoft Sample Driver Installation Media"
ClassName="Biometric Devices"
WudfRdDisplayName="Windows Driver Foundation - User-mode Driver Framework Reflector"
OsrUsbDeviceName="WUDF Fx2 WBDI sample"
WinUsb_SvcDesc="WinUSB Driver"

UMDF Debugging Videos

2009-06-10T04:29:00Z

UPDATE: You can find my post about KMDF debugging videos at http://blogs.msdn.com/iliast/archive/2009/09/22/kmdf-debugging-videos.aspx

A while back I had written that we didn't have any videos, where we talk about UMDF (KMDF seems to get all the glory :P). Well, now we do!

My teammate, Abhishek, has created a series of tutorials that describe how to debug UMDF drivers. They can be found at http://www.microsoft.com/whdc/devtools/debugging/umdftraining.mspx. I've been through all the videos a few times and I think that they are very helpful and present some very nice tricks. I suggest that you install a UMDF driver and go through the same tasks that Abhishek is describing, in order to understand the tutorials better.

Feel free to give me any feedback (or any thank-you comments) that you want me to tell Abhishek :)

Viewing WDF Logs In Windbg

2009-06-10T03:44:00Z

One feature that is really helpful in debugging WDF drivers is the log file that is created by the frameworks themselves. In the log files you can see many warnings and errors that are created by the framework (i.e. they come for free and the driver does not have to do anything). Did you ever have a problem trying to understand why a call to a WDF function fails or what the framework is doing under the hood? Then, continue reading:

In this post I'll explain how to look at the framework log files, while you're debugging a driver using windbg. I assume that you have already installed the WDK in the directory %winddk%.

So, let's start with UMDF:

You need to debug the wudfhost application that hosts your driver. This is described in an earlier post of mine.
In windbg execute the command "!wmitrace.searchpath %winddk%\tools\tracing\%arch%", e.g. "!wmitrace.searchpath c:\WinDDK\6001\tools\tracing\x86". The directory that you use should have files with names wdf01007.tmf, wdf01009.tmf, etc.
Execute the command "!wmitrace.strdump" and find the number that corresponds to "WUDF Trace". Let's say that this number is 0x11.
Execute the command "!wmitrace.logdump number_from_previous_step", e.g. "!wmitrace.logdump 0x11"
In order to control the verbosity of the output, you can use WdfVerifier, which can be found at %winddk%\tools\wdf\%arch%\wdfverifier.exe. Select the tab "User Mode Driver Settings" and change the tracing level. Also, enable the option "Send Log Output to Kernel Debugger". These options are global (i.e. they will be applied to all UMDF drivers)

For KMDF, things are easier:

Load wdfkd in windbg. This file is located at %winddk%\bin\%arch%. In order to load it execute "!load %winddk%\bin\%arch%\wdfkd.dll", e.g. "!load c:\WinDDK\6001\bin\x86\wdfkd.dll"
Execute "!wdftmffile %winddk%\tools\tracing\<arch>\wdf01009.tmf", e.g. "!wdftmffile c:\WinDDK\tools\tracing\x86\wdf01009.tmf". Make sure that the file wdf01009.tmf is in that directory. If you are debugging a KMDF 1.7 driver, then you need to use the file wdf01007.tmf, etc.
Execute "!wdflogdump my_driver" to see the log for your driver. For example, if you are debugging the echo driver, execute "!wdflogdump echo".
In order to control the verbosity, you can use WdfVerifier. Select the "Kernel Mode User Driver Settings" tab, select your driver in the left panel and then either select or de-select the option "Enable verbose logging". This option is per-driver, i.e. if you want to enable verbose logging for multiple drivers, then you need to select all of them in the left panel.

Analyzing the Installation of WDF 1.7 and 1.9 drivers

2009-06-09T22:11:00Z

Many months ago I had written a post analyzing the installation of WDF 1.5 drivers. Now that WDF 1.9 is almost out of the door, it's time to do the same thing for WDF 1.7 and 1.9. The differences in the coinstallers for these 2 versions are small, so the installation experience is almost the same. I'll try to point out any differences. For the purpose of this post, I'll use the WDF 1.9 RC coinstallers. A big part of this post was presented in more depth at WinHEC 2008 by Bob Kjeelgaard and me (the presentation can be found here).

PART 1: UMDF

Let's start with the installation of a UMDF driver. I'll use the echo sample from the WDK. It can be found at %WinDDK%\6001\src\umdf\echo (for UMDF 1.7) and%WinDDK%\%version%\src\general\echo\umdf (for UMDF 1.9). After compiling the sample, you need to put the following files in one directory:

The UMDF coinstaller (%WinDDK%\%version%\redist\wdf\x86\WUDFUpdate_0100X.dll), where X is either 7 or 9
The echo driver (WUDFEchoDriver.dll)
The inf file (WUDFEchoDriver.inf)
devcon (%WinDDK%\%version%\tools\devcon\i386\devcon.exe)
Even though it's not mandatory, it might be useful for debugging to have the pdb file of the driver (WUDFEchoDriver.pdb)

Now in order to install the driver, you can go to a command prompt and use the command
devcon install WUDFEchoDriver.inf WUDF\Echo

If everything goes well, you should see the following output:

>devcon install WudfEchoDriver.inf WUDF\Echo
Device node created. Install is complete when drivers are installed...
Updating drivers for WUDF\Echo from WudfEchoDriver.inf.
Drivers installed successfully.

If there's a problem, then you'll see something like:

>devcon install WudfEchoDriver.inf WUDF\Echo
Device node created. Install is complete when drivers are installed...
Updating drivers for WUDF\Echo from WudfEchoDriver.inf.
devcon failed.

The first file that you can look at foir more information regarding the installation is %windir%\setupact.log.

SCENARIO 1: SUCCESSFUL INSTALLATION WITHOUT UPDATE

In the case of a succesful installation you should see something like:

As you see in the above scenario, the coinstaller initially looks at the version of all the UMDF files that are installed in the system and does the following checks to determine, if an update is required:

1) If max on-disk file version > co-installer -> NO UPDATE
2) If max on-disk file version == co-installer BUT mismatched versions found (or missing files)-> damaged installation -> UPDATE
3) If all on-disk file versions == co-installer AND>= 1 UMDF service cannot be opened (wudfsvc, wudfrd, wudfpf) -> UPDATE
4) If all on-disk file versions < co-installer -> UPDATE

SCENARIO 2: SUCCESSFUL INSTALLATION WITH UPDATE

In the previous scenario we saw that no update was required. Let's see what happens, if an update is required:

WudfUpdate: installing version (1,9,0,7100).
WudfUpdate: Checking for presence of previous UMDF installation.
WudfUpdate: Found binary %WINDIR%\system32\drivers\wudfrd.sys version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\drivers\wudfpf.sys version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\wudfhost.exe version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\wudfsvc.dll version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\wudfx.dll version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\wudfplatform.dll version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\wudfcoinstaller.dll version (1.5.0.6000)
WudfUpdate: UMDF installation is older than current.
WudfUpdate: Locating resource stream WUDF_UPDATE_VISTA-RTM.
WudfUpdate: unpacking update from resource to Microsoft User-Mode Driver Framework Install-v1.9-Vista.msu.
WudfUpdate: Temporary path is D:\Windows\Temp\WDF114A.tmp.
WudfUpdate: Invoking update "%SYSTEMROOT%\system32\wusa.exe" with command line "D:\Windows\Temp\WDF114A.tmp\Microsoft User-Mode Driver Framework Install-v1.9-Vista.msu /quiet /norestart".
WudfUpdate: Waiting for update to terminate. WudfUpdate: Update process returned 3010.
WudfUpdate: WUDF version 1.9.0 () was installed succesfully, but requires a reboot.
WudfUpdate: Cleaning up update.
WudfUpdate: Requesting reboot to bring device online.
WudfUpdate: Installation will be restarted after reboot

In the above scenario, the coinstaller called the update package, which tried to update UMDF, however Windows Update determined that a reboot is required before the installation can continue. So, the installation stops and the user is prompted for reboot. After the reboot, the installation is restarted automatically in the background and we see the following output:

WudfUpdate: installing version (1,9,0,7100).
WudfUpdate: Checking for presence of previous UMDF installation.
WudfUpdate: Found binary %WINDIR%\system32\drivers\wudfrd.sys version (1.9,0.7100)
WudfUpdate: Found binary %WINDIR%\system32\drivers\wudfpf.sys version (1.9,0.7100)
WudfUpdate: Found binary %WINDIR%\system32\wudfhost.exe version (1.9,0.7100)
WudfUpdate: Found binary %WINDIR%\system32\wudfsvc.dll version (1.9,0.7100)
WudfUpdate: Found binary %WINDIR%\system32\wudfx.dll version (1.9,0.7100)
WudfUpdate: Found binary %WINDIR%\system32\wudfplatform.dll version (1.9,0.7100)
WudfUpdate: Found binary %WINDIR%\system32\wudfcoinstaller.dll version (1.9,0.7100)
WudfUpdate: UMDF installation is newer than update.
WudfUpdate: Loading configuration coinstaller from D:\Windows\system32\wudfcoinstaller.dll.
WudfCoInstaller: ReadWdfSection: Checking WdfSection [Echo_Install.NT.Wdf]
WudfCoInstaller: UMDF Service UMDFSkeleton is already installed - removing existing settings in preparation for setting new ones.
WudfCoInstaller: Configuring UMDF Service WUDFEchoDriver.
WudfCoInstaller: Using "Vista" service configuration
WudfCoInstaller: Service WudfSvc is already running.
WudfCoInstaller: Final status: error(0) The operation completed successfully.

NOTE: If the coinstaller determines that a system needs to be updated, then it will always prompt the user for reboot in the end. On the other hand, the KMDF coinstaller makes independent decisions about the reboot and the update (more information in the part that is discussing the KMDF coinstaller).

SCENARIO 3: UNSUCCESSFUL INSTALLATION

If there is an error, you will see a message that says something similar to:

WudfUpdate: installing version (1,9,0,7100).
WudfUpdate: Checking for presence of previous UMDF installation.
WudfUpdate: Found binary %WINDIR%\system32\drivers\wudfrd.sys version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\drivers\wudfpf.sys version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\wudfhost.exe version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\wudfsvc.dll version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\wudfx.dll version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\wudfplatform.dll version (1.5.0.6000)
WudfUpdate: Found binary %WINDIR%\system32\wudfcoinstaller.dll version (1.5.0.6000)
WudfUpdate: UMDF installation is older than current.
WudfUpdate: Locating resource stream WUDF_UPDATE_VISTA-RTM.
WudfUpdate: unpacking update from resource to Microsoft User-Mode Driver Framework Install-v1.9-Vista.msu.
WudfUpdate: Temporary path is D:\Windows\Temp\WDF7625.tmp.
WudfUpdate: Invoking update "%SYSTEMROOT%\system32\wusa.exe" with command line "D:\Windows\Temp\WDF7625.tmp\Microsoft User-Mode Driver Framework Install-v1.9-Vista.msu /quiet /norestart".
WudfUpdate: Waiting for update to terminate.
WudfUpdate: Update process returned 22.
WudfUpdate: update returned error 0x16 - error(22) The device does not recognize the command.
WudfUpdate: For additional information please look at the log files %windir%\windowsupdate.log and %windir%\Logs\CBS\CBS.log
WudfUpdate: Cleaning up update.
WudfUpdate: Error updating UMDF - error(22) The device does not recognize the command. Aborting installation.

As the message says, in order to understand the cause of the error, you can look at the files %windir%\windowsupdate.log and %windir%\logs\cbs\cbs.log. The UMDF 1.7 coinstaller incorrectly prints the 2nd log file as %windir%\cbs\logs\cbs.log, but that has been fixed in the UMDF 1.9 coinstaller. In order to find more information about how to read windowsupdate.log, you can look at http://support.microsoft.com/kb/902093.

In a Windows XP system, the previous line says

WudfUpdate: For additional information please look at the log file %windir%\temp\wudf_update.log

So, either the reason of the error will be shown in setupact.log or in this file you'll find pointers about which file to look at.

WALKTHROUGH OF UMDF COINSTALLER ACTIONS:

The UMDF coinstaller handles only the DIF_INSTALLDEVICE code and performs the following steps:

PREDEVICE INSTALL phase

1) Check for supported OS version (XP SP2+, 2003 SP1+, Vista RTM+, 2008, Windows 7 or newer)
2) Check status of current installation:
a) Read version information for all UMDF binaries
b) If max on-disk file version > co-installer -> NO UPDATE
c) If max on-disk file version == co-installer BUT mismatched versions found (or missing files)-> damaged installation -> UPDATE
d) If all on-disk file versions == co-installer AND>= 1 UMDF service cannot be opened (wudfsvc, wudfrd, wudfpf) -> UPDATE
e) If all on-disk file versions < co-installer -> UPDATE
3) Extract MSU or update.exe package to temporary folder
4) Call MSU or update.exe package to update system
5) The update package creates marker file for the framework (e.g. %windir%\system32\drivers\MsftWdf_user_01_09_00.Wdf)
a) Possible that the update package asks for reboot, because files were marked for replacement after reboot
b) If reboot is needed, then the installation stops and will be restarted afterthe reboot
6) Load the UMDF 1.9 config co-installer (%windir%\system32\wudfcoinstaller.dll)
7) Parse and validate INF (DDInstall.WDF section)
8) Create UMDF registry keys based on INF: impersonation level, kernel-mode client support, I/O dispatcher, host timeout, etc.
9) Start UMDF Device Manager (wudfsvc)

The PNP manager proceeds with installation (file copy, registry entries, etc.)

POSTDEVICE INSTALL phase

1) UMDF config co-installer creates marker file for the driver (e.g. %windir%\system32\drivers\Msft_User_WUDFEchoDriver_01_09_00.Wdf)

PART 2: KMDF

First of all we need to compile the echo sample and put the following files in the same directory:

Now it's time for KMDF. In order to install the KMDF you need to create a directory with the following files:

The KMDF coinstaller (%WinDDK%\%version%\redist\wdf\x86\WdfCoInstaller0100X.dll), where X is 7 or 9
The echo driver (echo.sys)
The inf file (echo.inf)
devcon.exe (%WinDDK%\%version%\tools\devcon\i386\devcon.exe)
The pdb file of the driver (echo.pdb). This is not mandatory, but it might be helpful to debug the driver.

In order to install the driver you can open a command prompt and type
devcon install ECHO.inf root\ECHO

If everything goes well, you should see the following output:

>devcon install echo.inf root\Echo
Device node created. Install is complete when drivers are installed...
Updating drivers for root\Echo from echo.inf.
Drivers installed successfully.

If there's a problem, then you'll see something like:

>devcon install echo.inf root\Echo
Device node created. Install is complete when drivers are installed...
Updating drivers for root\Echo from echo.inf.
devcon failed.

The first file that you can look at foir more information regarding the installation is %windir%\setupact.log.

SCENARIO 1: SUCCESSFUL INSTALLATION WITHOUT UPDATE OR REBOOT

In the above scenario we see that no update was necessary, because on-disk and in-memory we have KMDF 1.9 and this version is the same as the version of the coinstaller.

SCENARIO 2: SUCCESSFUL INSTALLATION WITH UPDATE AND REBOOT

WdfCoInstaller: DIF_INSTALLDEVICE: Pre-Processing
WdfCoInstaller: ReadComponents: WdfSection for Driver Service ECHO using KMDF lib version Major 0x1, minor 0x9
WdfCoInstaller: DIF_INSTALLDEVICE: Coinstaller version: 1.9.7100
WdfCoInstaller: GetInMemoryVersionUlong: No information about in-memory KMDF version
WdfCoInstaller: DIF_INSTALLDEVICE: KMDF in-memory version: 0.0.0
WdfCoInstaller: DIF_INSTALLDEVICE: KMDF on-disk version: 1.5.6000
WdfCoInstaller: Service Wdf01000 is running
WdfCoInstaller: DIF_INSTALLDEVICE: Reboot is required, so that the newer KMDF version will be loaded to memory
WdfCoInstaller: VerifyMSRoot: exit: error(0) The operation completed successfully.
WdfCoInstaller: Invoking "D:\Windows\system32\wusa.exe "D:\Windows\Temp\WdfTemp\Microsoft Kernel-Mode Driver Framework Install-v1.9-Vista.msu" /quiet /norestart".
WdfCoInstaller: Update process returned error code 0 :error(0) The operation completed successfully.
WdfCoInstaller: InstallComponents: KMDF installed successfully
WdfCoInstaller: InstallComponents: Reboot needed by windows update
WdfCoInstaller: ReadComponents: WdfSection for Driver Service Echo using KMDF lib version Major 0x1, minor 0x9

In this scenario we see that on-disk we have KMDF 1.5, but we have no information about the in-memory version of KMDF. We implemented the functionality for the detection of the in-memory KMDF version in KMDF 1.7, so version 0.0.0 means that KMDF 1.5 (or older) is running.

So, the system needs to be updated (in order to put KMDF 1.9 on the disk) and rebooted (in order to bring KMDF 1.9 in memory).

SCENARIO 3: SUCCESSFUL INSTALLATION WITH REBOOT, BUT NO UPDATE

Here we see that on disk we have KMDF 1.9, but in memory we still have KMDF 1.7. So, we don't need to update the system, but we need to reboot (in order to bring KMDF 1.9 in memory).

NOTE 1: It is also possible to need to update the system (if an older version of KMDF is installed), without the need to reboot (if no KMDF driver is currently running). Generally, the reason for the reboot is that a KMDF driver is running and therefore we cannot replace the in-memory KMDF version without a reboot. On the other hand, the UMDF coinstaller will always prompt for reboot, if it determines that an update is required (this happens because the kernel-mode files are memory-mapped, so they can be replaced without a need for reboot, however for user-mode files the memory manage keeps an open handle to them, so they cannot be updated without a reboot).

NOTE 2: A big difference between UMDF and KMDF is that the UMDF installation is restarted after the reboot, whereas the KMDF one has already finished, when the user is prompted to reboot the system.

SCENARIO 4: UNSUCCESSFUL INSTALLATION WITH UPDATE AND REBOOT

WdfCoInstaller: ReadComponents: WdfSection for Driver Service ECHO using KMDF lib version Major 0x1, minor 0x9
WdfCoInstaller: DIF_INSTALLDEVICE: Coinstaller version: 1.9.7100
WdfCoInstaller: DIF_INSTALLDEVICE: KMDF in-memory version: 1.7.6000
WdfCoInstaller: DIF_INSTALLDEVICE: KMDF on-disk version: 1.7.6000
WdfCoInstaller: Service Wdf01000 is running
WdfCoInstaller: DIF_INSTALLDEVICE: Reboot is required, because the in-memory KMDF version is older than the coinstaller's version.
WdfCoInstaller: DIF_INSTALLDEVICE: Update is required, because the on-disk KMDF version is older than the coinstaller
WdfCoInstaller: VerifyMSRoot: exit: error(0) The operation completed successfully.
WdfCoInstaller: Invoking "D:\Windows\system32\wusa.exe "D:\Windows\Temp\WdfTemp\Microsoft Kernel-Mode Driver Framework Install-v1.9-Vista.msu" /quiet /norestart".
WdfCoInstaller: The update process returned error code :error(265) <no error text>.
WdfCoInstaller: For additional information please look at the log files %windir%\windowsupdate.log and %windir%\Logs\CBS\CBS.log

In this scenario, the coinstaller points to the log files, where you can find more information regarding the reason of the failure. In Windows 2000 or XP, the underlined line would be:

WdfCoInstaller: For additional information please look at the log file %windir%\Wdf01007Inst.log (for the KMDF 1.7 coinstaller) or

WdfCoInstaller: For additional information please look at the log file %windir%\Wdf01009Inst.log (for the KMDF 1.9 coinstaller)

WALKTHROUGH OF KMDF COINSTALLER ACTIONS:

The UMDF coinstaller handles only the DIF_INSTALLDEVICE code and performs the following steps:

PHASE 1: Pre-device installation

1) Check for supported OS version (Windows 2000 or higher is supported)
2) Find KmdfLibraryVersion in INF and check if it is supported (major version has to be equal to the major version of the coinstaller)
3) Check if system needs to be updated (Vista SP1/2008 or lower)
a) On-disk version of wdf01000.sys < co-installer version OR
b) On-disk version of wdf01000.sys == co-installer version AND damaged installation (ARP registry entry missing OR KMDF service cannot be opened using SCM APIs)
4) Check if reboot is required:
a) KMDF service is running AND
b) KMDF in-memory < co-installer version 5) Extract WDFCAB_RESOURCE to temporary folder
6) Call MSU or update.exe package to update system
a) It's possible that the update package asks for reboot, because files were marked for replacement after reboot
7) Create marker file for the framework (e.g. %windir%\system32\drivers\MsftWdf_Kernel_01009_Coinstaller_Critical.Wdf)

PHASE 2: PNP manager

The PNP manager proceeds with the installation (file copy, registry entries, etc.)

PHASE 3: Post-device installation

1) If driver is marked as bootstart, then KMDF service is set to bootstart
2) Create marker file for the driver (e.g. %windir%\system32\drivers\Msft_Kernel_WdfRamdisk_01009.Wdf)
3) If reboot is required, then the PNP manager prompts the user for reboot

PART 3: Additional resources

How to install WDF drivers (Quick-Start)

2009-03-19T00:23:00Z

This post is a small quick-start on how to install WDF drivers.

Part 1: Installing a UMDF driver

You can start with the echo sample, which is located at %WinDDK%\6001.18002\src\umdf\echo.

First, you need to do a bcz in that directory. In your output directory you should see the following files:

1) WudfEchoDriver.dll: This is the UMDF echo driver

2) WudfEchoDriver.inf: This is your inf

3) WudfEchoDriver.pdb: This is the pdb of your driver

Copy these 3 files (the pdb is not needed actually, but it might help you in debugging) to a separate directory (e.g. c:\umdfdriver), together with:

4) devcon.exe: This is used to install the driver. You can find it at %WinDDK%\6001.18002\tools\devcon\devcon.exe

5) WUDFUpdate_01007.dll: This is the coinstaller that will update your system to the correct version of UMDF You can find it at %WinDDK%\6001.18002\redist\wdf\WUDFUpdate_01007.dll

After you put all these 5 files in the same directory (make sure that the architecture for all these files matches the architecture of your system, i.e. use x86, if you have 32-bit windows, amd64 if you have 64-bit), you can install the driver by executing (from an elevated command prompt):

devcon install WudfEchoDriver.inf WUDF\Echo

After the installation succeeds, you can go to the device manager and see a driver with the name "Sample WUDF Echo Driver". This is your UMDF driver that is running. If you look at the task manager, you will see an application with the name wudfhost.exe running. This is the exe that loads your driver (i.e. the dll).

In order to test the driver, you can compile the application at %WinDDK%\6001.18002\src\kmdf\echo\exe and then run it. If you see success messages, it means that your driver is working correctly. You can look at the sources of the echo driver (possibly it might be easier for you to look at the sources of the UMDF skeleton driver, which is located at %WinDDK%\6001.18002\src\umdf\skeleton, because it is simpler) to understand how the driver is structured.

Part 2: Installing a KMDF driver

Again, let's start with the echo sample, which is located at %WinDDK%\6001.18002\src\kmdf\echo\sys.

First, you need to do a bcz in that directory. In your output directory you should see the following files:

1) echo.sys: This is the KMDF echo driver

2) echo.inf: This is your inf

3) echo.pdb: This is the pdb of your driver

Copy these 3 files (the pdb is not needed actually, but it might help you in debugging) to a separate directory (e.g. c:\kmdfdriver), together with:

4) devcon.exe: This is used to install the driver. You can find it at %WinDDK%\6001.18002\tools\devcon\devcon.exe

5) WdfCoinstaller01007.dll: This is the coinstaller that will update your system to the correct version of KMDF You can find it at %WinDDK%\6001.18002\redist\wdf\WdfCoinstaller01007.dll

devcon install echo.inf root\ECHO

After the installation succeeds, you can go to the device manager and see a driver with the name "Sample WDF ECHO Driver". This is your KMDF echo driver that is running

In order to test the driver, you can use the same application as for the UMDF driver (echoapp), which is located at %WinDDK%\6001.18002\src\kmdf\echo\exe and then run it. If you see success messages, it means that your driver is working correctly.

NOTE: Since both the KMDF and UMDF echo driver as identical from echoapp's perspective, it would be good for you to have only one of the two installed, if you want to make sure that everything worked successfully.

The WDF team needs your help in ensuring compatibility

2009-02-12T22:03:00Z

You might know that the Windows Driver Framework team is working on the next version of WDF, version 1.9, and planning to release it with Windows 7.

Windows 7 will have this new version of framework built in. However, we will also provide a redistributable coinstaller so that you can install this framework on downlevel operating system with latest service packs. We have added several new features to:
a) Further simplify driver development.
b) Make it easier to debug & diagnose failures during development and also in the field after deployment.
c) Reduce CPU utilization and memory footprint.
d) Enable the use of the framework in certain new technologies.
e) Fixed numerous bugs to harden the framework to handle edge conditions - in particular run down scenarios.

So we have put in lot of effort to make driver and driver writing experience better. The presentation "What's new in WDF 1.9" that we gave in WinHEC 2008 (http://download.microsoft.com/download/5/E/6/5E66B27B-988B-4F50-AF3A-C2FF1E62180F/COR-T546_WH08.pptx) has more details on the work we did.

How can you help us?

Based on our telemetry, we know there is a large number (over 1000) of framework drivers of all versions (1.1, 1.5, 1.7) written and released to public. In order to make sure that these drivers continue to work on Windows 7, and even on downlevel OSes - if a new device brings in the latest framework - we request you to test your drivers with framework version 1.9 and make sure it's fully functional. We have put an extraordinary effort to maintain compatibility but when you have such a large eco-system, we will not be able to cover every possible scenario.

We made a very successful transition from 1.5 to 1.7 with absolutely no compatibility issues and we would like to ensure that we repeat that success and keep you all happy.

So please take some time and try out the new version. You can get the 1.9 version from Windows 7 beta WDK. Information on how to get the WDK is given on this page http://www.microsoft.com/whdc/DevTools/WDK/WDKbeta.mspx.

We are also putting together a small lab with some devices to do compatibility testing on our own. We are in need of more devices that use framework drivers. So if you have released a device that we can buy from a store and use it in our lab, please send me the description.

You can post your feedback here or email to (wdfinfo@discussion.microsoft.com). Remove the word 'discussion' from the email address.

Thank you,
On behalf of the WDF team - Microsoft

WinHEC 2008 Presentations

2008-11-22T04:28:00Z

As many of you know, WinHEC 2008 took place in Los Angeles, at the beginning of this month. I gave a presentation in the conference with Bob Kjelgaard about the WDF coinstallers and WDF logo requirements. This presentation includes a step-by-step walkthrough of the execution of the coinstallers, their contents, the methodology that we are using in order to debug WDF installation failures, as well as the tests that WDF drivers need to pass, in order to be logo-ed. This presentation can be found here. The list with all the presentations in WinHEC 2008 can be found here.