Windows 7 : Kernel Mode Installation and Build - Building Featured Toaster

The Toaster sample is set of simple software drivers that were created by Microsoft as a learning tool for new driver developers. If you are new to KMDF driver development, it’s the first sample you should look at. Not only does Toaster provide a simple example of how to write drivers by using the best coding practices, it includes detailed comments that explain every step. Toaster is located at WinDDK\BuildNmber\src\kmdf\toaster.

Toaster includes a number of drivers, including two function drivers. One is a minimal version that is named Simple and the other a full-featured version that is named Featured. This section uses the Featured Toaster sample as a convenient way to demonstrate the basics of the build, install, and debug process. We will walk through how to create a Windows 7 checked build of Featured Toaster. We will discuss some of the supporting files that are mentioned in the previous material. The KMDF version of Toaster is essentially a port of the WDM Toaster sample. If you are familiar with the WDM version, compare it to the KMDF version to see just how much KMDF can simplify driver code.

1. Makefile and Makefile.inc

The contents of Makefile are the same for all driver projects. Featured Toaster also includes an optional file, Makefile.inc. This file contains some additional make directives that handle two targets that aren’t covered by makefile.def. The following example shows the contents of Featured Toaster’s makefile.inc file:

_LNG=$(LANGUAGE)
_INX=.
STAMP=$(STAMPINF_PATH) –f $@ -a $(_BUILDARCH) -v 1.0.0.0

$(OBJ_PATH)\$(0)\$(INF_NAME) .inf:  $(_INX)\$(INF_NAME .inx
       copy $(_INX)\$(@B)  .inx $@
   $(STAMP)

mofcomp: $(OBJ_PATH)\$(0)\toaster.bmf

$(OBJ_PATH)\$(0)\toaster.bmf: toaster.mof
   mofcomp –WMI –B:$(OBJ_PATH)\$0\toaster.bmf toaster.mof
   wmimofck –m –h$(OBJ_PATH)\$0\ToasterMof.h  –
w$(OBJ_PATH)\$0\htm $(OBJ_PATH)\$(0)\toaster.bmf

The first part of makefile.inc uses the project’s INX file, wdffeatured.inx, to produce an architecture-specific INF file. The second part of makefile.inc produces the WMI target file.

2. The Sources File

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 following example shows the contents of the Featured Toaster Sources file, which is a typical Sources file for a simple KMDF driver:

TARGETNAME=wdffeatured
TARGETTYPE=DRIVER

KMDF_VERSION=1.5

INF_NAME=wdffeatured
MISCFILES=$(OBJ_PATH)\$(0)\$(INF_NAME)  .inf
INCLUDES = $(INCLUDES)   ;..\..\inc;..\shared

NTTARGETFILES=
NTTARGETDILE0=mofcomp

#
# List of source files to compile.
#
SOURCES=             \
      toaster.rc           \
      toaster.c            \
      power.c          \
      wmi.c

C_DEFINES=

!include $(WDF_ROOT)\project.mk

The following list gives brief descriptions of the macros and environment variables in this file. For a complete list, see the WDK documentation.

• TARGETNAME— Required. This macro specifies wdffeatured as the name to be used for output files such as the project’s .sys and .pdb files.

• TARGETTYPE— Required. The build utility can be used to build a variety of binary types. This macro specifies which type of binary is to be built; DRIVER indicates a Kernel Mode Driver.

• KMDF_VERSION— Required. This environment variable specifies the KMDF version number. This project uses KMDF version 1.5.

• INF_NAME— Optional. INF_NAME is a custom macro for projects that use INX files. It specifies that the INF file that is generated from the projects INXwdffeatured.inf. file is to be named

• MISCFILES— Optional. MISCFILES is a custom macro for projects that use INX files. It specifies where to place the INF file that is generated. In this example, the INF file is placed in the output folder with the other output files.

• INNLUDES— Optional. This macro 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.

• NTTARGETFILE0— Optional. This macro is used to specify additional targets and dependencies that are not covered by makefile.def. In this case, it is used for WMI-related aspects of the build.

• SOURCES— Required. This macro 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.

• C_DEFINES— Required for Unicode builds. Specifies any compile-time switches that must be passed to the C compiler.

3. The Build

The following procedure shows how to build Featured Toaster. For simplicity, assume that the WDK’s root folder is C:\WinDDK\6000.

build –ceZ

The output files go in the featured\objchk\w7_x86\i386 subfolder.