Example: Walkthrough SDV Analysis of Fail_Driver3 | Developing Drivers with the Windows Driver Foundation (Pro Developer)

This section provides a step-by-step walkthrough, showing how to run SDV to analyze the KMDF Fail_Driver3 sample driver. Fail_Driver3 contains coding errors that are intended to show you how to run SDV and how to interpret the test results. Fail_Driver3 uses a library that includes one source and one header file, in addition to driver source and header files.

Inside Out

File_Driver3 is provided with the WDK at %wdk%\tools\sdv\samples\fail_drivers\kmdf\fail_driver3.

How to Prepare to Verify Fail_Driver3

Follow these steps as you build and verify the Fail_Driver3 sample driver by using SDV.

Building the Fail_Driver3 Library by using SDV

To use the KMDF Fail_Driver3 sample, you must first navigate to the driver's library subdirectory and build the library. The Fail_Driver3 sample contains defects that can be found only when you link to the library.

To Build the Fail_Driver3 library with SDV

Open a build environment window from the Windows Start menu, using the following menu path:
- All Programs > Windows Driver Kits > WDK_Version > Build Environment > Operating System > Build Environment
SDV supports all free and checked versions of the build environments. For this sample, you should select a free build.
In the build environment window, navigate to:
- %wdk%\tools\sdv\samples\fail_drivers\kmdf\fail_driver3\library
Build the library by using the following commands:
- staticdv /clean
- staticdv /lib

When you use the staticdv /lib command, SDV calls the Build utility to compile and build the library for external use and generates the files that SDV must include in the library to perform the driver verification.

Creating the Sdv-map.h file for Fail_Driver3

Before SDV verifies a driver, it must know about the driver's supported capabilities. When you run SDV for the first time, SDV automatically scans the driver's source code to find the entry points. For a KMDF driver, these are the callback function role type declarations described in "How to Annotate KMDF Driver Source Code for SDV" earlier in this chapter. You can also perform this step manually.

For Fail_Driver3, use SDV to explicitly scan the driver and to detect all of the callback functions. When you scan the driver, SDV records the results of the scan in Sdv-map.h, a file that SDV creates in the driver's sources directory.

Important

Review the Sdv-map.h file to ensure that the correct callbacks are selected. After you review the file, you can approve the file so that SDV retains it for future verifications.

To Scan Fail_driver3 and Create the Sdv-map.h File

In the build environment window, navigate to the driver directory at %wdk%\tools\sdv\samples\fail_drivers\kmdf\fail_driver3\driver.
Scan the driver callback routines in Fail_Driver3 by typing the following command in the build environment window:
- staticdv /scan
View the Sdv-map.h file by typing the following command in the build environment window:
- notepad sdv-map.h

The Sdv-map.h file contains #define statements for the callback functions that were found during the scan of Fail_Driver3, as follows:

 //Approved=false #define fun_WDF_DRIVER_DEVICE_ADD EvtDriverDeviceAdd #define fun_WDF_IO_QUEUE_IO_READ EvtIoRead #define fun_WDF_TIMER_1 EvtTimerFunc #define fun_WDF_DRIVER_UNLOAD EvtDriverUnload #define fun_WDF_REQUEST_CANCEL EvtRequestCancel #define fun_WDF_IO_QUEUE_IO_WRITE EvtIoWrite #define fun_WDF_IO_QUEUE_IO_DEVICE_CONTROL EvtIoDeviceControl

To Approve the Sdv-map.h File

While you are reviewing the Sdv-map.h file in Notepad, set the value of the //Approved flag to true.
Save and close the Sdv-map.h file.

How to Verify Fail_Driver3

In the Fail_Driver3 sample, a sample defect that violates the FDOPowerPolicyOwnerAPI rule has been injected in the driver. The FDOPowerPolicyOwnerAPI rule applies only to function drivers. Therefore, first run the precondition rule FDODriver to verify that Fail_Driver3 is a function driver.

To Verify Whether Fail_Driver3 is an FDO Driver

In the build environment window, type the following command:
- staticdv /rule:FDODriver

As shown in the output in Listing 24-6, the rule should show a Pass result for Fail_Driver3 in the build environment window. This means that the FDOPowerPolicyOwnerAPI rule applies to Fail_Driver3.

