driver writing != bus driving

Ilias Tsigkogiannis' Introduction to Windows Device Drivers and Windows Audio Concepts

WDF Logo Requirements Regarding Coinstallers

WDF Logo Requirements Regarding Coinstallers

  • Comments 4

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:

  1. 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.
  2. Win7 + WDF 1.0-1.7: You can use either an RTM coinstaller or no coinstaller
  3. 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.
  4. 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:

  1. 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).
  2. 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"

Leave a Comment
  • Please add 1 and 5 and type the answer here:
  • Post
  • this is one of the blogs i'm interested on, please dedicate some of your writing time further to DDK,

    thanks .

  • Thanks for the comment!

    Is there something in particular that you want to learn about the DDK?

  • hi,

    Windows Driver Framework (WDF) drivers are packaged to contain the RTM fre versions of redistributables

    test case if failinf for my driver . my driver is a software filter driver for volume class.

    i would like to know how WdfTester tests the co-installer version does it use

    WdfTester.exe -kmdf -checkCoInstallerVersion <hardware id> <od namee> ???/

    but in this i don't have any hardware ID. can you please help me here.

  • Great post, I often feel like many of the tasks

    I do online are like grunt work, and like you I agree

    it was not the way I wanted to run an online business,

    I wanted everything more easy and automated.

    The 2 out 3 rule sounds good to me, I will be implementing that now,

    I was never sure what ratio to use for mailings.

    I have tried, failed and gave up, but now I am back to try again,

    with a new passion so hopefully I can find the way that works for me this time,

    thanks for this post, it really helped me

Page 1 of 1 (4 items)