Developing Drivers with the Windows® Driver Foundation

Developing Drivers with the Windows® Driver Foundation

by Penny Orwick Microsoft Corporation and Guy Smith
Released April 2007
Publisher(s): Microsoft Press
ISBN: 9780735623743

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

Start developing robust drivers with expert guidance from the teams who developed Windows Driver Foundation. This comprehensive book gets you up to speed quickly and goes beyond the fundamentals to help you extend your Windows development skills. You get best practices, technical guidance, and extensive code samples to help you master the intricacies of the next-generation driver model—and simplify driver development.



Discover how to:

  • Use the Windows Driver Foundation to develop kernel-mode or user-mode drivers

  • Create drivers that support Plug and Play and power management—with minimal code

  • Implement robust I/O handling code

  • Effectively manage synchronization and concurrency in driver code

  • Develop user-mode drivers for protocol-based and serial-bus-based devices

  • Use USB-specific features of the frameworks to quickly develop drivers for USB devices

  • Design and implement kernel-mode drivers for DMA devices

  • Evaluate your drivers with source code analysis and static verification tools

  • Apply best practices to test, debug, and install drivers



    • PLUS—Get driver code samples on the Web

    Table of contents

    1. Developing Drivers with the Windows® Driver Foundation
    2. Foreword
    3. Acknowledgments
    4. I. Getting Started with WDF
      1. 1. Introduction to WDF
        1. About This Book
          1. Who Should Read This Book
          2. About Part 1: Getting Started with WDF
          3. About Part 2: Exploring the Frameworks
          4. About Part 3: Applying WDF Fundamentals
          5. About Part 4: Digging Deeper: More Topics for WDF Drivers
          6. About Part 5: Building, Installing, and Testing a WDF Driver
        2. Conventions Used in This Book
        3. Getting Started with Driver Development
          1. System Requirements for Driver Development
          2. How to Obtain and Install the WDK
          3. WDK Libraries
          4. WDK Documentation
          5. WDK Tools
          6. WDK Samples
            1. About UMDF Samples
            2. About KMDF Samples
          7. How to Obtain Checked Builds of Windows
          8. How to Obtain Debugging Tools
          9. How to Obtain OSR Learning Devices
        4. Key Information Sources
          1. Key References
      2. 2. Windows Driver Fundamentals
        1. What Is a Driver?
          1. Core Windows Architecture
          2. Driver Architecture
            1. Device Objects and the Device Stack
            2. The Device Tree
        2. Kernel Objects and Data Structures
        3. The Windows I/O Model
          1. I/O Requests
          2. How a Device Stack Handles IRPs
          3. Data Buffers and I/O Transfer Types
          4. How to Transfer Data to or from a Device
        4. About Plug and Play and Power Management
        5. Basic Kernel-Mode Programming
          1. Interrupts and IRQLs
          2. Concurrency and Synchronization
            1. Threads
            2. Synchronization
            3. Race Conditions and Deadlocks
          3. Memory
            1. Memory Management
            2. Memory Pools
            3. The Kernel Stack
            4. MDLs
        6. Tips for Programming in Kernel Mode
          1. Allocating Memory
            1. Allocating Memory
            2. Using Spin Locks
            3. Managing Page Faults
            4. Accessing User-Mode Memory
            5. Blocking Threads
            6. Verifying Drivers
            7. Using Macros
        7. A Basic Vocabulary
      3. 3. WDF Fundamentals
        1. WDF and WDM
        2. What Is WDF?
        3. WDF Object Model
          1. Programming Interface
          2. Object Hierarchy
          3. Concurrency and Synchronization
        4. I/O Model
          1. I/O Request Cancellation
          2. I/O Targets
          3. How to Handle Nonfatal Errors
            1. Reporting UMDF Errors
            2. Reporting KMDF Errors
        5. Plug and Play and Power Management
        6. Security
          1. Safe Defaults
          2. Parameter Validation
        7. WDF Verification, Tracing, and Debugging Support
        8. Serviceability and Versioning
    5. II. Exploring the Frameworks
      1. 4. Overview of the Driver Frameworks
        1. The Frameworks: An Overview
        2. UMDF Overview
          1. UMDF Framework Objects
          2. UMDF Callback Objects
        3. KMDF Overview
          1. KMDF Objects
          2. KMDF Callback Functions
        4. WDF Architecture
        5. UMDF Infrastructure
          1. UMDF Infrastructure Components
          2. Fatal Errors in UMDF Drivers
          3. A Typical UMDF I/O Request
        6. KMDF Infrastructure
          1. KMDF Infrastructure Components
          2. Fatal Errors in KMDF Drivers
          3. A Typical KMDF I/O Request
        7. Device and Driver Support in WDF
          1. Devices Supported by UMDF
            1. Advantages of UMDF Drivers
            2. Limitations of UMDF drivers
          2. Devices Supported by KMDF
          3. Choosing the Right Framework
      2. 5. WDF Object Model
        1. Overview of the Object Model
          1. About Methods, Properties, and Events
          2. About Event Callbacks
          3. About Object Attributes
          4. About Object Hierarchy and Lifetime
          5. About Object Context
        2. UMDF Object Model Implementation
          1. UMDF Naming Conventions
            1. UMDF interface names
              1. UMDF interface names
              2. UMDF method names
              3. UMDF property names
              4. UMDF event callback interface names
          2. UMDF Framework Objects and Interfaces
          3. UMDF Driver Callback Objects and Interfaces
          4. UMDF Example: Objects and Callback Interfaces
        3. KMDF Object Model Implementation
          1. KMDF Object Types
          2. KMDF Naming Conventions
            1. KMDF method names
              1. KMDF method names
              2. KMDF property names
              3. KMDF event callback function names
        4. Object Creation
          1. UMDF Object Creation
          2. KMDF Object Creation
            1. KMDF Object Configuration Structure
            2. KMDF Object Attributes Structure
            3. KMDF Object Creation Methods
        5. Object Hierarchy and Lifetime
          1. UMDF Object Hierarchy
          2. KMDF Object Hierarchy
          3. Object Deletion
            1. Cleanup Callbacks
            2. Destroy Callbacks
            3. UMDF Object Deletion
            4. KMDF Object Deletion
        6. Object Context Areas
          1. UMDF Object Context Data
            1. UMDF Context Information in Callback Object Data Members
            2. UMDF Context Area for a Framework Object
          2. KMDF Object Context Area
            1. Type Declaration for a KMDF Context Area
            2. Initialization of the Context-Related Fields of the Object attributes structure
            3. Assignment of the KMDF Context Area to the Object
      3. 6. Driver Structure and Initialization
        1. Required Driver Components
          1. UMDF Driver Structure and Requirements
          2. KMDF Driver Structure and Requirements
            1. Driver unload functions
        2. Driver Object
          1. UMDF Driver Callback Object Creation
          2. KMDF Driver Object Creation
        3. Device Objects
          1. Types of Device Objects
            1. Filter Drivers and Filter Device Objects
            2. Function Drivers and Functional Device Objects
            3. Bus Drivers and Physical Device Objects (KMDF)
            4. Legacy Device Drivers and Control Device Objects (KMDF)
          2. WDF Drivers, Driver Types, and Device Object Types
          3. Device Properties
          4. Device Object Initialization
        4. Queues and Other Support Objects
        5. Device Interfaces
        6. UMDF Device Object Creation and Initialization
          1. Chapter 5 describes device callback objects
          2. Device Callback Object Creation
          3. Framework Device Object Creation and Initialization
            1. Chapter 5 explains the lifetime of the device object
          4. UMDF Example: Device Interface
        7. KMDF Device Object Creation and Initialization
          1. KMDF Device Initialization Structure
            1. KMDF Initialization for an FDO
            2. KMDF Initialization for a Filter DO
          2. Device Object Context Area
            1. Chapter 5 describes the object context area
          3. KMDF Device Object Creation
          4. Additional EvtDriverDeviceAdd Tasks
          5. KMDF Example: EvtDriverDeviceAdd Callback Function
        8. Child Device Enumeration (KMDF PDOs Only)
          1. Static and Dynamic Enumeration in Bus Drivers
            1. Dynamic Enumeration
            2. Static Enumeration
          2. PDO-Specific Initialization
        9. Device Naming Techniques for KMDF Drivers
          1. Named Device Objects
          2. Security Descriptors
    6. III. Applying WDF Fundamentals
      1. 7. Plug and Play and Power Management
        1. Introduction to Plug and Play and Power Management
          1. About Plug and Play
          2. About Power States
            1. “Highest powered state” uses the most power
              1. “Highest powered state” uses the most power
          3. About Power Policy
        2. Plug and Play and Power Management Support in WDF
          1. Plug and Play and Power Management Defaults
          2. I/O Queues and Power Management
          3. Plug and Play and Power Event Callbacks
            1. WDF automatically translates system power events to device power events
              1. WDF automatically translates system power events to device power events
          4. Idle and Wake Support (KMDF Only)
          5. Power-Pageable and Non-Power-Pageable Drivers
        3. Callback Sequences for Plug and Play and Power Management
          1. Common state changes that can trigger callbacks
            1. Common state changes that can trigger callbacks
              1. Common state changes that can trigger callbacks
          2. Device Enumeration and Startup
          3. Device Power-Down and Removal
          4. Surprise Removal
            1. UMDF Surprise-Removal Sequence
            2. KMDF Surprise-Removal Sequence
        4. How to Implement Plug and Play and Power Management in WDF Drivers
        5. Plug and Play and Power Management in Software-Only Drivers
          1. UMDF Example: Plug and Play in a Software-Only Filter Driver
            1. Chapter 6 describes initialization of device objects
              1. Chapter 6 describes initialization of device objects
          2. KMDF Example: Plug and Play in a Software-Only Filter Driver
          3. Framework Actions for Software-Only Drivers
        6. Plug and Play and Power Management in Simple Hardware Drivers
          1. Device Power-Up Initialization and Power-Down Teardown
          2. Power Management for Queues in Hardware Function Drivers
          3. UMDF Example: Plug and Play and Power Code in a Protocol Function Driver
            1. Power-Managed Queue for a UMDF Driver
            2. IPnpCallbackHardware Methods
            3. IPnpCallback Methods
          4. KMDF Example: Plug and Play and Power Code in a Simple Hardware Function Driver
            1. KMDF Example: Register Callbacks and Set Up Power-managed Queues
            2. KMDF Example: D0 Entry and D0 Exit Callbacks
          5. Framework Actions for a Simple Hardware Function Driver
        7. Advanced Power Management for KMDF Drivers
          1. Device Power-Down Idle Support for KMDF Drivers
            1. Idle Settings and Management in KMDF Drivers
            2. How to Choose Idle Times and Idle States in KMDF Drivers
          2. Device Wake Support for KMDF Drivers
            1. How wake and idle are related
              1. How wake and idle are related
            2. How to Implement Wake from Sx in KMDF Drivers
            3. How to Implement Wake from S0 in KMDF Drivers
          3. KMDF Example: Support for Device Idle and Wake
          4. Framework Actions Supporting Device Idle
          5. Framework Actions Supporting Device Wake
      2. 8. I/O Flow and Dispatching
        1. Common I/O Request Types
          1. Create Requests
          2. Cleanup and Close Requests
          3. Read and Write Requests
          4. Device I/O Control Requests
          5. Summary of I/O Request Types
        2. I/O Transfer Types
          1. Buffered I/O
          2. Direct I/O
          3. Neither Buffered nor Direct I/O
        3. I/O Request Flow
          1. I/O Request Path through the UMDF Device Stack
          2. I/O Request Path through a KMDF Driver
          3. I/O Completion Processing
            1. UMDF I/O Request Completion Processing
            2. KMDF I/O Request Completion Processing
            3. Windows I/O Request Completion Processing
          4. I/O Request Flow within the Frameworks
            1. IRP Preprocessing
            2. IRP Routing to the Internal Request Handler
          5. Processing in the I/O Request Handler
            1. Parameter Validation
            2. Request Processing in the I/O Handler
        4. I/O Request Objects
          1. I/O Buffers and Memory Objects
            1. Retrieving Buffers in UMDF Drivers
            2. Retrieving Buffers in KMDF Drivers
          2. Request, Memory, and Buffer Pointer Lifetimes
        5. I/O Queues
          1. Queue Configuration and Request Types
            1. How to Specify the Request Types for a Queue
            2. Queue Callbacks
            3. Default Queues
          2. Queues and Power Management
            1. Power-Managed Queues
            2. Non-Power-Managed Queues
              1. Chapter 7 describes WdfDevice-StopIdle
          3. Dispatch Type
            1. Chapter 10 describes synchronization scope for queues
              1. Chapter 10 describes synchronization scope for queues
          4. Queue Control
          5. UMDF Example: Creating I/O Queues
            1. UMDF Default Queue
            2. UMDF Nondefault Queue
            3. UMDF Manual I/O Queue
          6. KMDF Example: Creating I/O Queues
            1. KMDF Default Queue
            2. KMDF Nondefault Queue
          7. Retrieving Requests from a Manual Queue
        6. I/O Event Callbacks
          1. File Objects for I/O
          2. Automatic Forwarding of Create, Cleanup, and Close
          3. I/O Event Callbacks for Create Requests
            1. Handling Create Requests in a UMDF Driver
            2. Impersonation in UMDF Drivers
            3. Handling Create Requests in a KMDF Driver
          4. I/O Event Callbacks for Cleanup and Close
          5. I/O Event Callbacks for Read, Write, and Device I/O Control Requests
            1. Callbacks for Read and Write Requests
            2. Callbacks for Device I/O Control Requests
            3. Default I/O Callbacks
        7. Completing I/O Requests
          1. Chapter 5 describes object cleanup callbacks
            1. Chapter 5 describes object cleanup callbacks
              1. Chapter 5 describes object cleanup callbacks
        8. Canceled and Suspended Requests
          1. Request Cancellation
          2. Request Suspension
        9. Adaptive Time-outs in UMDF
        10. Self-Managed I/O
          1. Self-Managed I/O during Device Startup and Restart
          2. Self-Managed I/O during Device Power-Down and Removal
          3. KMDF Example: Implementing a Watchdog Timer
      3. 9. I/O Targets
        1. About I/O Targets
          1. Default I/O Targets
          2. Remote I/O Targets in KMDF Drivers
          3. General and Specialized I/O Targets
          4. UMDF I/O Target Implementation
            1. UMDF I/O Dispatchers
            2. Intra-Stack Files for I/O Targets in UMDF Drivers
        2. I/O Target Creation and Management
          1. Default I/O Target Retrieval
          2. Remote I/O Target Creation in KMDF Drivers
            1. Initialization Functions for the I/O Target Parameters Structure
            2. KMDF Example: Create and Open a Remote I/O Target
          3. I/O Target State Management
            1. Methods for Managing I/O Target State
            2. I/O Target Callbacks for KMDF Drivers
            3. KMDF Example: EvtIoTargetQueryRemove Callback
        3. I/O Request Creation
          1. UMDF Example: Create a WDF I/O Request Object
          2. KMDF Example: Create a WDF I/O Request Object
        4. Memory Objects and Buffers for Driver-Created I/O Requests
          1. Memory Object and Buffer Allocation for I/O Requests
            1. Create a Memory Object and a Buffer Simultaneously
            2. Create a Memory Object that Uses an Existing Buffer
            3. Association between Memory Object and I/O Request Object
          2. UMDF Example: Create a New Memory Object with an Existing Buffer
          3. KMDF Example: Create a New Memory Object and a New Buffer
        5. I/O Request Formatting
          1. How to Format an Unchanged Request for the Default I/O Target
          2. How to Format Changed or Driver-Created Requests
            1. Parameters for the Formatting Methods
            2. UMDF Example: Format a Write Request
            3. KMDF Example: Format a Read Request
          3. I/O Completion Callbacks
            1. Processing in the I/O Completion Callback
              1. Parameters for I/O completion callbacks
            2. Retrieving Completion Status and Information
        6. How to Send an I/O Request
          1. KMDF methods to format and send synchronous I/O requests
            1. KMDF methods to format and send synchronous I/O requests
              1. KMDF methods to format and send synchronous I/O requests
          2. Options for Sending Requests
            1. Flags for sending I/O requests
              1. Flags for sending I/O requests
            2. Time-Out Values for I/O Requests
            3. Synchronous and Asynchronous I/O Requests
            4. Effect of I/O Target State
            5. Send and Forget Option
          3. UMDF Example: Send a Request to the Default I/O Target
          4. KMDF Example: Send and Forget
          5. KMDF Example: Format and Send an I/O Request to an I/O Target
          6. How to Split an I/O Request into Smaller Requests
          7. KMDF Example: Reuse an I/O Request Object
          8. How to Cancel a Sent Request
            1. UMDF Example: How to Cancel All I/O Requests for a File
            2. KMDF Example: How to Cancel I/O Requests
        7. File Handle I/O Targets in UMDF Drivers
        8. USB I/O Targets
          1. About USB Devices
            1. Device and Configuration Descriptors
            2. USB Data Transfer Models
          2. Specialized USB I/O Targets in WDF
            1. USB Target Device Objects
            2. USB Interface Objects
            3. USB Target Pipe Objects
          3. How to Configure a USB I/O Target
            1. UMDF Example: Configure a USB I/O Target
            2. KMDF Example: Configure a USB I/O Target
          4. How to Send an I/O Request to a USB I/O Target
            1. UMDF Example: Send a Synchronous Request to a USB I/O Target
            2. KMDF Example: Send an Asynchronous Request to a USB I/O Target
          5. USB Continuous Reader in KMDF
        9. Guidelines for Sending I/O Requests
      4. 10. Synchronization
        1. When Synchronization Is Required
          1. Synchronized Access to Shared Data: An Example
          2. Synchronization Requirements for WDF Drivers
        2. WDF Synchronization Features
          1. Reference Counts and the Hierarchical Object Model
          2. Serialization of Plug and Play and Power Callbacks
          3. Flow Control for I/O Queues
          4. Object Presentation Lock
        3. Synchronization Scope and I/O Callback Serialization
          1. Device Scope and Queue Dispatch Methods
          2. Synchronization Scope in UMDF Drivers
          3. Synchronization Scope in KMDF Drivers
            1. Chapter 5 covers the object hierarchy
              1. Queue scope and file objects
            2. KMDF Example: Synchronization Scope
            3. Automatic Serialization for KMDF DPC, Timer, and Work Item Callbacks
            4. Execution Level in KMDF Drivers
              1. Chapter 15 describes IRQL guidelines
              2. Exception for file callbacks
        4. KMDF Wait Locks and Spin Locks
          1. Wait Locks
          2. Spin Locks
            1. Types of Spin Locks
              1. Chapter 16 describes interrupt spin locks
              2. Chapter 15 describes the IRQL guidelines
            2. KMDF Example: Spin Locks
        5. Synchronization of I/O Request Cancellation in KMDF Drivers
          1. Chapter 8 describes how the framework cancels I/O requests
            1. Chapter 8 describes how the framework cancels I/O requests
              1. Chapter 8 describes how the framework cancels I/O requests
          2. Synchronized Cancellation by Using Synchronization Scope
          3. Synchronized Cancellation by Tracking State in the Request Context
          4. Synchronized Cancellation of Incoming Request with Driver-Created Subrequests
            1. Chapter 12 describes collection objects
              1. Chapter 12 describes collection objects
        6. Summary and General Tips for Synchronization
      5. 11. Driver Tracing and Diagnosability
        1. WPP Software Tracing Basics
          1. Advantages of WPP Software Tracing
          2. WPP Software Tracing Components
          3. WPP and ETW
            1. About the trace message header file
              1. About the trace message header file
          4. ETW in Windows Vista
        2. Trace Message Functions and Macros
          1. DoTraceMessage Macro
          2. How to Convert Debug Print Statements to ETW
          3. Message Conditions
          4. Custom Trace Message Functions
        3. How to Support Software Tracing in a Driver
          1. Modify Sources to Run the WPP Preprocessor
            1. UMDF Example: RUN_WPP for the Fx2_Driver Sample
            2. Fx2_Driver Custom Trace Message
            3. KMDF Example: RUN_WPP for the Osrusbfx2 Sample
          2. Include the TMH File
            1. UMDF Example: Including the TMH File
            2. KMDF Example: Including the TMH File
          3. Define the Control GUID and Trace Flags
            1. UMDF Example: Defining the Control GUID and Trace Flag Names
            2. KMDF Example: Defining WPP_CONTROL_GUIDS and Trace Flag Names
          4. Initialize and Clean Up Tracing
            1. Initialize Tracing
            2. UMDF Example: Initialize Tracing in DllMain
            3. KMDF Example: Initializing Tracing in DriverEntry
            4. Clean Up Tracing
            5. UMDF Example: Clean Up Tracing in DllMain
            6. KMDF Example: Cleaning up Tracing in EvtCleanupCallback
          5. Instrument the Driver Code
            1. UMDF Example: Adding Trace Message Calls to Driver Code
            2. KMDF Example: Adding Trace Message Calls to Driver Code
        4. Tools for Software Tracing
        5. How to Run a Software Trace Session
          1. Prepare the Sample
          2. View a Driver Trace Log by Using TraceView
            1. How to Create and View a Trace Log File
            2. How to View a Trace Log in Real Time
          3. View the Frameworks Trace Log by Using the Core Tracing Tools
        6. Best Practices: Design for Diagnosability
      6. 12. WDF Support Objects
        1. Memory Allocation
          1. Local Storage
          2. Memory Objects and I/O Buffers
            1. UMDF Memory Objects and Interfaces
            2. KMDF Memory Objects and Methods
        2. Registry Access
          1. UMDF Device Property Store
          2. KMDF Registry Objects and Methods
            1. Sample code to read and write the registry
              1. Sample code to read and write the registry
        3. General Objects
          1. UMDF Example: How to Create a General Object
          2. KMDF Example: How to Create a General Object
        4. KMDF Collection Objects
          1. Collection Methods
          2. Example: Creating and Using a Collection
        5. KMDF Timer Objects
          1. Timer Object Methods
          2. Time Periods
          3. EvtTimerFunc Callback Function
          4. Example: Using a Timer Object
        6. WMI Support in a KMDF Driver
          1. About WMI
          2. Requirements for WMI Support
          3. How to Initialize WMI Support
            1. MOF Resource
            2. WMI Provider Object
            3. WMI Instance Objects
            4. Example: Sample Code to Initialize WMI Support
          4. WMI Instance Event Callbacks
            1. Example: Code to Query a WMI Instance
            2. Example: Code to Set a WMI Instance
            3. Example: Code to Set a WMI Data Item
      7. 13. UMDF Driver Template
        1. A Description of the Skeleton Sample
          1. About the Skeleton Sample
          2. About the Skeleton Sample Files
            1. Source Files
            2. Build Support Files
            3. Installation Support Files
        2. How to Customize the Skeleton Sample Source Files
          1. DLL Infrastructure
            1. DllMain
            2. DllGetClassObject
          2. Basic COM Support
            1. CUnknown
            2. CClassFactory
          3. Skeleton Sample Driver Callback Object
            1. CreateInstance
            2. IUnknown
            3. IDriverEntry
          4. The Skeleton Sample Device Callback Object
            1. Utility Methods for the Device Callback Object
            2. IUnknown
            3. Optional Interfaces
        3. How to Customize the Skeleton Sample Build and Installation Support Files
          1. Sources
          2. Make Files
          3. Exports
          4. Version Resource File
          5. INX File
    7. IV. Additional Topics for KMDF Drivers
      1. 14. Beyond the Frameworks
        1. How to Use System Services Outside the Frameworks
          1. How to Use the Windows API in UMDF Drivers
          2. How to Use Kernel-Mode Driver Support Routines in KMDF Drivers
        2. How to Handle Requests that the Frameworks Do Not Support
          1. Default Handling of Unsupported Requests
          2. How to Process Unsupported Requests in KMDF Drivers
            1. Example: Establishing the Preprocess Callback Function in EvtDriverDeviceAdd
            2. Example: Processing in the EvtDeviceWdmPreprocessIrp Callback Function
      2. 15. Scheduling, Thread Context, and IRQL
        1. About Threads
          1. Thread Scheduling
          2. Thread Context Defined
          3. Thread Context for KMDF Driver Functions
        2. Interrupt Request Levels
          1. Processor-specific and Thread-specific IRQLs
            1. IRQL PASSIVE_LEVEL
            2. IRQL PASSIVE_LEVEL in a Critical Region
            3. IRQL APC_LEVEL
            4. IRQL DISPATCH_LEVEL
            5. IRQL DIRQL
            6. IRQL HIGH_LEVEL
          2. Guidelines for Running at IRQL DISPATCH_LEVEL or Higher
          3. Calls to Functions that Run at a Lower IRQL
        3. Thread Interruption Scenarios
          1. Thread Interruption on a Single-Processor System
          2. Thread Interruption on a Multiprocessor System
          3. Testing for IRQL Problems
            1. Techniques for Finding the Current IRQL
            2. PAGED_CODE and PAGED_CODE_LOCKED Macros
            3. Driver Verifier Options
        4. Work Items and Driver Threads
          1. About Work Items
          2. KMDF Example: Use a Work Item
        5. Best Practices for Managing Thread Context and IRQL in KMDF Drivers
      3. 16. Hardware Resources and Interrupts
        1. Hardware Resources
          1. Hardware Resource Identification and Teardown
          2. Resource Lists
          3. Example: How to Map Resources
          4. Example: How to Unmap Resources
        2. Interrupts and Interrupt Handling
          1. Interrupt Objects
            1. Interrupt Object Configuration Structure
            2. Interrupt Object Attributes
            3. Interrupt Object Creation
          2. How to Enable and Disable Interrupts
          3. Post-interrupt Enable and Pre-interrupt Disable Processing
          4. Interrupt Service Routines
          5. Deferred Processing for Interrupts
          6. Synchronized Processing at DIRQL
      4. 17. Direct Memory Access
        1. Basic DMA Concepts and Terminology
          1. DMA Transactions and DMA Transfers
          2. Packet-Based and Common-Buffer DMA
            1. Packet-Based DMA Device Design
            2. Common-Buffer DMA Device Design
            3. Hybrid Device Designs
          3. Scatter/Gather Support
        2. DMA-Specific Device Information
          1. Device Information and DMA Driver Design
            1. DMA Design Type
            2. Device Addressing Capability
            3. Hardware Scatter/Gather Capability
            4. Maximum Transfer Length
            5. Buffer Alignment Requirements
          2. What Is Not a Consideration
        3. Windows DMA Abstraction
          1. DMA Operations and Processor Cache
          2. Completion of DMA Transfers by Flushing Caches
          3. Map Registers
            1. Map Registers: The Concept
            2. Map Registers: The Implementation
            3. When Map Registers Are Used
          4. System Scatter/Gather Support
            1. System Scatter/Gather: The Concept
            2. System Scatter/Gather: The Implementation
          5. DMA Transfer to Any Location in Physical Memory
            1. DMA Transfer to Any Location: The Concept
            2. DMA Transfer to Any Location: The Implementation
        4. Implementing DMA Drivers
          1. Driver DMA Initialization
            1. The DMA Enabler Object
            2. The Common-Buffer Object
            3. The DMA Transaction Object
            4. Example: Driver DMA Initialization
          2. Transaction Initiation
            1. Transaction Initialization
            2. Transaction Execution
            3. Example: Transaction Initiation
          3. Request Processing
            1. EvtProgramDma Function Definition
            2. EvtProgramDma Function Tasks
            3. Example: Request Processing
          4. DMA Completion Processing
            1. Transfer, Transaction, and Request Completion
            2. Example: DMA Completion Processing
        5. Testing DMA Drivers
          1. DMA-Specific Verification
          2. The !dma Debugger Extension
          3. KMDF Debugger Extensions for DMA
        6. Best Practices: Do’s and Don’ts for DMA Drivers
      5. 18. An Introduction to COM
        1. Before Starting
        2. UMDF Driver Structure
        3. A Brief Overview of COM
          1. The Contents of a COM Object
          2. Objects and Interfaces
          3. IUnknown
          4. Reference Counting
          5. Guidelines for AddRef and Release
          6. GUIDs
          7. VTables
          8. HRESULT
          9. Properties and Events
          10. Active Template Library
          11. Interface Definition Language Files
        4. How to Use UMDF COM Objects
          1. How to Start Using a COM Object
            1. Receive an Interface through a Callback Method
            2. Call a UMDF Object Creation Method
            3. Call QueryInterface to Request a New Interface
          2. How to Manage a COM Object’s Lifetime
        5. How to Implement the DLL Infrastructure
          1. DllMain
          2. DllGetClassObject
          3. The Class Factory
            1. How to Implement a Class Factory
            2. Objects That Do Not Require a Class Factory
        6. How to Implement UMDF Callback Objects
          1. How to Implement a Class for a COM Object
          2. How to Implement IUnknown
            1. AddRef and Release
            2. QueryInterface
          3. How to Implement UMDF Callback Objects
    8. V. Building, Installing, and Testing a WDF Driver
      1. 19. How to Build WDF Drivers
        1. General Build Considerations for Drivers
          1. UMDF Drivers—Build Issues
          2. KMDF Drivers—Build Issues
        2. Introduction to Building Drivers
          1. Build Environments
          2. Build Utility Supporting Files
            1. Required Files
            2. Optional Files
            3. Project File Limitations
          3. How to Build a Project
            1. Common Build.exe Flags
            2. Common Build Output Files
        3. UMDF Example: Building the Fx2_Driver Sample
          1. Sources File for Fx2_Driver
          2. Macros Used in the Sources File for Fx2_Driver
            1. UMDF Version Numbers
            2. Standard Targets
            3. Custom Targets
            4. Source Files, Headers, and Libraries
            5. Build Configuration
          3. Makefile and Makefile.inc for Fx2_Driver
          4. How to Build Fx2_Driver
        4. KMDF Example: Building the Osrusbfx2 Sample
          1. Sources File for Osrusbfx2
          2. Macros Used in the Sources File for Osrusbfx2
            1. KMDF Version Number
            2. Standard Targets
            3. Custom Targets
            4. Source Files, Headers, and Libraries
            5. Build Configuration
          3. Makefile and Makefile.inc for Osrusbfx2
          4. How to Build Osrusbfx2
      2. 20. How to Install WDF Drivers
        1. Driver Installation Basics
          1. Key Driver Installation Tasks
          2. Installation Techniques and Tools
        2. WDF Driver Installation Considerations
          1. WDF Versioning and Driver Installation
            1. Minor Version Updates
            2. Major Version Updates
            3. Framework Distribution
          2. How Drivers Bind to the Framework
          3. WDF Co-installer Packages
            1. UMDF Co-installer Package
            2. KMDF Co-installer Package
        3. WDF Driver Package Components
        4. How to Create an INF for a WDF Driver Package
          1. Commonly Used INF Sections
          2. INF Tools
          3. INFs for Different CPU Architectures
          4. INFs for WDF Drivers: The Co-installer Sections
        5. Examples of WDF INFs
          1. UMDF Example: The Fx2_Driver INF
            1. The key Fx2_Driver INF co-installer sections
              1. The key Fx2_Driver INF co-installer sections
          2. KMDF Example: The Osrusbfx2 INF
            1. The key Osrusbfx2 INF co-installer sections
              1. The key Osrusbfx2 INF co-installer sections
        6. How to Sign and Distribute a Driver Package
          1. Signed Catalog Files
          2. How to Specify the Catalog File in the INF
          3. How to Sign Boot-Start Drivers
        7. How to Distribute the Driver Package
        8. How to Install a Driver
          1. Considerations for Test Installations
          2. Considerations for Release Installations
          3. How to Install a Driver by Using the PnP Manager
          4. How to Install a Driver by Using DPInst or DIFxApp
          5. How to Install a Driver by Using a Custom Installation Application
          6. How to Install or Update a Driver by Using DevCon
          7. How to Update a Driver by Using Device Manager
          8. How to Uninstall a Driver
          9. Driver Installation Process
          10. Uninstall Actions
            1. Tools for Uninstalling Drivers and Devices
        9. How to Troubleshoot WDF Driver Installation Problems
          1. How to Use WinDbg to Debug Installation Errors
          2. Driver Installation Error Logs
          3. Common WDF Installation Errors
            1. Fatal Error during Installation
          4. PnP Manager Error Codes
      3. 21. Tools for Testing WDF Drivers
        1. Getting Started with Driver Testing
          1. Choosing a Test System
            1. Recommended test system capabilities
              1. Recommended test system capabilities
          2. Tools for Testing WDF Drivers: An Overview
          3. About PREfast and SDV
          4. Other Tools for Testing Drivers
            1. INF File Syntax Checker (ChkINF)
            2. Device Console (DevCon)
            3. Device Path Exerciser (Dc2)
            4. KernRate and the KernRate Viewer (KRView)
            5. Plug and Play Driver Test (Pnpdtest)
            6. Plug and Play CPU Test (PNPCPU)
            7. Memory Pool Monitor (PoolMon)
            8. Power Management Test Tool (PwrTest)
            9. Windows Device Testing Framework
        2. Driver Verifier
          1. When to Use Driver Verifier
          2. How Driver Verifier Works
          3. How to Run Driver Verifier
          4. Driver Verifier Examples
            1. Example 1: Activate Standard Options for a List of Drivers
            2. Example 2: Activate Specific Options for All Drivers
            3. Example 3: Start or Stop the Verification of a Driver without Rebooting
            4. Example 4: Activate or Deactivate Options without Rebooting
            5. Example 5: Deactivate All Driver Verifier Options
            6. Example 6: Deactivate Driver Verifier
            7. Example 7: Use Low Resources Simulation
            8. Example 8: Use Force IRQL Checking
          5. How to Use Driver Verifier Information during Debugging
            1. Example 1: Use !verifier to View Stack Traces
            2. Example 2: Use !verifier to Display Fault and Pool Allocation Counters
        3. KMDF Verifier
          1. When to Use KMDF Verifier
          2. How KMDF Verifier Works
          3. How to Enable KMDF Verifier
          4. How to Use KMDF Verifier Information during Debugging
        4. UMDF Verifier
          1. UMDF Bug Checks
          2. UMDF Error Reporting
        5. Application Verifier
          1. How Application Verifier Works
          2. How to Use Application Verifier to Verify UMDF Drivers
        6. Best Practices for Testing WDF Drivers
          1. Tips for Building Drivers
          2. Tips for Best Use of Tools
          3. Tips for Driver Life Cycle Testing
      4. 22. How to Debug WDF Drivers
        1. About WDF Debugging Tools
          1. WinDbg
          2. Other Tools
          3. WPP Tracing
          4. Debugging Macros and Routines
        2. WinDbg Basics
          1. Checked versus Free Builds
          2. User Interface
          3. Debugger Commands
          4. Symbols and Source Code
          5. Debugger Extensions
        3. How to Prepare for UMDF Debugging
          1. How to Enable Debugging of Driver Load and Startup Code
          2. How to Start Debugging a UMDF Driver’s Driver Load and Startup Code
          3. How to Start Debugging a Running UMDF Driver
          4. How to Track UMDF Objects and Reference Counts
          5. How to Start Debugging a UMDF Driver Crash
        4. How to Prepare for KMDF Debugging
          1. How to Enable Kernel Debugging on the Test Computer
            1. How to Enable Kernel Debugging for Windows Vista
            2. How to Enable Kernel Debugging for Earlier Versions of Windows
          2. How to Prepare the Test Computer for KMDF Debugging
          3. How to Start a KMDF Debugging Session
          4. How to Start Debugging a KMDF Driver Crash
        5. UMDF Walkthrough: Debugging the Fx2_Driver Sample
          1. Prepare to Debug Fx2_Driver
          2. Start the Debug Session for Fx2_Driver
          3. Examine the OnDeviceAdd Callback Routine for Fx2_Driver
          4. Use UMDF Debugger Extensions to Examine the Device Callback Object
          5. Use UMDF Debugger Extensions to Examine an I/O Request
        6. KMDF Walkthrough: Debugging the Osrusbfx2 Sample
          1. Prepare for a Debug Session for Osrusbfx2
          2. Start the Debug Session for Osrusbfx2
          3. Examine the EvtDriverDeviceAdd Callback Routine
          4. Use KMDF Debugger Extensions to Examine the Device Object
          5. Use KMDF Debugger Extensions to Examine an I/O Request
        7. How to View Trace Messages with WinDbg
        8. How to Use WinDbg to View the KMDF Log
          1. Getting Log Information after a Bug Check
          2. Controlling the Contents of the KMDF Log
        9. More Suggestions for Experimenting with WinDbg
      5. 23. PREfast for Drivers
        1. Introduction to PREfast
          1. How PREfast Works
          2. What PREfast Can Detect
        2. How to Use PREfast
          1. How to Specify the PREfast Analysis Mode
          2. How to Run PREfast
          3. How to Build the PREfast Examples
          4. How to Display PREfast Results
            1. PREfast Defect Log Viewer
            2. PREfast Defect Log Text Output
          5. Examples of PREfast Results
            1. Example 1: Uninitialized Variables and NULL Pointers
            2. Example 2: Implicit Order of Evaluation
            3. Example 3: Calling a Function at Incorrect IRQL
            4. Example 4: Valid Error Reported in the Wrong Place
            5. Example 5: Function Type Class Mismatch
            6. Example 6: Incorrect Enumerated Type
        3. Coding Practices that Improve PREfast Results
          1. Warnings that Indicate Common Causes of Noise and What to Do About Them
          2. How to Use Pragma Warning Directives to Suppress Noise
          3. How to Use Annotations to Eliminate Noise
        4. How to Use Annotations
          1. How Annotations Improve PREfast Results
          2. Where to Place Annotations in Code
            1. Annotations on Functions and Function Parameters
            2. Annotations on typedef Declarations
            3. Annotations on Function Typedef Declarations
            4. Tips for Placing Annotations in Source Code
        5. General-Purpose Annotations
          1. Primitive versus composite annotations
            1. Primitive versus composite annotations
              1. Primitive versus composite annotations
          2. Input and Output Parameter Annotations
            1. The __in and __out Contract
            2. __in, __out, and __inout versus IN, OUT, and IN OUT
          3. Annotation Modifiers
            1. The _opt Modifier
            2. The _deref Modifier
          4. Buffer-Size Annotations
            1. Fixed-Size Buffer Annotations
            2. Summary of Annotations for Buffers
            3. Tips for Applying Annotations to Buffers
            4. Buffer Annotation Examples
          5. String Annotations
            1. __nullterminated
            2. __nullnullterminated
            3. __possibly_notnullterminated
          6. Reserved Parameters
          7. Function Return Values
        6. Driver Annotations
          1. Basic Driver Annotations and Conventions
          2. Conditional Annotations
            1. Examples of Nested Conditional Annotations
            2. Grammar for Conditional Expressions
            3. Special Functions in Conditions
          3. Function Result Annotations
          4. Type-Matching Annotations
          5. Pointer Annotations
          6. Constant and Non-Constant Parameter Annotations
          7. Format String Annotations
          8. Diagnostic Annotations
            1. Annotations for Preferred Functions
            2. Annotations for Error Messages
          9. Annotations for Functions in __try Statements
          10. Memory Annotations
            1. Annotations for Allocating and Freeing Memory
            2. Annotations for Aliasing Memory
          11. Nonmemory Resource Annotations
            1. Annotations for Acquisition and Release of Nonmemory Resources
            2. Annotations for Global Nonmemory Resources
            3. Annotations for the Critical Region and Cancel Spin Lock
            4. Annotations for Holding and Not Holding Nonmemory Resources
            5. Composite Annotations for Resources
          12. Function Type Class Annotations
            1. Annotations for Identifying the Function Type Class of a Function
            2. Annotations for Checking a Function Type Class in a Conditional Expression
          13. Floating-Point Annotations
          14. IRQL Annotations
            1. Annotations for Specifying Maximum and Minimum IRQL
            2. Annotations for Specifying Explicit IRQL
            3. Annotations for Raising or Lowering IRQL
            4. Annotations for Saving and Restoring IRQL
            5. Annotations for Maintaining the Same IRQL
            6. Annotations for Saving and Restoring IRQL for I/O Cancellation Routines
            7. IRQL Annotation Examples
            8. Tips for Applying IRQL Annotations
          15. DO_DEVICE_INITIALIZING Annotation
          16. Annotations for Interlocked Operands
          17. Examples of Annotated System Functions
        7. How to Write and Debug Annotations
          1. Examples of Annotation Test Cases
          2. Tips for Writing Annotation Test Cases
        8. PREfast Best Practices
          1. Best Practices for Using PREfast
          2. Best Practices for Using Annotations
        9. Example: Osrusbfx2.h with Annotations
      6. 24. Static Driver Verifier
        1. Introduction to SDV
          1. SDV works with these kinds of drivers
            1. SDV works with these kinds of drivers
              1. SDV works with these kinds of drivers
        2. How SDV Works
          1. About SDV Rules
          2. How SDV Applies Rules to Driver Code
        3. How to Annotate KMDF Driver Source Code for SDV
          1. Function Role Type Declarations for KMDF Drivers
          2. Example: Function Role Types in Sample Drivers
        4. How to Run SDV
          1. How to Prepare Files and Select Rules for SDV
          2. About the SDV Options file
            1. About the SDV Options file
              1. About the SDV Options file
            2. How to Clean a Driver’s Sources Directory
            3. How to Process Libraries Used by the Driver
            4. How to Scan Driver Source Code to Create an Sdv-map.h File
          3. How to Run a Verification
          4. Experimenting with SDV
        5. How to View SDV Reports
          1. About SDV Defect Viewer
          2. Best Practice: Check SDV Results
          3. SDV known issues
            1. SDV known issues
              1. SDV known issues
        6. KMDF Rules for SDV
          1. DDI Order Rules for KMDF
          2. Device Initialization Rules for KMDF
          3. Control Device Cleanup Rules for KMDF
          4. Request-Completion Rules for KMDF
          5. Request-Cancellation Rules for KMDF
          6. Request Buffer, MDL, and Memory Rules
            1. Request Buffer Rules
            2. Request MDL Rules
            3. Request Memory Rules
          7. Power Policy Owner DDI Rules
        7. Example: Walkthrough SDV Analysis of Fail_Driver3
          1. How to Prepare to Verify Fail_Driver3
            1. Building the Fail_Driver3 Library by using SDV
            2. Creating the Sdv-map.h file for Fail_Driver3
          2. How to Verify Fail_Driver3
          3. How to View the Results for Fail_Driver3
            1. Reviewing the Rule for a Violation in Fail_Driver3
            2. Stepping through the Defect Trace for a Violation in Fail_Driver3
        8. KMDF Callback Function Role Types for SDV
    9. Glossary
    10. A. Microsoft Press Support Information
    11. Index
    12. About the Authors
    13. Copyright

    Product information

    • Title: Developing Drivers with the Windows® Driver Foundation
    • Author(s): Penny Orwick Microsoft Corporation and Guy Smith
    • Release date: April 2007
    • Publisher(s): Microsoft Press
    • ISBN: 9780735623743