Developing Drivers with the Windows Driver Foundation (Pro Developer)

This book is structured to provide you with the basic information you need to develop a WDF driver and assumes that you have no prior experience with driver development. The book starts with how a driver functions in the Windows operating system environment, and then builds on this information to describe how to use WDF to implement drivers.

Who Should Read This Book

This book is intended for developers with a solid foundation in programming with the C or C++ language who are interested in implementing Windows drivers, including:

• Driver developers who are interested in learning how to implement drivers with WDF. If you are an experienced driver developer, you should find it easy to adapt to the new model. However, WDF user-mode drivers are COM based, so this book provides a basic introduction to COM programming for those who need it.

• Application developers who want to get started in driver development. WDF provides a much easier learning curve than earlier driver models, but applications differ in many ways from drivers, especially kernel-mode drivers. This book presents basic background information to help you understand the structure and operation of Windows drivers. This background information is then used in the discussions of driver development throughout this book.

• Hardware engineers who need to understand how drivers interact with devices. Engineers who must build drivers for their prototype hardware will find the WDF model especially useful because of its rapid prototyping and easier learning curve.

Under WDF, developing user-mode drivers requires an understanding of C++, whereas kernel-mode drivers are almost always written in C. If you are unfamiliar with either language, you should consult any of the many books on these languages. By building on your knowledge of C and C++ and your familiarity with Windows programming, this book provides the concepts, guidelines, programming examples, and tips to get you started with WDF drivers.

About Part 1: Getting Started with WDF

The first part of this book provides an introduction to tools and resources, basic Windows operating system and driver concepts, and an overview of WDF.

• Chapter 1, "Introduction to WDF" (this chapter) This chapter provides an orientation to this book and the tools it discusses. To begin:

  • Review this chapter to understand the structure of this book and the conventions used in text and in code examples.

  • Review the requirements and install the Windows Driver Kit (WDK) and debugging tools as described in "Getting Started with Driver Development" later in this chapter, so that you can follow the samples and try activities in real time.

• Chapter 2, "Windows Driver Fundamentals" This chapter covers the background material that you'll need to understand driver development. It is especially intended for application programmers who are not familiar with drivers or kernel-mode programming. Read this chapter for a quick primer on Windows architecture, the Windows I/O model, user mode versus kernel mode, Plug and Play, interrupts, memory management, threads and synchronization, and other key concepts.

  The topics in Chapter 2 are all revisited in depth later in the book in the context of WDF driver implementation.

• Chapter 3, "WDF Fundamentals" WDF includes three primary components: the user-mode driver framework (UMDF), the kernel-mode driver framework (KMDF), and a suite of verification and testing tools. This chapter provides a conceptual tour of the WDF architecture and introduces the two frameworks. This chapter also introduces basic concepts related to WDF, such as the WDF object model, I/O model, and how WDF manages Plug and Play and power events.

About Part 2: Exploring the Frameworks

Although the two WDF frameworks are similar in many ways, they are not identical; each has its strengths and limitations. In Part 2, you'll find a detailed tour of the frameworks.

• Chapter 4, "Overview of the Driver Frameworks" This chapter describes the two frameworks, including their related runtime components:

  • UMDF supports the creation of simple, robust Plug and Play drivers for several device categories, especially for consumer-oriented devices such as portable media players and cell phones.

  • KMDF supports the creation of drivers that must run in kernel mode because they support direct memory access (DMA), handle interrupts, have strict timing loops, are clients of other kernel-mode drivers, or require kernel-mode resources such as the nonpaged pool.

  This chapter also provides guidelines to help you choose which framework to use to implement a driver for a particular device.

• Chapter 5, "WDF Object Model" WDF supports an object-oriented, event-driven programming model in which:

  • The basic building blocks of drivers are objects. The object models for UMDF and KMDF are similar, although the implementation details differ.

  • Each object has an associated set of events. The frameworks provide default handling for most events. Drivers handle only those events that are relevant to their device and let the frameworks handle the remainder.

  A WDF driver interacts with these objects through consistent, well-defined programming interfaces. This chapter provides details about the object model as a foundation for understanding what you must implement in your driver and what the frameworks handle.