Listing 24-6: Pass result for the FDODriver rule for Fail_Driver3

 C:\WINDDK\6001\tools\sdv\samples\fail_drivers\kmdf\fail_driver3\driver>     staticdv /rule:FD0Driver --------------------------------------------------------------------- Microsoft (R) Windows (R) Static Driver Verifier Version 1.5.314.0 Copyright (C) Microsoft Corporation.  All rights reserved. --------------------------------------------------------------------- Build     'driver'  ...Done Link      'driver' for [fail_library3.lib] ...Done Scan      'driver'  ...Done Compile   'driver' for [sdv_harness_pnp_io_requests] ...Done Link      'driver' for [fail_library3.lib] ...Done Check     'driver' for 'fdodriver' ...Running Check     'driver' for 'fdodriver'  ...Done Static Driver Verifier performed 1 check(s) with:         1 Rule Passes Start Time :1/25/2007 3:34:06 PM and End Time :1/25/2007 3:34:16 PM

To Clean the Directory to Prepare to Verify Another Rule

In the build environment directory, type the following command:
- staticdv /clean

Now, check Fail_Driver3 for the FDOPowerPolicyOwnerAPI rule.

To Verify Whether Fail_Driver3 Correctly Calls the Three Power Management DDIs

In the build environment directory, type the following command:
- staticdv /rule:FDOPowerPolicyOwnerAPI

As shown in Listing 24-7, the rule should show a defect result for Fail_Driver3 in the build environment window. This means that Fail_Driver3 has a Fail result for the FDOPowerPolicyOwnerAPI rule, so it does not correctly call the power management DDI functions.

Listing 24-7: Fail result for FDOPowerPolicyOwnerAPI rule for Fail_Driver3

 C:\WINDDK\6001\tools\sdv\samples\fail_drivers\kmdf\fail_driver3\driver>     staticdv /rule:"FD0PowerPolicyOwnerAPI" --------------------------------------------------------------------- Microsoft (R) Windows (R) Static Driver Verifier Version 1.5.314.0 Copyright (C) Microsoft Corporation.  All rights reserved. --------------------------------------------------------------------- Build     'driver'  ...Done Link      'driver' for [fail_library3.lib] ...Done Scan      'driver'  ...Done Compile   'driver' for [sdv_harness_pnp_io_requests] ...Done Link      'driver' for [fail_library3.lib] ...Done Check     'driver' for 'fdopowerpolicyownerapi' ...Running Check     'driver' for 'fdopowerpolicyownerapi'  ...Done Static Driver Verifier performed 1 check(s) with:         1 Defect(s) Start Time :1/25/2007 3:45:43 PM and End Time :1/25/2007 3:45:54 PM

How to View the Results for Fail_Driver3

You can conveniently view all of the defects in the sample drivers by using the Static Driver Defect Report.

To View the Defect Report for Fail_Driver3

In the build environment window, type the following command:
- staticdv /view
In the Results pane on the right of the Static Driver Verifier Report Page, double-click FDOPowerPolicyOwnerAPI.

This opens Defect Viewer, which displays a trace of the code path to the rule violation. See Figure 24-3 earlier in this chapter for an illustration of the Static Driver Verifier Defect Report Page for Fail_Driver3.

Reviewing the Rule for a Violation in Fail_Driver3

Before trying to find the rule violation in the sample driver code, you can become familiar with the rules that the driver violated by reviewing the Help topic for the rule.

To See the Code for the Rule

In the Source Code pane in the center of the Static Driver Verifier Report Page, click the tab with the FDOPowerPolicyOwnerAPI.slic file.

Stepping Through the Defect Trace for a Violation in Fail_Driver3

Fail_Driver3 violates the FDOPowerPolicyOwnerAPI rule. You can use the Trace Tree pane on the left to step through the execution path. As you scroll through the elements in the Trace Tree pane:

The source code file in which the selected element originates moves to the top of the stack of files in the Source Code pane.
The associated line of code is highlighted.

Look for the following when you view the violation of the FDOPowerPolicyOwnerAPI rule for Fail_Driver3:

Inside the WDF_DRIVER_DEVICE_ADD callback of the Fail_Driver3 driver, the driver calls the SDVTest_wdf_FDOPowerPolicyOwnerAPI library function.
Inside this library function, the WdfDeviceInitSetPowerPolicyOwnership DDI function is called with the second parameter being FALSE.

Therefore, the driver is not the power policy owner any more, and SDV marks this information.
Inside the same library function, the WdfDeviceInitSetPowerPolicyEventCallbacks DDI function is called.

This causes a rule to find a defect because only the owner of the power policy can call this DDI function.

Note The defect message that this rule displays is actually a warning about a possible defect in the driver. Some drivers establish power policy ownership based on some external data. For example, in the Serial sample driver at %wdk%\src\kmdf\serial, a registry setting determines whether the driver is a power policy owner, as defined in the driver's SerialEvtDeviceAdd callback function. Because SDV has no knowledge of the external data for such drivers, the defect that the rule reports could be a false defect if one of the three power management DDI functions that SDV is looking for is called on an execution path where the driver is actually a power policy owner.