Writing Windows WDM Device Drivers
Covers NT 4, Win 98, and Win 2000
Chris Cant
R&D Books Lawrence, Kansas 66046
Preface xvii Who Are You? xvii Terminology xviii Coding Style xviii Revised Source Files xix Thanks xix
Chapter 1 Introduction 1 The Windows Driver Model 2
WDM vs. NT Style Drivers 2 Ready-to-Use Drivers 3 Book CD-ROM 4 Device Driver Software Tools 4 Driver Types Not Covered 5
A New Frame of Mind 5 Device Driver Environment 5 Terminology and Resources 6
Win32 Program Interface 7 Basic I/O 7 Overlapped Asynchronous Requests 8 Environment 8 Device Specific Restrictions 9 Other Win32 Access to Drivers 9
Conclusion 9
i v Table of Contents
Chapter 2 The Big Picture 11 Device Driver Components 12
Driver Entry Points and Callbacks 13 Dispatch Routines 14 Creating Devices 15 Hardware Resource Assignments 16 Calling Other Drivers 16 Serializing Access to Hardware 16 Talking to Hardware 17 Hardware Problems 17 Power Management 17 Windows Management Instrumentation 18 NT Event Reporting • 18 System Threads 18
Types of Device Driver 18 Windows Overview 18 I/O Request Processing 19 Plug and Play Device Stacks . . . 20 Standard Bus and Class Drivers 21 Example Driver Stack 23
Driver Choices 24 Off-the-Shelf Drivers 24 Use Standard Drivers 24 Operating System 25 Layered Device Drivers 25 Monolithic Drivers 25 Recommended and Optional Features . 2 5
WDM Rationale 25 One Core Model 26 Complexity 26 Plug and Play and Layers 26 Range of Functionality 27 Development Environment 27 Developer Support 27
Conclusion 27
Chapter 3 Device Driver Design 29 Introduction 29 Driver Design Guide 29
Documentation 30 Good Design 30
Kernel Calls 31
Table of Contents V
Kernel Objects 33 Driver Routine Names 33
Processor Model 34 Processor Modes 34 Interrupt Levels 34
Using Memory 36 Pool Memory 36 Lookaside Lists 37 Other Memory Considerations 38 Accessing User Application Memory 38 DMA 38
IRP Processing 38 IRP Parameters 40 Processing IRPs in a Driver Stack 40
Conclusion 42
Chapter 4 WDM Driver Environment 43 System Set Up 43
DDKs 44 Book Software Installation 44 Shortcuts 45
Utilities 46 DOS Boxes 46 Computer Management Console 47 NT Devices Applet 47 Hardware Wizard 47 Registry Editors 47 INF Editor 47 WBEM 47 Debuggers 48 NT and Windows 2000 Utilities 48 Book Software Tools . 48
Driver Targets 49 Driver Language and Libraries 49
Resources 50 Good Code 50 build Utility 50
makefiles 51 SOURCES 51 makef i 1 e File 52 build Directories 52 Other build Steps 53
v i Table of Contents
DIRS File 54 VC++ Projects 54
Makefile Build Environment 54 MakeDrvr 55 Directories 56 Common Tasks 56
The Wdml Driver Code 56 Compiler Options 57 Header Files 58 Driver Entry Module 58 Version Resource 59 Accessing the Registry 59
Installing Wdml 63 Installation Details 64
INF Files 64 Registry 64 Windows 2000 Objects 65
Managing Devices and Drivers 65 Add Another Device 65 Removing a Device 65 Updating the Driver 65 NT Style Drivers 66
Conclusion 66
Chapter 5 Device Interfaces 93 Devices 93
Device Access 93 Subsequent I/O 95
Device Objects and Device Extensions 95 Creating and Deleting Device Objects 95
Creating Devices 97 Deleting Devices 98
Device Names 98 Symbolic Links 99
Device Interfaces 100 Wdml Device Interface 101
Win32 Device Interface Access 103 Getting a Device's Interface Name 103 Running Wdml Test 106
Conclusion 108
Table of Contents VÜ
Chapter 6 Testing and Debugging 115 Test, Test, Test 115 Driver Tests 116
Test That All Functions Work 116 W2000 and W98 117 Multiprocessor 117 Cancelling I/O 117
Debugging 118 How Do Things Go Wrong? 118
Debugging Techniques 120 Incremental Development 120 Checked Version 120 W2000 or W98 120
Debugging Tools 121 Windows 2000 Events 121 Tracing Tools 121 Driver Verifier 121 Debuggers 122
DebugPrint 122 Trying out DebugPrint 122 Using the DebugPrint Monitor 123 Using DebugPrint in Drivers 123
Debugging Notes 126 Updating Drivers 126 Driver Fails on Boot 126 Driver Dependencies 126 Uncanceled IRPs 127
Bugcheck Codes 127 Where Did the Bugcheck Happen? 129
Conclusion 130
Chapter 7 Dispatch Routines 131 Dispatch Routine IRPs 131 I/O Request Packets 132
Dispatch Routine Handling 132 Reentrancy 132 IRP Handling 133 IRP Completion 134
IRP Structure 134 I/O Stack Locations 136
Common IRP Parameters 137 Create IRP, IRP_MJ_CREATE 137
VÜi Table of Contents
Close IRP, IRP_MJ_CLOSE 138 Read IRP, IRP_MJ_READ 138 Write IRP, IRP_MJ_WRITE 138 IOCTL IRP, IRP_MJ_DEVICE_CONTROL 138
User Buffers 138 Buffered I/O 139 Direct I/O 139 Neither 139 Devi celoControl Buffers 139
Wdml Dispatch Routines 140 Create and Close 141 Write 141 Read 144 IOCTL 144 System Control 145
Conclusion 145
Chapter 8 Plug and Play and Device Stacks 147 Design Overview 147
Design Goals 148 Plug and Play System 148
Plug and Play Messages 153 Device Enumeration 155
Fixed and Configurable Devices 155 Enumeration 156 Device Tree 157
Device Stacks 158 PnP Support and the Device Stack 158 Device Objects 158
Upper Edges 160 USB Keyboard Example 160 Functional and Physical Device Objects 161 Upper Edge Definitions 162
Conclusion 163
Chapter 9 Plug and Play Implementation 165 Implementing Plug and Play 165
Adding and Removing Devices 166 Basic PnP Handlers 167 Passing Unsupported IRPs Down the Stack 171 PnP States and Messages 172
Ta b I e of Co nte nts IX
State Flags 173 Holding IRPs 174 Open Handles 175 When to Process PnP IRPs 176 Device Locking 180 Getting Resource Assignments 184
Testing Wdm2 190 Actual Plug and Play Messages 190
Other PnP IRPs 191 IRP_MN_DEVICE_USAGE_NOTIFICATION 191 IRP_MN_FILTER_RESOURCE_REQUIREMENTS 192
IRP_MN_QUERY_BUS_INFORMATION 192 IRP_MN_QUERY_CAPABILITIES 192 IRP_MN_QUERY_DEVICE_RELATIONS 192 IRP_MN_QUERY_DEVICE_TEXT 192 IRP_MN_QUERY_ID 193 IRP_MN_QUERY_INTERFACE 193 IRP_MN_QUERY_PNP_DEVICE_STATE 193 IRP_MN_QUERY_RESOURCE_REQUIREMENTS 193
IRP_MN_QUERY_RESOURCES 194 IRP_MN_READ_CONFIG 194 IRP_MN_SET_LOCK 194 IRP_MN_WRITE_CONFIG 194
Plug and Play Notification 194 Win32 PnP Notification 194 Device Driver PnP Notification 199 Notification Request Driver Interactions 199
Advanced Plug and Play 200 Bus Drivers 200 Sending PnP IRPs 201 Device Properties 202
Conclusion 202
Chapter 10 Power Management 203 The Power Picture 203
ACPI 204 Win32 Power Management 204 Wdm2Power Application 204 Battery Miniclass Drivers 206
System Power Policies 206 System and Device States 206
Power IRPs 207 Processing Power IRPs 208
X Table of Contents
Not Processing Power IRPs 210 Device Power Policy Owner 211 Handling Set Power IRPs 213
Setting System Power States 216 Setting Device Power States 219 SetPowerState 219
Dispatch Routine Power Handling 220 Testing Wdm2 Power Capabilities 221 Device Capabilities 221 Advanced Power Management 223
Wake 223 Power Sequence 224 Stopping System Power Down Events 224 Power Notification 224 Detecting System Power State Changes 224 WMI Support 224
Conclusion 226
Chapter 11 Installation 227 WDM Driver Installation Process 227 INF Files 228 Standard Sections 228
Strings 230 INF File Section Hierarchy 231
WdmlFree. INF 232 Inßdit 236
Cross-Platform and WDM INF Files 237 Installing Wdml in Windows 2000 237
Locating Drivers 239 Hardware IDs 240 Compatible IDs 241 Repeated Enumeration 241
NT Style Driver Installation 242 Install Process 242 Driver Load Order 243 NT 4 Control Panel Devices Applet 244 Windows 2000 Device Management 244 Windows 98 Device Management 246 REG Files 246
Installing NT Style Drivers in Windows 98 246 Conclusion 247
Table of Contents x i
Chapter 12 Windows Management Instrumentat ion. . 257 Overview 258
WBEM Model 258 The WDM Provider 259
A WMI Driver 261 WMI Build Environment 263 Registering as a WMI Data Provider 264 Handling System Control IRPs 266 QueryWmi Reginfo Handler 268 QueryWmi DataBl ock Handler 269 SetWmi DataBl ock Handler 271 SetWmi Dataltem Handler 272 ExecuteWmi Method Handler 273 Firing WMI Events. 274
WMI in Action 275 Conclusion 277
Chapter 13 Event Reporting 279 Overview 279 Message Files 280 Registering as an Event Source 283 Generating Events 284 Testing Wdm3 Events 288 Conclusion 288
Chapter 14 DebugPrint 289 Design Specification 289 Design Implementation 290 Test Driver Code 290
System Threads 291 Events 294 Synchronization 294 Generating Trace Events 296 Linked Lists 298 Final Pieces 300
DebugPrint Driver 302 Design 302 DebugPrint Devices 302 Read Queue 303 Cancelling IRPs 305 Write Algorithm 307 Read Algorithm 309
XÜ Table of Contents
DebugPrint Monitor 310 Design 310 Win32 Worker Threads 310 DebugPrint_Event Class 311 Win32 Overlapped I/O 312
Conclusion 315
Chapter 15 Wdmio and PHDIO Drivers 317 Win32 Interface 318
IOCTLs 318 Commands 319
LPT Printer Driver Application 320 Parallel Ports 320 WdmloTest 321 PHDIoTest 322 Issuing Commands 322 Writing Data Using Interrupt Driven I/O 324 Reading Data Using Interrupt Driven I/O 328
Testing Wdmio , 328 Installing Wdmio 328 LogConf i g Sections 329 Running WdmloTest 330
Testing PHDIo 331 Installing PHDIo 331 Running PHDIoTest 331
Analyzing Wdmio and PHDIo 332 Which to Use 332 Deficiencies 332
Conclusion 333
Chapter 16 Hardware I/O IRP Queuing 335 Hardware Access 336 IRP Queuing 337
Device Queues 337 S ta r t lo Routines 338
Processing Commands 342 Critical Sections 342
Cancelling Queued IRPs 343 Queued IRP Cancelling 344 Wdmio IRP Cancelling Strategy 344 Alternative Cancel Strategy 346
Cleanup IRP Handling 347
Table of Contents xü i
Testing, Cancelling, and Cleanup 349 Supplemental Device Queues 350
Implementing a Supplemental Device Queue 351 Conclusion 355
Chapter 17 Interrupt-Driven I/O 357 Interrupt Handling 357
The Nature of the Beast 357 Connecting to Interrupts 359
Wdmlo Reads and Writes 360 Starting Requests 362
Interrupt Handler 364 Deferred Procedure Calls 365
Using Basic DPCs 366 Custom DPCs 368
Timers 368 One-Second Interval Timers 369 Wdmlo Time-Outs 369 Custom Timers 370
Conclusion 371
Chapter 18 NT Hardware 373 NT Style Driver Construction 374
DDK Issues 374 Compile Environment 374 NT Style Driver Structure 374
Device Creation and Deletion 375 Claiming Resources 377 Translating Resources 384 Finding Resources 385
Auto-Detected Hardware 386 Interrogating Configurable Buses 389 Final Resource Discovery Techniques 390
Conclusion 390
Chapter 19 WDM System Drivers 391 Writing Client Drivers 392
Common Devices 392 Filter Drivers 393 NT Layering 393
Parallel Port Drivers 394 Conclusion 395
XIV Table of Contents
Chapter 20 The Universal Serial Bus 397 Device Classes 398
Human Input Devices (HID) 398 The Big Picture 398
Windows USB Driver Interface 399 Transfer Types 400
USB Low Level Structure 400 USB Devices 400 USB Signals 401 Bus Signalling 401 Low Level Protocol 402 Transactions 402 Power 403
USB Device Framework 403 Bus Enumeration 404 Standard Control Transactions 405 Descriptors 406 Driver Installation 407 USB Classes 407 New Features 409
Client Design 410 Endpoint Type Selection 410 Isochronous Devices 410
Conclusion 412
Chapter 21 USB Driver Interface 413 USB Client Driver Design 414
Using UsbKbd 415 UsbKbd Installation 416 Headers and Libraries 417
USBDI IOCTLs 417 URBs 418 Calling USBDI 419
Talking USB 422 Initializing a USB Device 422 Issuing URBs 424 Selecting an Interface 426 Other Initialization 428 Deselecting a Configuration 429 Interrupt Transfers 429 Control Transfers 432 Other Issues 434
Table of Contents XV
Testing UsbKbd 434 USBDI Structure Reference 438
Structures 438 USBDI URB Reference 441
URB Setup Functions 441 URB Transfer Functions 444 URB Default Pipe Functions 445 URB Isochronous Frame Functions 446
Conclusion 447
Chapter 22 The Human Input Device Model 449 HID Hides 449
HID in Windows 450 The HID Model 451
Reports 451 Usages 452 Getting HID Capabilities 454
HID Model Representation 454 HID Descriptors 455 Device Attributes 455 Report Descriptors 455
Conclusion 462
Chapter 23 HID Clients 463 HID Class Driver 463
HID Class Driver Characteristics 464 Windows HID Clients 464 Header Files 466 HID USB Minidriver 466 USB Boot Devices 467
User Mode HID Clients 467 Finding HID Devices 468 Getting HID Capabilities 468 Reading Input Reports 472 Sending Output Reports 476 Other User Mode HID Client Functions 478 Running HidKbdUser 478
Kernel Mode HID Clients 481 Client Types 481 Plug and Play Notifications 482 HidKbd Devices 484 Getting HID capabilities 489
x v i Table of Contents
Opening and Closing the Hi dKbd Device 490 Reading and Writing Data 491 Other HID Class IOCTLs 497
Conclusion 497
Appendix A Information Resources 499 Newsgroups and Mail Lists 501 Books 502
Appendix B PC 99 503 Drivers 503 The Specification 504 IBM-Compatible PCs 504 Changing World 507 ACPI, OnNow, and Plug and Play 508 PC 99 Conformance 508
Appendix C Direct Memory Access 509
Glossary Acronyms and Tools 511
Index 517
What's on the CD-ROM? 548