Writing Windows WDM Device Drivers

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

Build command line	MakeDrvr %DDKR00T% c: %WuMBook%wdm1sys free
Rebuild all options	-nmake /a
Output file name	Wdm1.sys
Browse info file name	obji386freeWdm1.bsc (W98/NT) objfrei386Wdm1.bsc (W2000)

MakeDrvr

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 %1insetenv.bat goto usage
call %1insetenv %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

Directories

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

In Windows 98, the free driver is in OBJi386freeWdm1.sys, with debug symbols in OBJ i386freeWdm1.dbg. The checked build products are in 0BJi386checked. The intermediate object files for both builds are in the OBJi386 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 OBJFREi386 and the checked build products are in OBJCHKi386. A complete rebuild is not required if you switch between free and checked builds.

Common Tasks

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.

The Wdm1 Driver Code

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

Wdm1.h	Driver header
Init.cpp	Entry and unload code
Pnp.cpp	Plug and Play and Power handling code
Dispatch.cpp	Main IRP dispatch routines