Appendix C. Building Drivers

Appendix C. Building Drivers

CHAPTER OBJECTIVES

• The Build Utility

• Using Visual Studio to Build Drivers

There is nothing magical about the build process for a driver. Like any piece of "real" (i.e., noninterpreted) code, it must be compiled and linked into a binary file before it can be used. The issues that arise when building drivers concern notifying the build tools (compiler and linker) that the environment for the code being generated is that of kernel mode.

Although it sometimes may appear otherwise , Microsoft supplies a single compiler and linker. Whether the tools are invoked from a command-line prompt or from an elaborate Integrated Development Environment (IDE) such as Visual Studio, the resulting binary files are the same. In many ways, Visual Studio is merely a GUI interface for the build and editing tools. Clicking on the menu option for Project, then Settings, provides a convenient dialog-based interface to the tool switches.

The DDK provides a utility, BUILD, that is convenient for batch and production builds of device drivers (as well as other production-level binaries). With proper environment settings, however, the driver author may successfully use Visual Studio. Indeed, it may be appropriate to use Visual Studio throughout the development phase and introduce BUILD during the later release stages of the project.

The purpose of this appendix is to provide background material on the BUILD utility, as well as provide the Visual Studio settings necessary for successful driver builds.

The Build Utility

The DDK-supplied BUILD utility is ideal for production releases because it works from a single "makefile" concept to batch-build a variety of targeted binaries. For example, a single set of source files can be used to generate driver binaries for both Intel x86 platforms and Alpha platforms. Similarly, both the retail (free) and checked (debug) versions can be built from a single procedure.

What BUILD Does

The BUILD utility is just an elaborate wrapper around NMAKE. (NMAKE is Microsoft's attempt at the Unix make utility.) A batch file of instructions provides a recipe for the construction of one or more target configurations (e.g., checked and free).

Using a set of keywords, a source file list, and miscellaneous switches, BUILD constructs an appropriate makefile and then invokes NMAKE to actually perform the build to produce one or more BUILD products . Figure C.1 shows how this process works.

BUILD itself is actually a rather simple-minded program. Most of the build process is controlled by a set of standard command files that BUILD passes to NMAKE. These files contain all the platform-specific rules and option settings needed to create a BUILD project. By separating the rules from the utilities, there is less version interdependency.

Figure c.1. The BUILD utility process.

BUILD uses several command files (located in the DDK's binary directory, \BIN:).

• MAKEFILES.DEF is the master control file. It references other files to perform its work.

• MAKEFILE.PLT selects the platform for a build operation.

• i386MK.INC, ALPHAMK.INC, and ia64mk.inc contain platform-specific compiler and linker switches for Intel, Alpha, and 64-bit Intel Itanium processors, respectively.

BUILD helps manage multiplatform projects by separating binary files according to their platform type. To do this, it uses different directories for different platforms. So long as cross-hosted compilers and linkers are available, a single BUILD process can generate binaries for all the supported platforms. The directory structure for the output files takes the form shown in Figure C.2.

Notice that BUILD uses separate directories for the checked and free versions of the generated binaries. The DBG symbol is defined as 1 when performing the checked build.

How to Build a Driver with BUILD

Once the source code is ready for compilation, the use of the BUILD utility requires that the following steps be followed:

1. In the source file directory, create a file called SOURCES that identifies the components that comprise the driver. A description of the format of this file follows in the next section.

   Figure c.2. Directory structure for BUILD product.

   

2. In the source directory, create a file called MAKEFILE that contains only the following line:

   !INCLUDE $(NTMAKEENV)\MAKEFILE.DEF
   

   This stub invokes the standard makefile needed by all drivers created with BUILD. Do not add source files to this makefile. Instead, use the SOURCES file.

3. Use Windows Explorer or the MKDIR command to set up the directory tree for the BUILD products. Refer to Figure C.2.

4. In the Program Manager group for the Windows 2000 DDK, select either the Checked Build Environment or the Free Build Environment. A command window appears with the appropriate BUILD environment variables set.

5. Navigate (using the CD command) to the source file directory for the driver.

6. Run the BUILD utility (i.e., type BUILD) to create the driver executable.

The binary output is created in the CHECKED or FREE directory of the appropriate platform. Any on-screen errors are also written to the BUILD log file.

Writing a SOURCES File

The BUILD operation is controlled by a series of keywords. These keywords specify the type of driver to be generated, the source files that comprise the product, and the directories for various files. While some keywords can be passed as command-line options to BUILD, the more useful procedure is to place the keywords into the SOURCES file. The following general rules apply to the SOURCES file:

• The filename must be SOURCES (no extension).

• The file contents are of the form

  keyword=value
  

• A single BUILD command can be extended over multiple lines by using the backslash (\) character at then end of a line.

• The value of a BUILD keyword must be simple text. BUILD itself does little processing of NMAKE macros and does not handle conditional statements.

• Ensure that there is no white space between a BUILD keyword and the equal sign (=) character. White space after the equal sign is acceptable.

• Comments in a SOURCE file line start with a sharp (#) character.

Table c.1. Common BUILD Utility Keywords

TARGETNAME= DRIVER
TARGETTYPE= DRIVER
TARGETPATH= .
SOURCES= init.c dispatch.c driver.c \
          pnp.c