Getting a Logo for YourWindows Driver Framework Driver

Neslihan BulutSoftware Design Engineer in TestWindows Driver Foundationnebulut@microsoft.com

• Why get drivers logo’ed?• WDF Logo Requirements• WDF Logo Testing

Agenda

• Windows Logo Program identifies drivers that are designed and tested to deliver compatible experiences with Windows

• Windows Logo provides Winqual signature• Trusted by every machine

• Logo ensures:• Driver package integrity• Driver installs without any warnings or requests from an

administrator

• On 64-bit Windows unsigned drivers won’t load

Why Get Drivers Logo’ed?

Requirement # Title

1. DEVFUND-0036 User-Mode Driver Framework (UMDF) drivers must be secure, stable, reliable, and not have application compatibility issues

2. DEVFUND-0037 Kernel-Mode Driver Framework (KMDF) drivers are designed to maximize reliability and stability and do not "leak" resources such as memory and KMDF objects

3 DEVFUND-0038 KMDF drivers are designed to handle device-driver interface (DDI) failures gracefully

4 DEVFUND-0039 Windows Driver Framework (WDF) drivers are packaged to contain the latest RTM fre versions of redistributables

5 DEVFUND-0040 WDF driver INF files are properly structured

WDF Logo Requirements

WDF Logo Tests

• UMDF-specific & KMDF-specific Driver Settings• DDI Fault Injection and Driver Reliability Tests• WDF Redistributable Version Checks• INF File Validation with CheckInf

• Object Tracking will be enabled • Application Verifier will be on for the Host Process• Use !wudfext.Wudfdumpobjects in the debugger to see any

leaked objects • Object Tracking will help catch WDF object leaks

• UMDF will cause a driver stop because of leaked objects

• If you discover object leaks, set Reference Count Tracking On • This setting provides add-release history of references

UMDF Settings

• Driver Verifier will be enabled• WDF Verifier will be enabled• Enhanced Verifier will be enabled

• New feature for WDF 1.9• Performs IRQL and Critical Region checks for event callbacks

• Handle Tracking will be enabled via TrackHandles registry value for all WDF objects• Set TrackHandles registry value to * in the Wdf subkey of driver’s

Parameters key, WdfVerifier tool can be used for this.

• With WDF 1.9, running the driver under Driver Verifier also enables WDF Verifier by default• Setting VerifierOn registry value to 0 in the Wdf subkey of the

driver’s Parameters key turns this off

KMDF Settings

• WDFTester from WDK Tools is used for fault injection• DDI return values will be fault-injected• When DDI return values are fault-injected, DDI out

parameters can be fuzzed upon exit by the logo test• Drivers must inspect DDI return values properly

DDI Fault Injection

• Available in %wdk%\WDKVersionNumber\tools\wdf\wdftester\

• Uses advanced kernel techniques similar to Driver Verifier for fault injecting the DDIs called from your driver• Fault injection is currently limited to DDIs that return NTSTATUS

codes

• Has a WMI Interface for use by applications and scripts• WdfTesterScript.wsf is provided in WDK as a reference

• This script provides command line interfaces to call into Wdftester wmi methods

• For more information, see wdftester.html in WDK

• Provides call logging through traces• Use Traceview.exe (provided with the WDK) to view the call log

WDFTester

• WdfTester order of execution

1. Register Driver

2. Execute Test

3. GetDdiCallInfo

4. ConfigureDdiFi

5. Execute Test

6. Unregister Driver

WDFTester (continued)

• Use with your own tests• At the 2nd and 5th stages run a test against the driver• With any test, Wdftester can collect DDI’s called from the

driverand it can be used to fault inject those DDIs

WDFTester (continued)

1. Register Driver

2. Inject own test

3. GetDdiCallInfo

4. ConfigureDdiFi

5. Inject own test

6. Unregister Driver

• Cscript wdftesterscript.wsf runtest <DriverName> <DeviceId>

• Execute Test phase uses Device Disable Enable Test from WDK• Example with Osrusbfx2 from WDF samples

WDFTester Scenario

• ...registering driver osrusbfx2.sys• SUCCESS: Registered driver osrusbfx2.sys

Successfully1. Register Driver

• ...enabling Driver Verifier for osrusbfx2.sys• SUCCESS: Disabled driver• SUCCESS: Enabled driver

2. Execute Test

WDFTester Scenario (continued)

• ...getting DDI call Info for osrusbfx2.sys• 1) WdfDeviceAssignS0IdleSettings (1)• 2) WdfDeviceAssignSxWakeSettings (1)• 3) WdfDeviceInitSetPnpPowerEventCallbacks(1)• 4) WdfDeviceInitSetIoType (1)• 5) WdfDeviceCreate (1)• 6) WdfDeviceCreateDeviceInterface (1)• 7) WdfDeviceSetPnpCapabilities (1)• 8) WdfDeviceConfigureRequestDispatching (2)• 9) WdfDriverCreate (1)• 10) WdfIoQueueCreate (4)• 11) WdfIoTargetStart (1)• 12) WdfObjectGetTypedContextWorker (4)• 13) WdfUsbTargetDeviceCreate (1)• 14) WdfUsbTargetDeviceRetrieveInformation (1)

…

3.GetDdiCallInfo

