Programming the Microsoft Windows Driver Model (2nd Edition) (Developer Reference)

Written for advanced C/C++ programmers, Walter Oney's Programming the Microsoft Windows Driver Model is a technically astute and clearly presented guide to writing custom Windows 2000 device drivers.The author's command of the details of the new Windows Driver Model (WDM) standard is what makes this book such a clear success. (Because the WDM is rich in kernel and system services, the trick is often knowing how to use what's available rather than doing everything yourself.) The author presents a solid overview of the WDM architecture and breaks down the process of writing custom device drivers into manageable pieces, from the basics of loading device drivers to creating and processing I/O request packets. The book is very good at exposing kernel system calls, design principles, and programming techniques (such as managing synchronization and handling errors). There are also "nerd alerts" that point out extremely technical material.This book shows you what you'll need to create WDM drivers that cooperate fully with Windows 2000 (and Windows 98). Features like Plug and Play (PnP), Windows power management, and the new Windows Management Instrumentation (WDM) standard get full attention here. There is plenty of sample code (plus a custom Visual C++ AppWizard that generates skeleton code for a default WDM driver) to get you started. Examples for working with the S5933 PCI chip set (and other simple hardware) let you see WDM drivers in action.The process of writing device drivers certainly has changed from the early days of DOS. But armed with this handy and thorough book, C/C++ programmers can successfully create drivers for custom hardware that take full advantage of all the features of the powerful new WDM standard. 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? The Microsoft Windows driver model (WDM) supports Plug and Play, provides power management capabilities, and expands on the driver/minidriver approach. Written by long-time device-driver expert Walter Oney in cooperation with the Windows kernel team, this book provides extensive practical examples, illustrations, advice, and line-by-line analysis of code samples to clarify real-world driver-programming issues. And its been updated with the latest details about the driver technologies in Windows XP and Windows 2000, plus more information about how to debug drivers. Topics covered include: Beginning a driver project and the structure of a WDM driver; NEW: Minidrivers and class drivers, driver taxonomy, the WDM development environment and tools, management checklist, driver selection and loading, approved API calls, and driver stacks Basic programming techniques; NEW: Safe string functions, memory limits, the Driver Verifier scheme and tags, the kernel handle flag, and the Windows 98 floating-point problem Synchronization; NEW: Details about the interrupt request level (IRQL) scheme, along with Windows 98 and Windows Me compatibility The I/O request packet (IRP) and I/O control operations; NEW: How to send control operations to other drivers, custom queue implementations, and how to handle and safely cancel IRPs Plug and Play for function drivers; NEW: Controller and multifunction devices, monitoring device removal in user mode, Human Interface Devices (HID), including joysticks and other game controllers, minidrivers for non-HID devices, and feature reports Reading and writing data, power management, and Windows Management Instrumentation (WMI) NEW: System wakeup, the WMI control for idle detection, and using WMIMOFCK Specialized topics and distributing drivers; NEW: USB 2.0, selective suspend, Windows Hardware Quality Lab (WHQL) certification, driver selection and loading, officially approved API calls, and driver stacks COVERS WINDOWS 98, WINDOWS ME, WINDOWS 2000, AND WINDOWS XP! CD-ROM FEATURES: A fully searchable electronic copy of the book Sample code in Microsoft Visual C++ A Note Regarding the CD or DVD The print version of this book ships with a CD or DVD. For those customers purchasing one of the digital formats in which this book is available, we are pleased to offer the CD/DVD content as a free download via O'Reilly Media's Digital Distribution services. To download this content, please visit O'Reilly's web site, search for the title of this book to find its catalog page, and click on the link below the cover image (Examples, Companion Content, or Practice Files). Note that while we provide as much of the media content as we are able via free download, we are sometimes limited by licensing restrictions. Please direct any questions or concerns to booktech@oreilly.com. The Microsoft Windows driver model (WDM) supports Plug and Play, provides power management capabilities, and expands on the driver/minidriver approach. Written by long-time device-driver expert Walter Oney in cooperation with the Windows kernel team, this book provides extensive practical examples, illustrations, advice, and line-by-line analysis of code samples to clarify real-world driver-programming issues. It's also been updated with the latest details about the driver technologies in Windows XP and Windows 2000, plus more information about how to debug drivers.