Run your driver against test suites including any applicable HCTs and third-party programs (ex: IOMeter for storage drivers). Build in unit tests that fully test the features of your driver.  Make it possible for these tests to be run by a script. This will enable you to run a daily smoke screen to see if any of the code you?ve added that day has broken pre-existing code.

Catch 'em While Coding

Functions in a driver that may be the first functions entered from user mode must validate their parameters. This check should always occur, regardless of whether your driver is built in the free or checked environment. It should not be done using ASSERT().  Such functions include your driver?s dispatch, AddDevice, DriverEntry, and Unload routines.

Beware of macros. Many of the APIs in the DDK are actually implemented as macros, and while they may be well written, it?s best to be cautious when using any macro. Never pass arguments to a macro that are expressions with side effects because the macro might just evaluate the expression multiple times. Use block notation for conditional expressions to avoid problems with poorly-written multi-statement macros.  For example:

if (flag) DoSomething(); 

If the function DoSomething() is a actually a multi-statement macro, then only the first statement in the macro would be conditionally executed. Be safe and use block notation for your conditional expressions, like:

if (flag) { DoSomething(); }

Remember to synchronize access to any resources that can be touched by more than one thread at the same time. It?s far better to experience a performance hit due to synchronization code and to have your code properly synchronized than to have code that?s a little faster but full of bugs.

Don?t touch paged memory at IRQL >= DISPATCH_LEVEL. Also, keep in mind that the UNICODE character tables are in paged memory, so if you attempt to use a DbgPrint() statement to print out a WCHAR/UNICODE string, the system will attempt to access paged memory in order to convert that string to text that can be sent to the attached kernel debugger. At DISPATCH_LEVEL, the statement DbgPrint(?%S?, unicodeString.Buffer); will cause a 0x0A bug check.

Avoid stack overflows. Every NT thread has two stacks, a user-mode and a kernel-mode stack.  The user-mode stack is quite large, but the kernel-mode stack is limited to 12K. To avoid overflowing the kernel stack, avoid deeply nested function calls, large local variables, and recursive calls. Also, some system calls (ex: registry I/O calls) consume quite a bit of stack. You may find it necessary to farm off some of your API calls to worker threads whose stacks are empty. You can use ASSERTs with IoGetRemainingStackSize() to quickly locate areas in your code where you might overflow the stack.

Avoid undocumented system calls. The behavior of these calls can change from one implementation to the next, and even between service packs. If you do use undocumented calls, document exactly which ones you used and the reasons you were forced to use them.

Be very careful to avoid deadlocks if your driver initiates new I/O that will pass through a device stack in which your driver participates. This is particularly true if your driver blocks on that new I/O.

Keep in mind that the data that an IRP?s MDL refers to can be changing while your driver owns the IRP.  An MDL?s data is not static.

if (Irp->PendingReturned) { IoMarkIrpPending(Irp); }

This is necessary in order to propagate the PendingReturned flag up to the top of the stack so that the IRP can be properly freed upon completion.

Zero-out (or use some other non-random value) structs that you are about to free. This will help you to identify when you are referencing memory that has already been freed. If you leave data in the struct, it?s likely that your code will not complain about the data that it finds in the memory when it uses a pointer that points to memory that?s already been freed. This technique is easily accomplished by #defining a new version of the free-memory function that, if DBG is defined, will zero-out the memory before freeing it.

Use structured exception handling whenever you access user-mode virtual memory such as in calls to MmMapLockedPagesSpecifyCache() or MmMapLocked Pages() when mapping pages into user address space, or calls to MmProbeAndLockPages(), MmProbeForRead() and MmProbeForWrite().

Discover 'em in the Debugger

Use cookies in your structs so that you can identify them when you?re poking around in memory or in a crash dump file.

If a driver has trampled over critical data structures in memory, the crash dump file may not be usable. When using a kernel debugger to analyze a crash dump file, use dumpchk.exe first to check the file to see if it?s corrupt or not.

Get the Bugs that Got Away

First, and most importantly, you should generate .PDB symbol files. While the XP DDK will generate .PDB files automatically, the NT4 and W2K DDKs will need explicit instructions in the SOURCES file. These .PDB files will enable you to perform source-level (rather than assembly) debugging. Do not release your .PDB files to the public as they can be used to generate the entire source of your driver.

Some kernel debuggers have the ability to show your source code mixed with assembly language while you are debugging. WinDbg cannot (to my knowledge) do this, but you can generate mixed source/assembly code output at build time in the form of .COD files. 

Another useful file to generate is a .MAP file which is a table of the mappings of symbols to addresses that were assigned by the linker.

You may also find it helpful to create a debugger extension DLL that will give you extra commands in WinDbg specifically tailored to debugging your driver. WinDbg comes with sample code for a simple debugger extension DLL. They?re very easy to write.

Conclusion

OSR would like to thank Nathan Bushman of PowerQuest Corporation for his guest article contribution. He can be reached at:  nate.bushman@powerquest.com