Table of Contents
Acknowledgments
Introduction
1 Beginning a Driver Project
1.1 A Brief History of Device Drivers
1.2 An Overview of the Operating Systems
1.2.1 Windows XP Overview
1.2.2 Windows 98/Windows Me Overview
1.3 What Kind of Driver Do I Need?
1.3.1 WDM Drivers
1.3.2 Other Types of Drivers
1.3.3 Management Overview and Checklist
2 Basic Structure of a WDM Driver
2.1 How Drivers Work
2.1.1 How Applications Work
2.1.2 Device Drivers
2.2 How the System Finds and Loads Drivers
2.2.1 Device and Driver Layering
2.2.2 Plug and Play Devices
2.2.3 Legacy Devices
2.2.4 Recursive Enumeration
2.2.5 Order of Driver Loading
2.2.6 IRP Routing
2.3 The Two Basic Data Structures
2.3.1 Driver Objects
2.3.2 Device Objects
2.4 The DriverEntry Routine
2.4.1 Overview of DriverEntry
2.4.2 DriverUnload
2.5 The AddDevice Routine
2.5.1 Creating a Device Object
2.5.2 Naming Devices
2.5.3 Other Global Device Initialization
2.5.4 Putting the Pieces Together
2.6 Windows 98/Me Compatibility Notes
2.6.1 Differences in DriverEntry Call
2.6.2 DriverUnload
2.6.3 The \GLOBAL?? Directory
2.6.4 Unimplemented Device Types
3 Basic Programming Techniques
3.1 The Kernel-Mode Programming Environment
3.1.1 Using Standard Run-Time Library Functions
3.1.2 A Caution About Side Effects
3.2 Error Handling
3.2.1 Status Codes
3.2.2 Structured Exception Handling
3.2.3 Bug Checks
3.3 Memory Management
3.3.1 User-Mode and Kernel-Mode Address Spaces
3.3.2 Heap Allocator
3.3.3 Linked Lists
3.3.4 Lookaside Lists
3.4 String Handling
3.5 Miscellaneous Programming Techniques
3.5.1 Accessing the Registry
3.5.2 Accessing Files
3.5.3 Floating-Point Calculations
3.5.4 Making Debugging Easier
3.6 Windows 98/Me Compatibility Notes
3.6.1 File I/O
3.6.2 Floating Point
4 Synchronization
4.1 An Archetypal Synchronization Problem
4.2 Interrupt Request Level
4.2.1 IRQL in Operation
4.2.2 IRQL Compared with Thread Priorities
4.2.3 IRQL and Paging
4.2.4 Implicitly Controlling IRQL
4.2.5 Explicitly Controlling IRQL
4.3 Spin Locks
4.3.1 Some Facts About Spin Locks
4.3.2 Working with Spin Locks
4.3.3 Queued Spin Locks
4.4 Kernel Dispatcher Objects
4.4.1 How and When You Can Block
4.4.2 Waiting on a Single Dispatcher Object
4.4.3 Waiting on Multiple Dispatcher Objects
4.4.4 Kernel Events
4.4.5 Kernel Semaphores
4.4.6 Kernel Mutexes
4.4.7 Kernel Timers
4.4.8 Using Threads for Synchronization
4.4.9 Thread Alerts and APCs
4.5 Other Kernel-Mode Synchronization Primitives
4.5.1 Fast Mutex Objects
4.5.2 Interlocked Arithmetic
4.5.3 Interlocked List Access
4.5.4 Windows 98/Me Compatibility Notes
5 The I/O Request Packet
5.1 Data Structures
5.1.1 Structure of an IRP
5.1.2 The I/O Stack
5.2 The “Standard Model” for IRP Processing
5.2.1 Creating an IRP
5.2.2 Forwarding to a Dispatch Routine
5.2.3 Duties of a Dispatch Routine
5.2.4 The StartIo Routine
5.2.5 The Interrupt Service Routine
5.2.6 Deferred Procedure Call Routine
5.3 Completion Routines
5.4 Queuing I/O Requests
5.4.1 Using the DEVQUEUE Object
5.4.2 Using Cancel-Safe Queues
5.5 Cancelling I/O Requests
5.5.1 If It Weren’t for Multitasking…
5.5.2 Synchronizing Cancellation
5.5.3 Some Details of IRP Cancellation
5.5.4 How the DEVQUEUE Handles Cancellation
5.5.5 Cancelling IRPs You Create or Handle
5.5.6 Handling IRP_MJ_CLEANUP
5.5.7 Cleanup with a DEVQUEUE
5.5.8 Cleanup with a Cancel-Safe Queue
5.6 Summary—Eight IRP-Handling Scenarios
5.6.1 Scenario 1—Pass Down with Completion Routine
5.6.2 Scenario 2—Pass Down Without Completion Routine
5.6.3 Scenario 3—Complete in the Dispatch Routine
5.6.4 Scenario 4—Queue for Later Processing
5.6.5 Scenario 5—Your Own Asynchronous IRP
5.6.6 Scenario 6—Your Own Synchronous IRP
5.6.7 Scenario 7—Synchronous Pass Down
5.6.8 Scenario 8—Asynchronous IRP Handled Synchronously
6 Plug and Play for Function Drivers
6.1 IRP_MJ_PNP Dispatch Function
6.2 Starting and Stopping Your Device
6.2.1 IRP_MN_START_DEVICE
6.2.2 IRP_MN_STOP_DEVICE
6.2.3 IRP_MN_REMOVE_DEVICE
6.2.4 IRP_MN_SURPRISE_REMOVAL
6.3 Managing PnP State Transitions
6.3.1 Starting the Device
6.3.2 Is It OK to Stop the Device?
6.3.3 While the Device Is Stopped
6.3.4 Is It OK to Remove the Device?
6.3.5 Synchronizing Removal
6.3.6 Why Do I Need This @#$! Remove Lock, Anyway?
6.3.7 How the DEVQUEUE Works with PnP
6.4 Other Configuration Functionality
6.4.1 Filtering Resource Requirements
6.4.2 Device Usage Notifications
6.4.3 PnP Notifications
6.5 Windows 98/Me Compatibility Notes
6.5.1 Surprise Removal
6.5.2 PnP Notifications
6.5.3 The Remove Lock
7 Reading and Writing Data
7.1 Configuring Your Device
7.2 Addressing a Data Buffer
7.2.1 Specifying a Buffering Method
7.3 Ports and Registers
7.3.1 Port Resources
7.3.2 Memory Resources
7.4 Servicing an Interrupt
7.4.1 Configuring an Interrupt
7.4.2 Handling Interrupts
7.4.3 Deferred Procedure Calls
7.4.4 A Simple Interrupt-Driven Device
7.5 Direct Memory Access
7.5.1 Transfer Strategies
7.5.2 Performing DMA Transfers
7.5.3 Using a Common Buffer
7.5.4 A Simple Bus-Master Device
7.6 Windows 98/Me Compatibility Notes
8 Power Management
8.1 The WDM Power Model
8.1.1 The Roles of WDM Drivers
8.1.2 Device Power and System Power States
8.1.3 Power State Transitions
8.1.4 Handling IRP_MJ_POWER Requests
8.2 Managing Power Transitions
8.2.1 Required Infrastructure
8.2.2 Initial Triage
8.2.3 System Power IRPs That Increase Power
8.2.4 System Power IRPs That Decrease Power
8.2.5 Device Power IRPs
8.2.6 Flags to Set in AddDevice
8.3 Additional Power-Management Details
8.3.1 Device Wake-Up Features
8.3.2 Powering Off When Idle
8.3.3 Using Sequence Numbers to Optimize State Changes
8.4 Windows 98/Me Compatibility Notes
8.4.1 The Importance of DO_POWER_PAGABLE
8.4.2 Completing Power IRPs
8.4.3 Requesting Device Power IRPs
8.4.4 PoCallDriver
8.4.5 Other Differences
9 I/O Control Operations
9.1 The DeviceIoControl API
9.1.1 Synchronous and Asynchronous Calls to DeviceIoControl
9.1.2 Defining I/O Control Codes
9.2 Handling IRP_MJ_DEVICE_CONTROL
9.3 METHOD_BUFFERED
9.3.1 The DIRECT Buffering Methods
9.3.2 METHOD_NEITHER
9.3.3 Designing a Safe and Secure IOCTL Interface
9.4 Internal I/O Control Operations
9.5 Notifying Applications of Interesting Events
9.5.1 Using a Shared Event for Notification
9.5.2 Using a Pending IOCTL for Notification
9.6 Windows 98/Me Compatibility Notes
10 Windows Management Instrumentation
10.1 WMI Concepts
10.1.1 A Sample Schema
10.1.2 Mapping WMI Classes to C Structures
10.2 WDM Drivers and WMI
10.2.1 Delegating IRPs to WMILIB
10.2.2 Advanced Features
10.3 Windows 98/Me Compatibility Notes
11 Controller and Multifunction Devices
11.1 Overall Architecture
11.1.1 Child Device Objects
11.2 Handling PnP Requests
11.2.1 Telling the PnP Manager About Our Children
11.2.2 PDO Handling of PnP Requests
11.2.3 Handling Device Removal
11.2.4 Handling IRP_MN_QUERY_ID
11.2.5 Handling IRP_MN_QUERY_DEVICE_RELATIONS
11.2.6 Handling IRP_MN_QUERY_INTERFACE
11.2.7 Handling IRP_MN_QUERY_PNP_DEVICE_STATE
11.3 Handling Power Requests
11.4 Handling Child Device Resources
12 The Universal Serial Bus
12.1 Programming Architecture
12.1.1 Device Hierarchy
12.1.2 What’s in a Device?
12.1.3 Information Flow
12.1.4 Descriptors
12.2 Working with the Bus Driver
12.2.1 Initiating Requests
12.2.2 Configuration
12.2.3 Managing Bulk Transfer Pipes
12.2.4 Managing Interrupt Pipes
12.2.5 Control Requests
12.2.6 Managing Isochronous Pipes
12.2.7 Idle Power Management for USB Devices
13 Human Interface Devices
13.1 Drivers for HID Devices
13.2 Reports and Report Descriptors
13.2.1 Sample Keyboard Descriptor
13.2.2 HIDFAKE Descriptor
13.3 HIDCLASS Minidrivers
13.3.1 DriverEntry
13.3.2 Driver Callback Routines
13.3.3 Internal IOCTL Interface
13.3.4 IOCTL_HID_GET_DEVICE_DESCRIPTOR
13.4 Windows 98/Me Compatibility Notes
13.4.1 Handling IRP_MN_QUERY_ID
13.4.2 Joysticks
14 Specialized Topics
14.1 Logging Errors
14.1.1 Creating an Error Log Packet
14.1.2 Creating a Message File
14.2 System Threads
14.2.1 Creating and Terminating System Threads
14.2.2 Using a System Thread for Device Polling
14.3 Work Items
14.3.1 Watchdog Timers
14.4 Windows 98/Me Compatibility Notes
14.4.1 Error Logging
14.4.2 Waiting for System Threads to Finish
14.4.3 Work Items
15 Distributing Device Drivers
15.1 The Role of the Registry
15.1.1 The Hardware (Instance) Key
15.1.2 The Class Key
15.1.3 The Driver Key
15.1.4 The Service (Software) Key
15.1.5 Accessing the Registry from a Program
15.1.6 Device Object Properties
15.2 The INF File
15.2.1 Install Sections
15.2.2 Populating the Registry
15.2.3 Security Settings
15.2.4 Strings and Localization
15.2.5 Device Identifiers
15.2.6 Driver Ranking
15.2.7 Tools for INF Files
15.3 Defining a Device Class
15.3.1 A Property Page Provider
15.4 Customizing Setup
15.4.1 Installers and Co-installers
15.4.2 Preinstalling Driver Files
15.4.3 Value-Added Software
15.4.4 Installing a Driver Programmatically
15.4.5 The RunOnce Key
15.4.6 Launching an Application
15.5 The Windows Hardware Quality Lab
15.5.1 Running the Hardware Compatibility Tests
15.5.2 Submitting a Driver Package
15.6 Windows 98/Me Compatibility Notes
15.6.1 Property Page Providers
15.6.2 Installers and Co-installers
15.6.3 Preinstalled Driver Packages
15.6.4 Digital Signatures
15.6.5 Installing Drivers Programmatically
15.6.6 CONFIGMG API
15.6.7 INF Incompatibilities
15.6.8 Registry Usage
15.7 Getting Device Properties
16 Filter Drivers
16.1 The Role of a Filter Driver
16.1.1 Upper Filter Drivers
16.1.2 Lower Filter Drivers
16.2 Mechanics of a Filter Driver
16.2.1 The DriverEntry Routine
16.2.2 The AddDevice Routine
16.2.3 The DispatchAny Function
16.2.4 The DispatchPower Routine
16.2.5 The DispatchPnp Routine
16.3 Installing a Filter Driver
16.3.1 Installing a Class Filter
16.3.2 Installing a Device Filter with the Function Driver
16.3.3 Installing a Device Filter for an Existing Device
16.4 Case Studies
16.4.1 Lower Filter for Traffic Monitoring
16.4.2 Named Filters
16.4.3 Bus Filters
16.4.4 Keyboard and Mouse Filters
16.4.5 Filtering Other HID Devices
16.5 Windows 98/Me Compatibility Notes
16.5.1 WDM Filters for VxD Drivers
16.5.2 INF Shortcut
16.5.3 Class Filter Drivers
Coping with Cross-Platform Incompatibilities
Determining the Operating System Version
Run-Time Dynamic Linking
Checking Platform Compatibility
Defining Win98/Me Stubs for Kernel-Mode Routines
Version Compatibility
Stub Functions
Using WDMSTUB
Interaction Between WDMSTUB and WDMCHECK
Special Licensing Note
Using WDMWIZ.AWX
Basic Driver Information
DeviceIoControl Codes
I/O Resources
USB Endpoints
WMI Support
Parameters for the INF File
Now What?