KMDF Example: Building the Osrusbfx2 Sample

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

image from book
 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 
image from book

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:


    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:


    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.


    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:


    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.


    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.


    Optional. Indicates that the project has a 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:


    Optional. Specifies folders that contain shared header files.


    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.


    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:


    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.


    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.


    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.


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

Makefile and 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 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 file.

Listing 19-5: The Osrusbfx2 file

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

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 directives. The example in Listing 19-6 is 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 file

image from book
 _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 
image from book

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 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.

Developing Drivers with the Microsoft Windows Driver Foundation
Developing Drivers with the Windows Driver Foundation (Pro Developer)
ISBN: 0735623740
EAN: 2147483647
Year: 2007
Pages: 224

Similar book on Amazon
Windows Internals, Part 1: Covering Windows Server 2008 R2 and Windows 7
Windows Internals, Part 1: Covering Windows Server 2008 R2 and Windows 7
Windowsu00ae Internals: Including Windows Server 2008 and Windows Vista, Fifth Edition (Pro Developer)
Windowsu00ae Internals: Including Windows Server 2008 and Windows Vista, Fifth Edition (Pro Developer)
Advanced Windows Debugging
Advanced Windows Debugging
The Windows 2000 Device Driver Book: A Guide for Programmers (2nd Edition)
The Windows 2000 Device Driver Book: A Guide for Programmers (2nd Edition) © 2008-2017.
If you may any questions please contact us: