Developing Drivers with the Windows Driver Foundation (Pro Developer)

This section is a walkthrough that creates a checked build of Osrusbfx2 for Windows Vista. It also discusses the details of some of the supporting files.

Sources File for Osrusbfx2

The Sources file contains most of the project-specific information that the Build utility uses to build the project. The Sources file consists of a series of directives that assign project-specific values to a set of macros and environment variables. The example in Listing 19-4 shows the contents of the Osrusbfx2 Sources file, edited to remove the comments. The example is a typical Sources file for a simple KMDF driver.

Listing 19-4: The Osrusbfx2 Sources file

TARGETNAME=osrusbfx2 TARGETTYPE=DRIVER KMDF_VERSION=1 INF_NAME=osrusbfx2 MISCFILES=$(OBJ_PATH)\$O\$(INF_NAME).inf NTTARGETFILES= INCLUDES=$(INCLUDES);..\inc TARGETLIBS= $(DDK_LIB_PATH)\ntstrsafe.lib SOURCES=driver.c \ device.c \ ioctl.c \ bulkrwr.c \ Interrupt.c \ osrusbfx2.rc ENABLE_EVENT_TRACING=1 !IFDEF ENABLE_EVENT_TRACING C_DEFINES = $(C_DEFINES) -DEVENT_TRACING RUN_WPP= $(SOURCES) \ -km \ -func:TraceEvents(LEVEL,FLAGS,MSG,...) \ -gen:{km-WdfDefault.tpl}*.tmh !ENDIF

The next section gives brief descriptions of the macros and environment variables used in the Osrusbfx2 Sources file. Many are the same as those used for UMDF drivers. In that case, the definition is abbreviated.

Macros Used in the Sources File for Osrusbfx2

This section discusses the macros and environment variables in the Fx2_Driver example.

KMDF Version Number

The following macro defines the KMDF version number:

• KMDF_VERSION

  Required. Specifies the KMDF major version number. The example in Listing 19-4 uses KMDF version 1.

Standard Targets

The following macros describe the standard build targets:

• TARGETNAME

  Required. Specifies the name to be used for output files such as the project's .sys and .pdb files. In Listing 19-4, this is specified as osrusbfx2.

• TARGETTYPE

  Required. Specifies the type of binary to be built. In Listing 19-4, DRIVER indicates that the build should produce a kernel-mode driver.

Custom Targets

The following macros describe custom targets, such as an INF file that the Build utility produces:

• INF_NAME

  Optional. Specifies the file name for the INF file that is generated from the project's INX file. In Listing 19-4, the file is to be named Osrusbfx2.inf.

• MISCFILES

  Optional. Specifies where to place the INF file that is generated. In Listing 19-4, the INF file is placed in the output folder with the other output files.

• NTTARGETFILES

  Optional. Indicates that the project has a Makefile.inc file. No value is specified in the example in Listing 19-4; instead, the output folder is specified by INF_NAME.

Source Files, Headers, and Libraries

The following macros describe the source files, headers, and libraries used to build the targets:

• INCLUDES

  Optional. Specifies folders that contain shared header files.

• SOURCES

  Required. Specifies the project's source files. By default, the files must be on a single line. The backslash (\) is a line-continuation character that allows the files to be listed on separate lines.

• TARGETLIBS

  Optional. Specifies any libraries to be used. KMDF drivers do not require any .lib files, but this project uses the Ntstrsafe.lib safe string library.

Build Configuration

The following macros describe the build configuration:

• C_DEFINES

  Required for Unicode builds. Specifies any compile-time switches that must be passed to the compiler. For Osrusbfx2, the macro specifies a required flag for event tracing.

• ENABLE_EVENT_TRACING

  Optional. A custom macro-defined by the sample-that enables WPP event tracing. To disable event tracing in this sample, comment out or delete the line. Chapter 11, "Driver Tracing and Diagnosability," provides information about event tracing.

• !IFDEF/!ENDIF

  Optional. Works much like the C equivalent. The code between the macros is run only if the condition is satisfied. In the example in Listing 19-4, the two directives are run only if WPP tracing is enabled.

• RUN_WPP

  Optional. Runs the WPP preprocessor. The gen option specifies the WDF template file, which supports hundreds of framework-specific tracing messages.

Makefile and Makefile.inc for Osrusbfx2

The contents of Makefile are the same for all driver projects, as discussed in "Build Utility Supporting Files" earlier in this chapter. Osrusbfx2 also includes an optional file-Makefile.inc. This file contains some additional make directives that handle a target that is not covered by Makefile.def: converting the project's INX file into an appropriate INF file. The example in Listing 19-5 shows the contents of Osrusbfx2's Makefile.inc file.

Listing 19-5: The Osrusbfx2 Makefile.inc file

_LNG=$(LANGUAGE) _INX=. STAMP=stampinf -f $@ -a $(_BUILDARCH) $(OBJ_PATH)\$O\$(INF_NAME).inf: $(_INX)\$(INF_NAME).inx copy $(_INX)\$(@B).inx $@ $(STAMP)

The file in Listing 19-5 contains the following four directives:

• _LNG specifies the language. The WDK default value is U.S. English.

• _INX specifies the location of the INX file as the project folder.

• STAMP specifies the command that actually produces an INF file from the specified INX file.

• OBJ_PATH specifies where to place the target file.

KMDF drivers can support WMI, which requires additional Makefile.inc directives. The example in Listing 19-6 is Makefile.inc from the KMDF Featured Toaster driver sample. The first half of the example is for the project's INX file and is identical to the example in Listing 19-5. The latter half of the example in Listing 19-6 has the directives for building the project's MOF resource file.

Listing 19-6: The KMDF Featured Toaster Makefile.inc file

_LNG=$(LANGUAGE) _INX=. STAMP=stampinf -f $@ -a $(_BUILDARCH) $(OBJ_PATH)\$(O)\$(INF_NAME).inf: $(_INX)\$(INF_NAME).inx copy $(_INX)\$(@B).inx $@ $(STAMP) mofcomp: $(OBJ_PATH)\$(O)\toaster.bmf $(OBJ_PATH)\$(O)\toaster.bmf: toaster.mof mofcomp -WMI -B:$(OBJ_PATH)\$O\toaster.bmf toaster.mof wmimofck -m -h$(OBJ_PATH)\$O\ToasterMof.h -w$(OBJ_PATH)\$O\htm $(OBJ_PATH)\$(O)\toaster.bmf

Most KMDF drivers can use these examples with only minimal alteration, mainly to change the file names in the WMI section. If your driver does not support WMI or use an INX file, you can omit Makefile.inc entirely.

How to Build Osrusbfx2

The following procedure shows how to build Osrusbfx2.

To Build Osrusbfx2

1. Open the Windows Vista and Windows Server Longhorn x86 Checked Build Environment console window.

   The build environment window opens in the %wdk% folder.

2. Use cd to move to the project folder at %wdk%\src\kmdf\osrusbfx2\sys\final.

3. Build the project by running the following command:

   • build.exe -ceZ

This is not the only way to build the project, but it uses the most common flags. The output files go in the project's objchk_wlh_x86\i386 subfolder.