WinDrvr : Driver Design

Coding Guidelines

DonBurn — Sun, 24 Jun 2007 23:59:00 GMT

When I get a new client, I ask for a copy of their driver coding guidelines. Typically I get one of several responses.

· We trust our developers to do the right thing.

· The last time we brought this up there was almost open revolt.

· They hand me a corporate standard for coding applications, most of which is worthless for drivers.

Whether companies recognize it or not, they need a set of coding guidelines for drivers. There are a lot of ways of doing things in drivers that can cause problems, and a good set of guidelines can help. Consider some of the following areas:

· C++ - There can be an argument for this in many cases, but if C++ is used for drivers, there needs to be limits placed upon the language for it to work in the kernel.

· Undocumented or unusual routines – What is your company’s policy on the use of undocumented kernel interfaces? What about routines not normally used in the kernel, but documented for user space? How about functions from the IFS kit for a regular driver? There are a lot decisions to make here.

· WDM, WDF or 3^rd party toolkits – What is your policy on drivers: should they be the traditional WDM model, the new WDF models or a 3^rd party model?

· Development Environment – What do you require for a development environment? This should be simple; namely a specific version of the DDK/WDK, but if you don’t spec it you can get anything.

· Windows Logo – Do you want your drivers to have a Windows Logo? This impacts the routines, models, and methodology for developing drivers.

· Static Verification tools – What is your policy on code passing static and dynamic verification tools? Do you require code to be PREfast clean? Does your code need to run through Static Driver Verifier? Do you require annotations to aid the above tools in finding bugs? Do you use PC-Lint and do you have your own definitions file?

· Testing – Does the code need to pass Driver Verifier? For Server 2003, does your code need to pass Call Usage Verifier? Is there a code coverage tool and standards to be met? What other tests are required?

· Diagnostics – What is your model for tracing and debug prints? Do you require event logging? Do you expect data to be presented to the performance monitor? Is there information going to Windows Management Instrumentation?
· Coding style – This is the one that causes the biggest fights. You should probably not be dictating the location of braces or indentation, but there are things that make code easier to review or for the next person to work on it.

The above is not a complete list, but even more needs to be considered. If you do not have the resources in-house, consider engaging a consultant to develop the guidelines based on your current practice.

You do not want to end up like one firm I know that hired a contractor to develop a driver. When the driver was delivered, the company discovered the contractor had used a toolkit the firm did not own and would cost over $100,000 to buy for the developers and train them on. The choice between slipping the product schedule and buying the tool was not a pleasant one. With some preparation up front in specifying coding guidelines, such scenarios can be prevented and time and money saved in the end.

Tag, you're it

DonBurn — Fri, 15 Jun 2007 23:31:00 GMT

I’ve been spending the last couple of days tracking down a bug in a driver I am writing. The effort reminded me of how great tags on memory allocations and frees can be. Also, the work reminded me that there are at least a couple of features Microsoft does not promote and I rarely see.

For the uninitiated, tags are a four character value that is passed as an argument in memory allocation calls. The tag gives you a way to identify what the memory was allocated for by having a different tag for each common structure allocated. Here is a common problem: many driver developers commonly assume that they have only one tag for their whole driver because so many of the common samples do this. There is nothing stopping you from having multiple tags, and in fact there is a strong reason to have them.

Right now I am developing a file system mini-filter that has twenty-one different tags it uses for allocations. All the major buffer types and context blocks each have a unique tag for their allocations and frees.

Yes, I said frees. Part of the reason to have multiple tags is that you can also put the tag on the free of the memory by using the call ExFreePoolWithTag. Unfortunately, this call has been described as worthless in Walter Oney’s Programming the Windows Driver Model and is incorrectly documented by Microsoft.

The value of ExFreePoolWithTag is when you combine it with a tag with the PROTECTED_POOL bit set. This bit requires that you free the memory with ExFreePoolWithTag, and the OS will bug check if the memory being freed does not have the matching tag. Unfortunately, PROTECTED_POOL is not documented except in include files, and is not used by any Microsoft sample. Using ExFreePoolWithTag with PROTECTED_POOL tags gives you an automatic check that you are freeing what you intended to.

You do have to be careful on memory you allocate that the system will be freeing, since Windows will not know what tag you are using, so the system frees everything without tags. For everything except the rare instance where the system frees the memory, using multiple tags with PROTECTED_POOL is worthwhile.

Crossing the Undocumented Line

DonBurn — Sun, 27 May 2007 16:32:00 GMT

As a consultant who has more than once taken on projects Microsoft has said are impossible, many people assume I often use undocumented calls in Windows in my work. In fact, I try to avoid them if at all possible, and am extremely careful in crossing the undocumented line.

A developer should ask a set of questions when considering using an undocumented technique; these are:

Is it really needed? Before anything else, ask yourself if there is any other way to do this. Be sure to not constrain your design when you ask this question. For instance, requiring something be done in the kernel may force an undocumented technique where building a helper application could allow a documented approach.
How undocumented is it? There is a lot of variation here; there are plenty of undocumented calls that are never mentioned by Microsoft. These I consider pretty undocumented even if there are examples on the web.