WDFTester Scenario (continued)

• ...getting list of DDIs to be failed for osrusbfx2.sys• 1) WdfDeviceAssignS0IdleSettings (1)• 2) WdfDeviceAssignSxWakeSettings (1)• 3) WdfDeviceCreate (1)• 4) WdfDeviceCreateDeviceInterface (1)• 5) WdfDeviceConfigureRequestDispatching (2)• 6) WdfDriverCreate (1)• 7) WdfIoQueueCreate (4)• …• ...starting async notification for WdfTester_DdiFiEvent• ************************************************************• * TEST CASE : 1• * DDI to fail : WdfDeviceAssignS0IdleSettings• ************************************************************• ...enabling FI for driver: osrusbfx2.sys• SUCCESS: Enabled FI for WdfDeviceAssignS0IdleSettings in

osrusbfx2.sys

4.ConfigureDdiFi

WDFTester Scenario (continued)

• ...disabling driver• SUCCESS: Disabled driver• ...enabling driver• *** SUCCESS: FI occurred for WdfDeviceAssignS0IdleSettings

in osrusbfx2.sys• SUCCESS: Enabled driver

5.Execute Test

• ...unregistering driver osrusbfx2.sys• SUCCESS: Unregistered driver osrusbfx2.sys Successfully!6. Unregister Driver

• Logo Test runs in 2 phases• 1st phase determines the DDIs called • 2nd phase configures fault injection on those DDIs

• If the driver calls a DDI n times, fault injection can:• Occur at random calls, or• Be configured for any call of the DDI, inclusive 1 … n

• 3 tests from WDK are run against the driver:• Device Disable/Enable• Sleep Test • PnP Tests

Logo Test

• Fault injection exercises these DDIs:• WdfDriverCreate• WdfDeviceCreate• WdfWaitLockCreate• WdfIoQueueCreate• WdfDeviceCreateDeviceInterface• WdfDeviceAssignMofResourceName• WdfWmiInstanceCreate• WdfDeviceOpenRegistryKey• WdfRegistryQueryULong• WdfWaitLockCreate• WdfDeviceCreateDeviceInterface

Logo Test (continued)

• … and these DDIs:• WdfDeviceAssignMofResourceName• WdfWmiInstanceCreate• WdfDeviceConfigureRequestDispatching• WdfUsbTargetDeviceCreate• WdfUsbTargetDeviceSelectConfig• WdfUsbTargetDeviceRetrieveInformation• WdfDeviceAssignS0IdleSettings• WdfDeviceAssignSxWakeSettings• WdfUsbTargetPipeConfigContinuousReader• WdfIoTargetStart• . . .

Logo Test (continued)

• Drivers can be packaged for logo with only latest RTM fre versions of the WDF co-installers

• Before Windows 7 RTM, WDF v1.9 drivers can be submitted for logo only if:• Driver is not packaged with pre- RTM v1.9 co-installers

• Before WDF v1.9 RTM, v1.9 drivers can be submitted for logo provided that there is not any co-installer in the driver package

• KMDF drivers Inf file must adhere to the following requirements• Doesn’t have WDF co-installer section• Doesn’t reference WDF co-installer (WdfCoinstaller<Version>.dll) anywhere

• UMDF drivers Inf file must adhere to the following requirements• Has WDF Co-installer section. WDF Co-installer section;

• Has AddReg directive, it associates only the config co-installer (WUDFCoinstaller.dll) with the device

• Doesn’t have CopyFiles directive

• Doesn’t reference update co-installer (WUDFUpdate_<version>.dll) anywhere

• Logo is required for Windows 7 only

WDF Redistributable Version Checks

• Validation checks for:• Properly structured WDF-specific sections of INF

• Coinstaller section• WDF section• KMDF Install section in KMDF drivers• UMDF Install section in UMDF drivers• Refer to MSDN and Developing Drivers with the Windows

Driver Foundation book for details about WDF sections• CatalogFile directive in the [Version] section of INF• Service Names, Hardware Ids , CLSIDs and Display names

against the ones provided with WDK samples

• Don’t copy/paste service names, Hardware Ids, CLSIDs and Display Names from WDF samples

INF File Validation

• Test using WdfTester • Test WDF drivers with WDF Verifier and DriverVerifier• Test UMDF drivers with Application Verifier• Diagnose with WDF-specific registry settings enabled, by

using WdfVerifier application• http://msdn.microsoft.com/en-us/library/cc264238.aspx

• Use the latest RTM fre co-installers• Review and provide feedback on logo program

requirements via https://winqual.microsoft.com • Certify your driver’s quality with Windows Logo

Call to Action

• Book: Developing Drivers with the Windows Driver Foundation• http://www.microsoft.com/MSPress/books/10512.aspx

• Windows Logo Program• http://www.microsoft.com/whdc/winlogo/default.mspx• http://www.microsoft.com/whdc/winlogo/hwrequirements.mspx

• WDF Testing and INF Documentation on MSDN• WdfTester: WDF Driver Testing Toolset

http://msdn.microsoft.com/en-us/library/cc264231.aspx• Specifying WDF Directives

http://go.microsoft.com/fwlink/?LinkID=82953• Installing the Framework's Co-installer

http://msdn.microsoft.com/en-us/library/aa490024.aspx

Resources