PFD and SDV Clean: Improving the Quality of Headers and Samples in the WDK and Windows 7 (Part 1 of 6)

Overview:

With the Windows 7 development process drawing to a close and the product slated to hit the shelves on October 22nd, we’re starting to look back and review the work our team has done. One of our work items – a major one – was a quality-driven initiative we called “PFD/SDV Clean for Drivers”.

Introduction:

This article from 2006 talks about our team using Static Driver Verifier (SDV) to find bugs in WDK Samples before the kit was published and get them addressed by the teams that owned the code. That effort translates into savings for any vendor using this code for their own devices, as they don’t have a potentially very difficult bug to track down before (or after!) the release of their product. That further benefits the end consumer in terms of stability of the OS and devices that using that sample code. This thought process serves as the mission statement for the PFD/SDV Clean initiative. Our goal was to establish a “quality bar” for headers and samples in the Win7 WDK, and further extend this bar to the Microsoft authored drivers that ship inbox with Windows 7. The remainder of this and next few blog posts details the work our team did to make this effort successful.

PFD Clean (Annotating Headers):

Those of you familiar with PFD know that it is (basically) a function-level code checker that relies upon annotations for accuracy. It was first included as a tool in the 2003 SP1 DDK, and I am of the opinion that it remained relatively anonymous to most of the developers using those kits. The addition of OACR to the WDK build environments changes all of that. OACR, which stands for “Microsoft Auto Code Review”, is a tool that resides in the background once a build environment is opened. Once code is compiled, it uses idle time to scan that compiled code using the various code review plug-ins, one of which happens to be PREfast for Drivers (PFD). Once OACR finishes scanning, it throws a pop-up box in the corner to show you any issues it considers warnings (bad) or errors (worse) with your recent compile. This occurs with any build commandin the standard WDK environments, no special commands or switches required:

This addition meant scanning “for free” for everyone that uses the Win7 WDK. It also meant that if we wanted developers to consider those warnings and errors as anything more than a nuisance, we needed to make sure the code checker was as accurate as possible. Thus began phase 1 of the “PFD Clean” initiative, annotation of public driver APIs.

The RC version of the WDK includes 254 files in the inc\ddk folder, and 48 in the inc\wdf\* folders (Windows Driver Framework). A number of these header files are compilations of smaller headers located in different places of the Windows source, because they are a group of API that are used for a single purpose – wdm.h, for example. This means that multiple developers create the content that ultimately ends up in wdm.h, and each individual one gets a “work item” to add annotation to the APIs that they own. In all, to cover the files in the kit that were thought to relate in some way to a driver (which includes some in inc\api as well), nearly 600 work items were filed asking for review and changes to the header files that are published into the WDK – one for each header file.

Quick sidebar: It became evident very quickly that asking developers to add annotation to their code would yield far better results than our local team reviewing and annotating their code: the ramp-up time on the annotation language was far less than any ramp-up time needed to become familiar and comfortable with the code to be annotated. The additional benefit of the developers gaining knowledge of this valuable technology was not ignored in making this decision, either.

The overall response to this task was fantastic – every header file that even remotely relates to drivers was reviewed and annotated appropriately (where/when needed). Combined with OACR in the build environment, this creates immediate impact for any vendor that will use the Win7 WDK to build their driver. If their code is calling one of these API in a manner that it shouldn’t be called in, the OACR pop-up says so. In the next post (part 2 of the “Clean” series), I’ll provide an example of how these annotations and OACR combine to catch a potentially painful bug in the next post.