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