Getting Started with Driver Development | Developing Drivers with the Windows Driver Foundation (Pro Developer)

To follow the examples in this book and to use the WDF frameworks, you must install the current Windows Driver Kit (WDK). The WDK contains most of the resources you need to develop drivers, such as tools, documentation, and libraries. The following sections provide some guidelines and tips for installing software and finding the samples and tools discussed in this book.

Important

Always use the most recent version of the WDK. This book assumes that you are using WDK Build 6000 or a later version. If you are already developing Windows drivers, you need to install Build 6000 or a later version to obtain the components discussed in this book. Static Driver Verifier for KMDF drivers and PREfast driver-specific annotations require the WDK version provided with the Beta 3 release of Microsoft Windows Server Code Name "Longhorn," or a later version.

System Requirements for Driver Development

You can develop and build KMDF drivers for Windows 2000 or later versions of Windows. You can build UMDF drivers for Windows XP or a later version of Windows. You can use any recent version of Windows to build your drivers. To target a driver for a particular version and CPU architecture, you specify the appropriate build environment configuration when you use the Build utility.

However, you should plan to install, test, and debug your driver on a system that is running the target version of Windows, with hardware that is the same as or similar to the hardware on your customers' systems.

Important

Always use the most recent version of the Debugging Tools for Windows, as described later in this chapter.

To debug KMDF drivers, you need two computers: one to host the debugger and the other to host the driver you want to debug. Kernel-mode driver bugs commonly cause system crashes and can corrupt the file system, causing loss of data-so it's necessary to have the debugger and driver on separate computers.

To debug UMDF drivers, you can run the debugger and driver on the same computer or run the two on separate systems. You can also use a single computer with different versions of Windows on separate partitions for many of these tasks. However, a common practice is to have a development computer plus at least one additional computer dedicated to testing and debugging.

We recommend the following hardware for a developer's work configuration:

A computer with a multicore processor or multiple processors. At a minimum, your processor should support hyperthreading. If you test your drivers only on a uniprocessor system, you might not detect certain types of bugs, such as race conditions. In addition, the Windows Logo Program requires that all submitted drivers pass compatibility tests for multiprocessor systems.
A 64-bit computer that runs x64 versions of Windows. Certain types of critical errors can be detected only on 64-bit systems. The Windows Logo Program requires that your driver support both 32-and 64-bit systems.

Tip

If you develop and test WDM drivers by using WDK Build 6000 or later, you can use the same build environments to develop drivers with WDF.

How to Obtain and Install the WDK

The WDK, which contains the Driver Development Kit (DDK), is the driver developer's primary resource. The WDK contains the bulk of what you need to develop drivers, as described in the following sections.

The WDK supports driver development for the Microsoft Windows NT family of operating systems, starting with Windows 2000. The WDK is released periodically, and the version is typically associated with a particular Windows release. However, that's just a convenient way of indicating the release date. In fact, each WDK release supports building drivers for all hardware platforms and all versions of Windows that Microsoft supports under the life cycle support policy. In 2007, the WDK supports building drivers for Windows 2000, Windows XP, Windows Server 2003, Windows Vista, and Windows Server "Longhorn."

You should always use the latest version of the WDK. This practice guarantees that you have current documentation and tools, including all updates and fixes made since the previous release.

To Obtain the WDK

See the WHDC Web site at http://www.microsoft.com/whdc/ for information about obtaining the current WDK.

New versions are released in conjunction with associated product releases, such as Windows beta and RTM releases and major developer events such as WinHEC. The WHDC Web site also provides information about which versions of Windows are supported by the current WDK.
If you download the ISO for the WDK, burn a CD or DVD to create the installation media.

To Install the WDK

Insert the WDK installation media to run the installation application.
Read the WDK Release Notes to check for any installation issues.
Install required prerequisites.

The installation application checks your system and enables buttons under WDK Prerequisite Setup Packages for any features that are not present. You might not need all of these features, but you probably want the .NET Framework, Version 2.0, and Microsoft Document Explorer to view the documentation.
Under WDK Setup Package Features, click Install.

Inside Out

By default, the WDK installs on your C drive in a root folder named WinDDK \BuildNumber. If you install multiple WDK versions, the WDK installation wizard places each WDK version under its own build number.