There are calls that have been in the Microsoft DDK include files for years, but are not documented. For example, a number of the ZwXXX calls have options that are not described in the documentation, but are in the includes with all the needed data structures.

Another variant of undocumented is the call that is documented in later OS’s but works for your driver in previous versions. In the early days of the DDK, there were calls in the samples that were not documented. These calls are not completely safe, but they are better than the totally undocumented calls.

Which OS’s require the undocumented stuff? If you are looking at an undocumented call for an older OS, the function you need in later OS’s is not present, so you are probably safer than expecting a call to be there in the future.
What is the scope of the input and usage of the undocumented stuff? If you are using the undocumented calls in a constrained environment you are in a safer position than a having a widespread and flexible use. It is hard to test any piece of code, but if the inputs or patterns of use vary, the testing of this area just got harder.
What is the fallback plan? If you do go ahead and do this, what will you do if it breaks tomorrow? Has your design kept the undocumented stuff limited so it can be replaced in the code? Is there likely to be an alternative for the replacement? What is the plan if there is no replacement?

If you decide you have to cross the line and use an undocumented call, there are some things you should be doing:

· Let the customer know – Document the call and the answers to the above questions to the customer or your management. Crossing the line should be a decision made by more than just the developer.

· Plan for a long testing cycle – You have chosen to use something you cannot rely on, so your testing pain just went up. You really need to test all the likely OS configurations the end user could have. This means not just testing on the current version of a Windows OS, but instead the base, all service packs, and the current version , i.e., all the latest hotfixes and downloads. For 32-bit Windows, that is sixteen full tests if you want to support Windows 2000 up to Vista!

There are times to cross the line, but be sure you have a plan and a strong justification before you enter the undocumented territory.

Using the event log in your driver

DonBurn — Mon, 19 Feb 2007 22:02:00 GMT

I wrote previously that drivers should use the event log. This time I am going to give some things to consider when using events. The challenge for using the event log is that many components use it poorly. The two common problems are superfluous messages and lazy definitions.

The event log is commonly configured as a circular log with a limited capacity. Thus, having a bunch of superfluous messages can cause the important events that lead up to a failure to be lost. If you want to put in things like the driver started or stopped, provide a registry value or other control so these can be disabled.

The second problem, lazy definitions, happens because building the message catalog where the event strings are stored and setting up the registry for it require additional steps. Developers looked around and found that a number of the common Microsoft error codes took a string for the log entry, and decided to use the Microsoft definition instead of their own. This is a poor approach for two reasons. First, since all your errors are coded as the same event, this makes it hard for tools to look for problems in the log. Second, the event log is designed for internationalization but the strings you dump from your driver will all be in one language.

For internationalization, consider making the message catalog where the text of the messages resides a separate file, rather than including it in the device driver. The advantage of this is that you can provide the components needed for a support organization to add a new language without having to sign the driver again.

So what should go in the event log? Some obvious things are:

· Failures in DriverEntry, AddDevice and Unload – In all these cases, there is no user request to which to report the problem.

· Resource failures – These include a malfunction in the hardware or supporting software (for instance, a service that supports the driver) that impacts many requests.

· Anomalous behavior – This is anything that is unexpected, whether it fails a request or not. If something you really didn’t expect occurs, even if the driver handles it, log it.

My overall message is that you should add the event log to the diagnostic capabilities you provide your support people and your customers. If you already do this, great! And if you already have working guidelines for event log use, please share them with a comment to this blog.

Why your driver should use the event log

DonBurn — Sun, 18 Feb 2007 14:34:00 GMT

Do you use the event log in your driver? Event logging should be standard in almost every driver, yet few drivers support logging. Event logging is the place to record anomalous conditions and events that are detected by your code. Specifically, it is the recognized way to report errors that are not related to a particular request to the device.

The event log consists of small records about events of interest. The record is based on an NTSTATUS code, whether it is a standard code or a custom status code for your software. Think of the event log as a series of alerts to inform you of what is happening on the system. If you haven’t looked at it lately, open the event viewer from Administrative Tools, and look at the entries since the last boot of your machine.

There are articles for developers that contend that no one reads the event log. Yes, the normal user does not look at it, but system administrators certainly do. When there is a problem with a system, the event log is the first place admins will look to establish a chronology of what happened and possibly see what failed. The event log is also integrated into many network management tools that administrators use to monitor system health.

So why don’t more drivers use the event log? Part of the reason for this is Microsoft. The DDK used to provide a specific sample to illustrate logging, but this was removed years ago. Worse, some Microsoft developers do not understand the use of the event log. A few years ago a Microsoft talk confused the purpose of Event Logging with the more recent Event Tracing for Windows (ETW). ETW is a great capability, but it is designed to provide detailed diagnostics for the developer, not simple alerts for the administrator.

So if you are not using the event log in your drivers, ask yourself or your developers, why aren’t you? If you are using the event log, there are a number of things to consider, but that needs to wait for another post.