• Chapter 6, "Driver Structure and Initialization" To help you get started with the specifics of Windows driver development, this chapter explores the structure and required components of WDF drivers. It also explores common aspects of UMDF and KMDF drivers: driver objects, device objects, driver entry points, and callbacks. You'll learn about driver entry routines, initialization, and device object creation.

About Part 3: Applying WDF Fundamentals

After you have a solid conceptual understanding of the architecture and components of the WDF frameworks, it's time to dive into the details of Windows drivers that will absorb much of your time and energy during development. This part of the book explores a number of important concepts and practices.

• Chapter 7, "Plug and Play and Power Management" Plug and Play is a combination of hardware and software that enables a computer to recognize and support hardware configuration changes with little or no user intervention. Windows also supports a power management architecture that provides a comprehensive policy for managing system and device power.

  These two Windows capabilities have proved difficult for driver developers who used earlier driver models. This chapter explores how these features work in WDF drivers and shows how the frameworks substantially reduce and simplify the code that is required to support Plug and Play and power management.

• Chapter 8, "I/O Flow and Dispatching" A Windows driver receives I/O requests from applications, services them, and returns information to the application. This chapter provides a general description of I/O flow in WDF drivers, describes the types of I/O requests that drivers might be asked to handle and how to create queues to handle them, and focuses in detail on some commonly used request types.

• Chapter 9, "I/O Targets" Drivers can satisfy and complete some I/O requests, but they must pass other requests to lower components of their device stack or to other device stacks. Drivers can also issue I/O requests. A WDF driver uses an I/O target to send an I/O request to another driver-whether that driver is in the same device stack or a different one. This chapter explores the details of creating I/O targets and sending I/O requests, including information on specialized I/O targets for USB devices.

• Chapter 10, "Synchronization" Windows is a preemptive, multitasking operating system, which means that different threads can try to concurrently access shared data structures or resources and that multiple driver routines can run concurrently. To ensure data integrity and to avoid race conditions, all drivers must synchronize access to shared data structures and resources. This chapter discusses when synchronization is required and then explores the synchronization and concurrency features that the frameworks provide.

• Chapter 11, "Driver Tracing and Diagnosability" Software tracing provides a low-overhead way to analyze your driver's behavior. This chapter discusses how to use Windows Software Trace Preprocessor (WPP) to instrument a WDF driver to help analyze your driver's behavior and fix its problems. The emphasis in this chapter is on best practices that help you design your driver for diagnosability.

• Chapter 12, "WDF Support Objects" All drivers use the device, driver, and I/O queue objects described in earlier chapters. The frameworks also define additional objects that represent less-common driver abstractions. This chapter describes some of the other objects that you'll use to implement WDF drivers and describes techniques for allocating memory, reading and writing to the registry, using timers and collections, and supporting Windows Management Instrumentation (WMI) in KMDF drivers.

• Chapter 13, "UMDF Driver Template" The Skeleton sample driver contains the minimum amount of code that is required in a UMDF driver. You can use it as a starting point from which to build drivers for actual hardware. This chapter explains how the Skeleton driver demonstrates the minimal required features and best practices for a UMDF driver, and then it describes how to use the sample as a starting point for implementing a full-featured driver.

About Part 4: Digging Deeper: More Topics for WDF Drivers

A kernel-mode driver is, in effect, part of the Windows operating system and consequently must manage additional complications that do not apply to user-mode drivers. KMDF drivers might be required to deal with the subtleties of hardware interrupts and direct memory access. For UMDF drivers, you need to understand how to use and implement COM objects. These deeper subjects are explored in this part of the book.