Tip

Because you can choose to install the WDK on other drives the %wdk% environment variable is used in this book to refer to the WDK root folder.

WDK Libraries

The WDK includes static libraries (LIBs), dynamic-link libraries (DLLs), and the WDF libraries that you need for developing WDF drivers:

Redistributable co-installer DLLs The WDK contains redistributable co-installers for UMDF and KMDF. The co-installers are used during driver installation to install the associated framework runtime support on a user's computer, if the runtime is not already present. Drivers dynamically bind with the frameworks that the co-installers install. To make the co-installers easier to identify, their names include the WDF version number. There are separate versions of the co-installers for each supported CPU architecture.

Chapter 20, "How to Install WDF Drivers," describes the co-installers.
Debugger extensions The WDF debugger extensions are specialized, WDF-specific commands that run in the context of the WinDbg debugger. The debugger extensions are packaged in two DLLs: WudfExt.dll contains the UMDF extensions, and WdfKd.dll contains the KMDF extensions. Separate versions of the debugger extensions are provided for each supported CPU architecture.

Chapter 22, "How to Debug WDF Drivers," describes WinDbg and the extensions.
Libraries The WDK contains a number of static libraries. KMDF drivers bind statically with WdfDriverEntry.lib and WdfLdr.lib. You can choose to implement UMDF drivers by using the Active Template Library (ATL), a C++ template library that is designed to simplify the process of implementing COM objects.

Inside Out
KMDF libraries are located under %wdk%\lib\wdf\kmdf. ATL libraries are located under %wdk%\lib\atl.

WDK Documentation

This book is only an introduction to WDF development. For all of the necessary information to develop a fully functional device driver, see the WDK documentation. That documentation provides detailed reference pages for every function exposed in the WDF device driver interface (DDI). The WDK documentation also contains conceptual material, design and implementation guidelines, and documentation for the WDK tools.

To Run the WDK Documentation from the Start Menu

On the taskbar, click Start, and then click:

All Programs > Windows Driver Kits > BuildNumber > Help > WDK Documentation

Tip You can view the WDK documentation online as part of the MSDN Library-online at http://msdn.microsoft.com. Locate the Microsoft Win32 and COM Development node in the MSDN Library table of contents, and then find Windows Driver Kit. The online version of the WDK documentation is updated quarterly.

WDK Tools

The WDK contains a substantial set of tools for development and testing. Most are command-line tools that run in a command window, but some are conventional Windows applications with graphical user interfaces. Some tools for testing include the following:

Tracing Chapter 11, "Driver Tracing and Diagnosability," describes how to use WPP tracing and the associated WDK tools to trace execution and assist in debugging.
Driver Verifier and other runtime tools Chapter 21, "Tools for Testing WDF Drivers," discusses the runtime verification tools for testing drivers.
Static verifiers Chapter 23, "PREfast for Drivers," and Chapter 24, "Static Driver Verifier," provide details about using static verifier tools.

Note-Info To run some of the tools in Windows Vista, you must specify that you want the tool to run with elevated privileges, even if you already have administrative privileges. See "User Account Control" on MSDN for details-online at http://go.microsoft.com/fwlink/?LinkId=80621.

To Run an Application on Windows Vista with Elevated Privileges

On the taskbar, click Start, right-click the application, and then click Run as administrator.

If you already have administrative privileges, Windows Vista displays a User Account Control dialog box asking for permission to proceed.
To run the application, click Continue.
If you do not have administrative privileges, Windows Vista asks for administrative credentials.

To Open a Command Window with Elevated Privileges

On the taskbar, click Start, right-click Command Window, and then click Run as administrator.
Click Continue and provide credentials, if prompted.

Any application that you run from that command window, including any Windows-based application, also has elevated privileges.

WDK Samples

The WDK includes an extensive set of samples that show common types of drivers you might develop. These samples contain well-designed working code and are extensively commented.

Inside Out

The WDF samples are installed with the WDK in %wdk%\src\kmdf and %wdk%\src\umdf. Each sample is installed in its own folder with the same name as the driver.

Tip

Before you build or modify any WDK sample, copy the files to another directory and then work with the copies. This preserves the sample in its original form in case you need it.

