Chris Cant - Writing Windows WDM Device Drivers

The best way therefore is to use a Makefile project. This invokes a command line utility to build the driver. The downside of this approach is that some common tasks, such as adding a file to the compile list, have to be done in a different way, as described in the following text.

The book software projects are set up already to use the Makefile technique. This eventually invokes the build command as described previously. All the necessary build files must be set up correctly: SOURCES, makefile, the target directories, and possibly the makefile.inc and DIRS files.

You might find it useful to select the Visual Studio Tools+Options menu Editor tab "Automatic reload of externally modified files" checkbox so that changes to the build log files are loaded with no fuss.

When you make a new Makefile project, Visual Studio gives you two build configurations by default, "Win32 Debug" and "Win32 Release". I prefer to use the Build+Configurations menu to remove these and have configurations named "Win32 Checked" and "Win32 Free", instead.

For the free configuration, set the project settings as shown in Table 4.3. For the checked build, change "free" to "checked" in the build command line and the browse info filename.

If you installed the book software to a driver other than C: you will need to change the drive letter in the build command line.

The build command line runs the MakeDrvr.bat batch file, using the DDKROOT and WDMBOOK environment variables. The options –nmake /a are added to this command line if you request a complete rebuild in Visual Studio. The output filename is set so that the correct name is displayed in the build menu.

Table 4.3 Win32 Free configuration settings

When you ask Visual Studio to build your driver, the batch file MakeDrvr.bat, listed in Listing 4.4, is run. This is always passed at least four parameters: the DDK base directory, the source drive, the source directory, and the build type ("free" or "checked"). Any further arguments are passed straight to build.

MakeDrvr first does some basic checks on the parameters that are passed. It then calls the DDK setenv command to set up the environment variables correctly for the build target, changes directory to the source drive and directory, and finally calls build. The –b build option ensures that the full error text is displayed. The –w option ensures that the warnings appear on the screen output, so that Visual Studio can find them in the build Output window.

The screen output of the MakeDrvr command file appears in the Visual Studio Output window. You can then use F4 as usual to go the next error or warning.

Listing 4.4 MakeDrvr.bat

@echo off

if "%1"=="" goto usage

if "%3"=="" goto usage

if not exist %1\bin\setenv.bat goto usage

call %1\bin\setenv %1 %4

%2

cd %3

build –b –w %5 %6 %7 %8 %9

goto exit

:usage

echo usage MakeDrvr DDK_dir Driver_Drive Driver_Dir free/checked [build_options]

echo eg MakeDrvr %%DDKROOT%% C: %%WDMBOOK%% free –cef

:exit

The build output goes into the OBJ, OBJFRE, or OBJCHK subdirectories.

In Windows 98, the free driver is in OBJ\i386\free\Wdm1.sys, with debug symbols in OBJ\ i386\free\Wdm1.dbg. The checked build products are in 0BJ\i386\checked. The intermediate object files for both builds are in the OBJ\i386 directory. If you change from the free to checked targets, make sure that you do a "Rebuild all" to recompile all the source files with the correct debug preprocessor defines.

In Windows 2000, the free build object files and driver are in OBJFRE\i386 and the checked build products are in OBJCHK\i386. A complete rebuild is not required if you switch between free and checked builds.

As you are using a Visual Studio Makefile project, these common tasks must be done is a different way.

Add File to Project

If you add a file to your project, you must add it to the SOURCES file for it to be built.

Make Browse Information

Source browser information is generated alongside the target executable if the SOURCES file contains this line.

BROWSER_INFO=1

Build Steps

Various additional build steps can be defined in a makefile.inc file if the SOURCES file contains one or more of the NTTARGETFILE0, NTTARGETFILE1, or NTTARGETFILES macros.

The results of any additional build steps are not shown in the Visual Studio output window, but only in the build.log file. The build does not necessarily stop if one of these steps fail.

You could also alter MakeDrvr.bat to do tasks that are common to all your driver projects.

Compiling a Single File

You cannot compile a single file in Makefile projects.

Table 4.4 lists all the source files used by the first driver called Wdm1. Table 4.5 lists all the build files that have already been described. In W2000 the build output files have slightly different names. These files are on the book CD-ROM.

This chapter looks at only some of the source files. As far as possible, the minimum possible functionality has been implemented in Wdm1. For example, a stub function has been written to handle Win32 create file requests. These stub functions usually make each request succeed.

If you were to put this Wdm1 driver to the test, it would not work in some circumstances. The succeeding chapters explain how the driver works and how its functionality has been enhanced to make it work better, as well as showing how to call the driver from Win32 code.

Table 4.4 Wdm1 source files

Table 4.5 Wdm1 build files

The code includes some directives to the compiler that need some explaining.