Writing Windows WDM Device Drivers

The build process also generates a file called Wdm1.dbg with the debug symbols in the OBJi386free directory.

Windows 2000

In W2000, build keeps the free and checked build object files separate. If the TARGETPATH is OBJ, the free build x86 object files and the final driver go in the OBJFRE i386 directory. The checked build object files and driver go in the OBJCHKi386 directory.

Wdm1 Directories

The end result is the following series of subdirectories for Wdm1.

Directory	Contents
OBJ	Has build list of files to build in _objects.mac
OBJi386	W98 Compiled object files
OBJi386free	W98 Free build Wdm1.sys
OBJi386checked	W98 Checked build Wdm1.sys
OBJFREi386	W2000 Free build objects and Wdm1.sys
OBJCHKi386	W2000 Checked build objects and Wdm1.sys

Other build Steps

Another makefile called makefile.inc is invoked if you use certain optional macros in the SOURCES file. Table 4.2 shows the macro name and when the make target is invoked.

Table 4.2 SOURCES optional macros

SOURCES macro name	When invoked
NTTARGETFILE0	after dependency scan
NTTARGETFILE1	before linking
NTTARGETFILES	during link

Listing 4.3 shows the standard makefile.inc that is used in all the book software projects.

Listing 4.3 Book software projects makefile.inc

PostBuildSteps: $(TARGET)
!if '$(DDKBUlLDENV)'='free'
 rebase –B 0x10000 –X . $(TARGET)
!endif
 copy $(TARGET) $(WINDIR)system32drivers

The line in the Wdm1 SOURCES file that says NTTARGETFILES=PostBuildSteps ensures that the target PostBuildSteps is built during the link process. As the PostBuildSteps target depends on $(TARGET) — the driver executable — the build commands for PostBuildSteps are carried out after the driver is built. The PostBuildSteps output is displayed in the build.log file. Note that problems in PostBuildSteps may not evident unless you inspect this file.

The actual post-build steps in makefile.inc do two jobs. First, the rebase utility is run on the driver executable for free builds, and the driver is copied to the Windows system32drivers directory. Copying the driver does not mean that it is installed.

rebase strips any remaining debug symbols that are left, even in the free driver executable. The base load address is kept at 0x10000 and the symbols are put in the .dbg file in the current directory.

DIRS File

The final main feature of build is that it can recursively build files in other directories. If a DIRS file is present, build looks at the DIRS directive in there for a list of directories to build. These directories may themselves contain further DIRS files.

The book software base directory has a DIRS file with the following line:

DIRS=Wdm1 Wdm2 WdmIo UsbKbd HidKbd DebugPrint PassThru

Running build in the book software base directory will compile the drivers in all these directories. The companion Win32 user mode applications are not built by this process.

The directories listed in the DIRS directive must be only one level below the current directory. Therefore, the Wdm1 directory has a DIRS file that instructs build to go to the SYS subdirectory.

VC++ Projects

You can set up VC++ to build drivers from within Visual Studio. It is possible to configure a project's settings so that Visual Studio can compile your driver directly. However, it is laborious changing all the settings and is error prone. The final problem is that Microsoft might change driver compile or link requirements in the DDK standard makefile. Such changes would not be reflected automatically in your settings.

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.

Makefile Build Environment

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.