About UMDF Samples

If you are a new WDF developer, we recommend that you examine the Skeleton and Fx2_Driver samples, which are used throughout this book:

Skeleton driver (UMDF Template) This basic driver does little more than load and start successfully.

The Skeleton sample driver is simple so that you can use it to learn the basics of how a UMDF driver works. It's also a good starting point for implementing a functional driver, because most UMDF drivers can use most of the code in the Skeleton sample driver with little or no modification. You can add code incrementally to handle the requirements of your particular device.

Inside Out
The Skeleton sample driver is installed with the WDK in the %wdk%\src\umdf \skeleton folder.

Fx2_Driver This sample is a USB driver that was specifically designed for learning purposes.

The Fx2_Driver works with the OSR USB FX2 Learning Kit device from Open System Resources (OSR), as described later in this chapter. Fx2_Driver is simple because the device itself is not very complicated. However, the driver works with a real device and demonstrates a range of basic UMDF features, including how to handle read, write, and device I/O control requests.

Code from the Fx2_Driver sample driver appears throughout this book in examples to show how UMDF drivers work. Other samples are also included-in this book and in the WDK-to illustrate features that Fx2_Driver does not support.

Inside Out

Fx2_Driver is located under the %wdk%\src\umdf\usb\fx2_driver folder. Each subfolder contains a variant of the driver. The driver in the Step1 folder is a minimal implementation. The Step2 through Step5 folders contain increasingly full-featured versions of the driver. The Final folder contains the complete driver and is the sample that is used in this book. The \Exe subfolder contains source code for a simple console application that can be used to operate the device and exercise the capabilities of the driver.

About KMDF Samples

The WDK provides many KMDF samples. If you are a new WDF developer, we recommend that you examine the Toaster and Osrusbfx2 samples, which are used throughout this book. You can examine other samples for more information about other features that these samples do not use, such as DMA or interrupt handling:

Toaster This software driver simulates the behavior of real devices in Windows.

The Toaster driver is not quite as basic as the Skeleton driver, but nevertheless serves as a useful starting point for understanding KMDF drivers. The Toaster sample is made up of a collection of related drivers, including bus, filter, and function drivers.

Inside Out

The Toaster sample is located in the %wdk%\src\kmdf\toaster folder. Several subfolders contain different related drivers. The best place to start is with the function driver located under %wdk%\src\kmdf\toaster\func.

Two drivers in that subfolder contain a different version of the driver: a basic one named Simple, and a full-featured version named Featured. The %wdk%\src\kmdf\toaster\exe folder contains the source code for several test applications that you can use to exercise the driver's capabilities.

Osrusbfx2 This sample is a USB driver built for kernel mode.

Code from the Osrusbfx2 sample driver appears throughout this book in examples to show how KMDF drivers work. This sample does not demonstrate all of the features of KMDF. The %wdk%\src\kmdf folder in the WDK contains other samples that illustrate features that Osrusbfx2 does not support.

This sample is the kernel-mode equivalent of Fx2_Driver. It has almost the same capabilities as Fx2_Driver, and the structure and code are quite similar.

Inside Out

Osrusbfx2 is located in %wdk%\src\kmdf\osrusbfx2, which includes six subfolders. The Step1 through Step5 and the Final folders contain successively more sophisticated versions of the driver. Each version has similar capabilities to the corresponding Fx2_Driver version. The \Exe subfolder contains the source code for a simple test application.

Tip

Use the Osrusbfx2 test application with both the OsrUsbFx2 and Fx2_Driver samples. It provides access to all the features on the device.

How to Obtain Checked Builds of Windows

The system Microsoft uses to build Windows produces two separate builds of the operating system: free and checked. We recommend that you test and debug on both types of builds:

Checked builds Checked builds contain detailed debugging information and enable certain types of debugging-related code such as ASSERT macros.

Checked builds are similar to the debug builds that are used in application development. They are typically slower than free builds. Because some compiler optimizations are disabled, the disassembled machine instructions and trace messages are more easily understood.
Free builds Free builds lack detailed debugging information and are fully optimized.

These builds are similar to the release builds that are used in application development. Retail versions of Windows are all free builds because they have the best performance and smallest memory footprint.

