Let’s build production drivers with full symbolic debugging information that take up no more space than the standard Windows NT DDK build process for production drivers, which of course have nearly zero symbolic debugging information in them. And, lets make sure that our fully debugable production drivers are pretty much identical as binary executable images to the essentially undebugable drivers that are the default output from the NT DDK build process.

Why? Consider this scenario: you have been developing your NT kernel driver for some time. It is nearing the point where the driver is going to be released (an Alpha release for example) outside of your own insular internal test environment. You have been doing most of your testing using the checked version of your driver, and everything works fine. Now you switch over to the free version of your driver, install it on your test system, and fire up your regression test suite. Two and one half seconds into the stress test part of the regression test your test system crashes with a hideous Blue Screen of Death. “Gadzooks!,”  you exclaim, and you retry the exact same test with your favorite debugger and the checked version of your driver installed. The test works fine, no problems. You repeat the process, same results. The production version of your driver crashes while the debug version sails through your tests. Your debugger shows a function in your driver on the stack at the time of the crash, but any attempts to set a breakpoint in the source code for this function, or to symbolically examine the local variables for the function are useless.

Your production driver doesn’t have any symbolic debugging information.

But First Some Review

As you all are aware, the NT DDK comes with a set of tools for building device drivers. Unfortunately, while the tools work just fine, the documentation for those tools is rather lacking. This article explores part of the undocumented territory that exists within the driver development process.

The core of the toolkit is the build utility itself. Build is a front-end to nmake, Microsoft’s version of the traditional Unix make utility. Various files, that the developer either creates as part of the development process, or that are standard parts of the DDK itself, direct build’s operations. The most familiar of these files are the SOURCES file and the DIRS file. The SOURCES file simply defines values for a set of standard make macros that are then included into a standard makefile template used to build all device drivers.

A typical use of the SOURCES file is to simply enumerate the list of source code files that constitute a driver. Actually the build process can create many types of executable objects, not just NT kernel device drivers, so at a minimum the SOURCES file must indicate what type of object is being built. In addition the SOURCES file must indicate where the output of the build process should go, what the target name is, and it must list the set of source files that generate the executable.

A minimal device driver SOURCES file is as follows:

The DIRS file directs the build utility to build in sequence a list of subdirectories. Build will process each directory listed in a DIRS file. If it finds a SOURCES file in a directory it uses that to build the contents of the directory. If there is a DIRS file but no SOURCES file then build will recursively use the DIRS file of the subdirectory to process the new list of subdirectories. Build can easily re-build an entire complex software project consisting of many applications, libraries, and device drivers. It is, of course, the utility used by the Windows NT development team at Microsoft to build the software for Windows NT itself.

Enough review already. As you know, your driver can be built in one of two forms: checked or free. The checked version of your driver has the DBG compilation constant set to 1 so that all code wrapped in #if DBG - #endif constructs is included in your source code. In other words this is the debug version of your driver. If you build the free version of your driver DBG is set to zero, so all of your code wrapped within #if DBG - #endif constructs is not included in your driver.

Enough review already. To facilitate your progress, the checked and free versions of your driver have some other differences. Compiler optimization (otherwise known as code mangling) is turned off in the checked version of your driver. Consequently, even if you don’t have any DBG-enabled code at all in your driver the free version of your driver is a different executable than the debug version. But the difference I like most of all is that the free version of your driver has what is quaintly referred to in the documentation as minimal symbolic debugging information. By minimal they mean that you will not get more symbolic information out of your driver than the names of functions. Any debugging of your production driver will be through an assembly language view of the world.

The Gory Details

Let’s actually look at what the compiler settings are for both the checked and the free version of a driver.

Here is the compiler command line from a checked build of a simple driver:

Setting this environment variable causes BUILD to generate .obj files and image files with full symbolic debugging information.”

This is a clue. The suggestion is to set an environment variable – which means you would have to change your “free build” icon settings. Every time you installed a new version of the DDK you would have to re-create you build environment again, and it would be difficult to share this process with other developers or put this process under version control. A modification to the SOURCES file for your project would be a much better way to go.

The checked build environment as supplied by the NT DDK sets NTDEBUG to ntsd and NTDEBUGTYPE to both. The free version does not set either of these environment variables. Makefile.dev (DDK\inc\makefile.def,) the global makefile used by build to create NT executables uses these variables to set up the compiler and linker debugging options discussed above and also to decide if a checked or free version of the driver is being built.  The italics are intentional. The procedure recommended by the DDK documentation quoted above will not work.

Look at the platform specific portion of the global makefile, Makefile.plt (DDK\inc\makefile.plt.) Right near the top of this file are the lines seen below.

!if ("$(NTDEBUG)" == "") || ("$(NTDEBUG)" == "retail") || ("$(NTDEBUG)" == "ntsdnodbg")
FREEBUILD=1
!else
FREEBUILD=0
!endif

If you set NTDEBUG to the value “ntsd”, either in your build environment or simply by added the line

to your sources file, then you will get, free of charge, the checked version of your driver with the DBG constant set and code optimization turned off.

What you want to do instead is to set NTDEBUG to “ntsdnodbg”. It would also be nice to have NTDEBUG set in the SOURCES file itself. It doesn’t do any good to put the line:

in your SOURCES file as this will result in always generating a free version of your driver, complete with code optimization, even when you are trying to build the checked version of your driver. The DBG constant will not be defined.

Luckily, There is a Simple Work-Around

Here is what I put in my driver SOURCES file:

# turn these on to produce symbolic information while
# leaving the DBG flag off
# BUT ONLY IF WE ARE NOT BUILDING THE CHECKED BUILD
#
 
!IF "$(DDKBUILDENV)" != "checked"
 

NTDEBUG=ntsdnodbg
NTDEBUGTYPE=both
USE_PDB=1
 
!ENDIF

By testing the independent environment variable DDKBUILDENV the sources file can conditionally set flags that only affect either the checked version or the free version of the driver.

As it turns out, the NTDEBUGTYPE flag is also required if we want our free driver to have the same debug format as its checked equivalent. This is the flag that is used to set the linker –debugtype switch. The test in Makefile.def is as follows:

!IF "$(NTDEBUGTYPE)" == "windbg"
LINKER_DBG_TYPE = -debugtype:cv
!ELSEIF "$(NTDEBUGTYPE)" == "ntsd" || "$(NTDEBUGTYPE)" == "coff" || "$(NTDEBUGTYPE)" == ""
LINKER_DBG_TYPE = -debugtype:coff
!ELSEIF "$(NTDEBUGTYPE)" == "both"
LINKER_DBG_TYPE = -debugtype:both
!ELSE
! ERROR NTDEBUGTYPE macro can one of "", "ntsd", "coff", "windbg" or "both"
!ENDIF

If we don’t set NTDEBUGTYPE build is going to generate COFF format symbols, which is not what we want.

You might notice that there is one more flag set in the excerpt from my SOURCES file above. The USE_PDB flag is set. If this flag is not set then the symbolic information is embedded into the driver executable image itself. This can result in an executable image that is at least two or three times larger than the equivalent standard free version driver. In addition, you might very well not want anyone to be able to look at all of the nice descriptive symbols you gave your functions variables and parameters.

There are manual tools to strip the symbols out of an executable file into a separate debug file, see the documentation on rebase for details. A much easier way is to convince the linker to produce .PDB files instead, as is done in the standard Visual C++ development environment. Windbg (circa January 1998 vintage, other versions are a mystery,) is happy to use PDB files for symbolic debugging, and SoftIce undoubtedly is able to do the same.

To wrap up, all you have to do to create production versions of your device driver that are both fully optimized and fully source code debugable is to add five lines to your SOURCES file. The result is a free version of your driver that:

·         contains no extra symbolic information (its all in the PDB file,)

·         uses the same compilation switches for code generation, so the actual executable is identical,

·         and takes up no more space in the kernel than the original production version would have.

Speaking of bugs, my version of Word, the ponderous Word97 would prefer to change debugable to debatable, which I figure is debatably a bug.