• Chapter 14, "Beyond the Frameworks" Although the frameworks provide most of the features that drivers use most of the time, there are some exceptions when drivers require services that the frameworks do not support. This chapter describes how to use system services that fall outside the frameworks. For example:

  • UMDF drivers can use many of the functions in the Windows API.

  • KMDF drivers can use kernel-mode system functions, including functions that manipulate the WDM objects underlying the WDF objects.

• Chapter 15, "Scheduling, Thread Context, and IRQL" Thread scheduling, thread context, and the current interrupt request level (IRQL) for each processor affect how kernel-mode drivers work. This chapter explores the concepts and best practices that you must master to avoid problems related to interrupts, preemption, and IRQL in KMDF drivers.

• Chapter 16, "Hardware Resources and Interrupts" If your device hardware generates interrupts, your kernel-mode driver must service those interrupts. To service a hardware interrupt, a KMDF driver must create an interrupt object, enable and disable the interrupt, and respond appropriately when an interrupt occurs. This chapter discusses how to service interrupts with KMDF and provides guidelines and best practices.

• Chapter 17, "Direct Memory Access" DMA is a high-performance technique for transferring data directly to and from memory for DMA-capable devices. DMA can support higher data rates than other approaches, along with lower overall system CPU usage. KMDF transparently handles much of the work that is required to implement DMA in a driver. This chapter describes basic DMA concepts and how to implement DMA in a KMDF driver.

• Chapter 18, "An Introduction to COM" To create a UMDF driver, you must use a number of COM objects that belong to the UMDF runtime and also implement a number of COM-based callback objects. This chapter provides a basic introduction to using and implementing COM objects, as required by UMDF.

About Part 5: Building, Installing, and Testing a WDF Driver

Drivers must be built, tested, debugged, and installed by using a set of tools and techniques designed specifically for driver development. In addition to the standard tools, WDF includes a set of verification, testing, and debugging tools to make it easier to produce robust WDF drivers.

• Chapter 19, "How to Build WDF Drivers" Window drivers are built with the WDK build utility, Build.exe. This command-line utility is the tool that Microsoft uses to build Windows. This chapter shows how to set up your build environment and describes how to build UMDF and KMDF drivers.

• Chapter 20, "How to Install WDF Drivers" Installing a driver is quite different from installing an application. This chapter explores the tools and processes for installing drivers, including the use of tools such as DevCon and Device Manager. It also closely examines INF issues for WDF drivers, and points to resources for code-signing drivers.

• Chapter 21, "Tools for Testing WDF Drivers" Thorough testing throughout all phases of development is essential to create a robust, high-quality driver. WDF includes built-in runtime verification for both frameworks, adding to Driver Verifier and other general-purpose driver-testing tools that are provided in the WDK. This chapter provides a brief introduction to the tools and best practices to test and verify WDF drivers.

• Chapter 22, "How to Debug WDF Drivers" WinDbg is the debugger of choice for both UMDF and KMDF drivers. This debugger works in either user mode or kernel mode and supports a number of extensions that simplify debugging WDF-specific issues. This chapter introduces driver debugging and provides a basic overview of how to use WinDbg to debug WDF drivers.

• Chapter 23, "PREfast for Drivers" PREfast for Drivers is a static source code analysis tool for driver development. This tool runs at compile time and reports a variety of coding errors that the compiler and runtime testing are unable to detect in drivers. This chapter explores how to use PREfast effectively in your driver development process, including the use of source code annotations in your driver so PREfast can perform a deeper analysis of your code.

• Chapter 24, "Static Driver Verifier" Static Driver Verifier (SDV) is a static verification tool for kernel-mode drivers that emulates the operating system's path through the driver and symbolically executes the source code. This tool has built-in knowledge about Windows internals and about how drivers should use Windows interfaces. This chapter describes the use of SDV as a recommended best practice for driver development. It includes details about KMDF rules for SDV, first introduced in 2007.

Glossary

The glossary contains a list of the terms and acronyms used in this book. A comprehensive glossary of driver development terms is provided in the WDK.