We recommend that you use checked builds of Windows for testing and debugging. Developers typically switch to free builds of Windows for performance tuning late in the development cycle, after most of the bugs have been eliminated.

Info You can obtain checked builds on MSDN Subscriber CDs or from the Subscription area on MSDN. See "Using Checked Builds of Windows" on the WHDC Web site-online at http://go.microsoft.com/fwlink/?LinkId=79304.

How to Obtain Debugging Tools

The Debugging Tools for Windows package is provided at no charge on the WHDC Web site and is included in the WDK.

To Obtain Debugging Tools for Windows from WHDC

Go to the "Debugging Tools for Windows" page on the WHDC Web site at http://go.microsoft.com/fwlink/?LinkId=80065.
Locate the Install page for the 32-bit version and follow the instructions for downloading the package.
Locate the page for the 64-bit version and repeat the steps to download the 64-bit package.

Tip Check the Debugging Tools for Windows documentation for information about where the package is installed.

In general, if the debugger is running on a 32-bit system, you must use the 32-bit package. If the debugger is running on an x64 system and the target computer is running Windows XP or later, you can use either the 32-bit or the 64-bit package. See "Choosing Between the 32-bit and 64-bit Packages" in the Debugging Tools for Windows documentation.

The Debugging Tools for Windows package includes the following components:

Debuggers WinDbg is a graphical debugging tool that we recommend for both UMDF and KMDF drivers. However, developers who prefer a command-line tool can also use KD, a console application with the same capabilities as WinDbg.
A collection of related debugging tools The Debugging Tools for Windows package also includes other tools to support debugging. For example, Tlist is a command-line tool that displays information about running processes and is useful for debugging UMDF drivers. The DBH tool can be used to look at symbols while debugging.
Debugging documentation The Debugging Tools for Windows Help file contains instructions on how to use the debugging tools and a complete reference for the standard debugger commands and extensions.

When debugging a driver-especially a kernel-mode driver-you typically need the symbol files for the version of Windows under which the driver is running. Symbol files for all versions of Windows are available from Microsoft.com. For kernel debugging, you must install the symbols on the computer that hosts the debugger, not on the test computer.

Inside Out

Symbols for the hardware abstraction layer (HAL) and Windows kernel (KRNL) are installed with the WDK at %wdk%\debug.

To obtain up-to-date symbols, we recommend that you connect the debugger to the Microsoft symbols server, which automatically downloads the correct symbols.

To Obtain Windows Symbols

Follow the instructions in the WinDbg help file to connect to the Microsoft symbols server, from which WinDbg can automatically download the correct symbols-online at http://msdl.microsoft.com/download/symbols.

-Or-

Download the current packages from the WHDC Web site at http://go.microsoft.com/fwlink/?LinkId=79331.

Chapter 22, "How to Debug WDF Drivers," discusses how to use symbols when debugging a driver, including how to use the Microsoft symbols server.

Info See "Debugging Tools and Symbols-Resources" on the WHDC Web site for a list of training companies and other resources for learning about debugging Windows drivers-online at http://go.microsoft.com/fwlink/?LinkId=79332.

How to Obtain OSR Learning Devices

The best way to learn how to develop device drivers is with an actual device. However, commercial devices are frequently complex, making it difficult to get started. In addition, the specifications you need to implement such a driver are often proprietary and can be difficult to obtain if you do not work for the manufacturer.

To solve this problem for beginning driver developers, OSR has created several learning kits with devices that are specifically designed for learning driver development. They are simple enough that you can focus on developing basic skills.

Physically, the kits are circuit boards that either plug in to the PCI bus or attach to the computer with a USB cable. The boards provide visual feedback on their operation, so that you can easily see what is happening. For example, the USB device has an LED panel that can be programmed to display alphanumeric characters, as shown in Figure 1-1. This book uses Microsoft sample drivers that work with the OSR USB Fx2 device.

image from book
Figure 1-1: Simplified drawing of the USB learning device

Info The OSR Learning Kits include all of the required hardware specifications to implement a driver, plus sample code and test applications. See the OSR Web site for more information and to obtain kits-online at http://www.osronline.com.