Developing Drivers with the Windows Driver Foundation (Pro Developer)

This section provides a walkthrough that creates a checked build of Fx2_Driver for Windows Vista and discusses the details of some the supporting files mentioned in the previous section.

Sources File for Fx2_Driver

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

Listing 19-2: The Fx2_Driver Sources file

UMDF_VERSION=1 UMDF_MINOR_VERSION=5 TARGETNAME=WUDFOsrUsbFx2 TARGETTYPE=DYNLINK USE_MSVCRT=1 WIN32_WINNT_VERSION=$(LATEST_WIN32_WINNT_VERSION) _NT_TARGET_VERSION=$(_NT_TARGET_VERSION_WINXP) NTDDI_VERSION=$(LATEST_NTDDI_VERSION) MSC_WARNING_LEVEL=/W4 /WX MSC_WARNING_LEVEL=$(MSC_WARNING_LEVEL) /wd4201 C_DEFINES = $(C_DEFINES) /D_UNICODE /DUNICODE DLLENTRY=_DllMainCRTStartup DLLDEF=exports.def INCLUDES=$(INCLUDES);..\inc;..\..\inc SOURCES=\ OsrUsbFx2.rc \ dllsup.cpp \ comsup.cpp \ driver.cpp \ device.cpp \ queue.cpp \ ControlQueue.cpp \ ReadWriteQueue.cpp TARGETLIBS=\ $(SDK_LIB_PATH)\strsafe.lib \ $(SDK_LIB_PATH)\kernel32.lib \ $(SDK_LIB_PATH)\advapi32.lib NTTARGETFILES=$(OBJ_PATH)\$(O)\WUDFOsrUsbFx2.inf MISCFILES=$(NTTARGETFILES) RUN_WPP= $(SOURCES) -dll -scan:internal.h

The following section gives brief descriptions of the macros and environment variables used in the Fx2_Driver Sources file.

 Tip   See "Utilizing a Sources File Template" in the WDK for a complete list of the possible contents of a Sources file, plus links to documentation about environment variables and macros-online at http://go.microsoft.com/fwlink/?LinkId=79350.

Macros Used in the Sources File for Fx2_Driver

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

UMDF Version Numbers

The following macros define the UMDF version number:

• UMDF_VERSION

  Required. Specifies the UMDF major version number, which is 1 in the example in Listing 19-2.

• UMDF_MINOR_VERSION

  Required. Specifies the UMDF minor version number, which is 5 in the example in Listing 19-2.

These macros define the UMDF version numbers, which control the following:

• Which headers the driver uses.

• The major version of UMDF to which the driver is bound.

  If a new major version of the framework is installed on a user's system, the old version remains. All drivers that are bound to that version continue to use the old version.

• Minimum minor version of UMDF to which the driver can be bound.

  You can specify only a minimum minor version. If the framework on a user's system is upgraded to a newer minor version, the old version is removed and the driver automatically binds to the new version.

• Which UMDF co-installer is required.

  The co-installer version must match the major and minor version numbers.

Chapter 20, "How to Install WDF Drivers," provides more information on WDF co-installers and versioning.

Standard Targets

The following macros describe the standard build targets, such as the driver binary:

• TARGETNAME

  Required. Specifies the name to be used for output files such as the project's .dll and .pdb files. In Listing 19-2, the value is WUDFOsrusbfx2.

• TARGETTYPE

  Required. Specifies which type of binary is to be built. UMDF drivers are built as DLLs, so TARGETTYPE is set to DYNLINK.

Custom Targets

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

• MISCFILES

  Optional; required for projects that use INX files to produce their INFs. Specifies where the resulting INF file should be placed. In the example in Listing 19-2, this macro uses the value assigned to NTTARGETFILES, which places the INF in the output folder with the other output files.

• NTTARGETFILES

  Optional. Indicates that the project has a Makefile.inc file. The value assigned to the macro specifies the name and target folder for the INF file that the Build utility produces from the project's INX file.

Source Files, Headers, and Libraries

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

• INCLUDES

  Optional. Specifies the location of folders, other than the project folder, that contain header files. These are typically header files that are shared across multiple projects. The folder locations are typically specified relative to the project folder and are separated by semicolons.

• SOURCES

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

  Required. Specifies any static libraries that the driver uses. UMDF drivers must link to at least Kernel32.lib. In the example in Listing 19-2, the driver links to three libraries: Ntstrsafe.lib, Kernel32.lib, and Advapi32.lib.

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 C compiler. In the example in Listing 19-2, this variable specifies a required flag for event tracing.

• DLLDEF

  Optional. Specifies the name of the .def file that the Build utility passes to the librarian when building the export and import files. If you do not specify a value for this macro, the Build utility assumes that the .def file uses the name that is assigned to TARGETNAME and names the file $(TARGETNAME).def.

• DLLENTRY

  Optional. Specifies the name of the DLL's entry point as DllMain. If you do not specify a value for this macro, the Build utility uses the DllMainCRTStartup default value.

• MSC_WARNING_LEVEL

  Optional. Sets the compiler warning level. The recommended practice is to set the warning level to 4, to ensure a clean build. If you receive warnings that are caused by nonstandard features, you can disable the warnings-which is similar to adding the following to a code file:

  • #pragma warning(disable:WarningNumber)

    For example, the second instance of MSC_WARNING_LEVEL disables warning 4201.

• RUN_WPP

  Optional. Runs the WPP preprocessor. You can omit this directive if you are not using WPP tracing. The -scan option indicates that Internal.h contains the trace message function definition. Chapter 11, "Driver Tracing and Diagnosability," provides information about WPP tracing.

• USE_MSVCRT

  Optional. Indicates that the project uses the multithreaded C run time library. Free builds use Msvcrt.lib, and checked builds use Msvcrtd.lib.

• WIN32_WINNT_VERSION, _NT_TARGET_VERSION, and NTDDI_VERSION

  Required. Normally, the build environment defines these aspects of the build configuration. However, UMDF drivers must be built with the Windows Vista build environment. Specifying the settings shown in Listing 19-2 for these three macros enables the drivers to run on Windows XP also.

Makefile and Makefile.inc for Fx2_Driver

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

Listing 19-3: The Fx2_Driver Makefile.inc file

.SUFFIXES: .inx STAMP=stampinf .inx{$(OBJ_PATH)\$(O)}.inf: copy $(@B).inx $@ $(STAMP) -f $@ -a $(_BUILDARCH) -u $(UMDF_VERSION).$(UMDF_MINOR_VERSION).0

This example Makefile.inc file contains the following three directives:

• .SUFFIXES lists extensions for inference rule matching.

  Common extensions such as .c, .h, and .cpp are predefined, but .inx must be listed explicitly.

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

  The standard $(OBJ_PATH) variable specifies that the INF is to be placed in the output folder.

• The final line specifies the UMDF version and CPU architecture.

  Most UMDF drivers can use this example with only minimal alteration.

How to Build Fx2_Driver

The following procedure shows how to build Fx2_Driver for the x86 version of Windows Vista.

To Build Fx2_Driver for the x86 Version of Window Vista

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

   The window opens in the %wdk% folder.

2. Use cd to move to the project folder: %wdk%\src\umdf\usb\Fx2_Driver\Final.

3. Build the project by running the following command:

   • build.exe -ceZ

This is not the only way to build the project, but the example shows a commonly used set of flags. The output files for the Fx2_Driver are placed in the project's objchk_wlh_x86\i386 subfolder.