Developing Drivers with the Windows Driver Foundation (Pro Developer)

Tips for Building Drivers

Consider these best practices when building your driver:

• Build and test your driver for all versions of Windows that you plan to support. Building for the earliest version of Windows creates a binary of your driver that is compatible with all versions of Windows from that version forward. Building for the latest version of Windows provides the latest checks for your driver.

• Build your driver for both 32-bit and 64-bit platforms. Compiling for both 32-bit and 64-bit platforms can find problems in your code. In particular, compiling for 64-bit platforms can find problems related to pointers, subtle differences in the compilers, and inline assembly language, which is sometimes included inadvertently.

   Tip  See "Compiler for x64 64-Bit Environments" in the WDK-online at http://go.microsoft.com/fwlink/?LinkId=79791.

• Build your driver in a checked build environment during development. The checked build environment creates a driver with debugging code enabled. Checked builds make debugging easier because the compiler does not optimize the output binaries as thoroughly.

• Build your driver in a free build environment for performance testing and release. The free build environment creates a production driver in which code is optimized and debugging code is disabled.

• Take advantage of the compiler's error-checking capabilities. Compiling and building your driver with warnings treated as errors and error level /W4 enabled finds problems in source code to the fullest extent that the compiler can enforce.

Chapter 19, "How to Build WDF Drivers," presents details and additional best practices.

Tips for Best Use of Tools

Consider these best practices for using testing tools:

• Make sure you're using the latest tools. You should always use the latest versions of the WDK and Debugging Tools for Windows when debugging WDF drivers.

  Chapter 1, "Introduction to WDF," describes how to obtain current kits and tools.

• Use all of the testing tools that can run on your driver. If you omit any of these tools, you might miss a serious bug in your driver.

   KMDF  At a minimum for testing KMDF drivers: Enable all options in Driver Verifier and run Device Path Exerciser, Plug and Play Driver Test, and a power management test that does a suspend-resume and a hibernate-resume, such as the WDTF script Sleep_Stress_With_IO.wsf or the Sleep State Chooser (Sleeper.exe) in %wdk%\tools\acpi. Enable KMDF Verifier and examine the information it returns in the debugger.

   UMDF  At a minimum for testing UMDF drivers: Enable Application Verifier with the settings described earlier in this chapter, and run Device Path Exerciser and the WDTF scripts Disable_Enable_With_IO.wsf and Sleep_Stress_With_IO.wsf.

• Test your driver in both the checked and free builds of Windows. At a minimum for testing with the checked build: Install a checked build of your driver stack and the checked versions of Ntoskrnl.exe and Hal.dll, as described in this chapter.

  Test your driver with the free build for performance-related issues.

• Use the extended features of the testing tools. In particular, test your driver with the low-resources simulation features of Driver Verifier and Application Verifier, to validate that the driver is stable and reliable when resources are constrained.

• Make tests easily reproducible. A test that requires many manual steps or a specific system is not a viable test. The test should be easy to run and easy to move to additional test machines. If the test requires manual steps, provide a clearly written document that describes what to do.

• Make test results easy to verify. Many tests provide detailed logs of their runs. These logs should have a simple result line indicating whether the tests succeeded. It is not helpful to have a large log that must be hand-verified to determine whether the test ran correctly. At a minimum, create the log so that it can easily be compared to a previous successful log.

Tips for Driver Life Cycle Testing

Consider these best practices for testing throughout the life cycle of your driver:

• Test throughout the development cycle. Test your driver as soon as possible by using tools such as PREfast, SDV, and Driver Verifier and the checked build of Windows.

• Test on a variety of platforms. Test your driver on the released versions of Windows on both uniprocessor and multiprocessor systems. If possible, test on systems that have different HALs.

• When you fix a bug, write a test. When you debug a problem, create a regression test that can be integrated into future testing of the driver. Make sure that your customer never sees that bug again.

• Always do regression testing. Do regression testing on your drivers against every new minor version of the framework and every new service pack of the operating system.

Errors in released drivers can be difficult to track down without good data from the field. The WER service provides a mechanism for users to send error reports to Microsoft that you can view on the Microsoft Windows Quality Online Services (Winqual) Web site. Through WER, you can direct users to Windows Update to download a newer version of your driver.

The WER service captures both hardware (that is, operating system) and software (that is, application) crashes, including information about drivers and applications as well as other modules such as controls and plug-ins that were running at the time of the crash. WER data includes a small crash dump file plus additional information depending on the type of error.

You provide Winqual with information to associate your driver's error reports with your company-sometimes called "mapping files." If WER has access to symbolic data, it can analyze the dump and look for the symbol that caused the crash, making it possible to categorize the errors more precisely.

The WER service also provides a mechanism you can use to offer users a solution to the error. When a user submits an error report, WER can show a message to the user, for example, to direct the user to a support Web site or to Windows Update.

See "Windows Error Reporting: Getting Started" on the WHDC Web site for details about WER-online at http://go.microsoft.com/fwlink/?LinkId=79792.