|
|
| Using This Documentation | xliii |
| Documentation Roadmap | xliii |
| Using This Documentation Online | xlviii |
| Documentation Conventions | xlix |
| SECTION 1 DRIVER WRITER’S GUIDE | |
| CHAPTER 1 Driver Development Environment | 3 |
| 1.1 Free Build and Checked Build | 3 |
| 1.2 Debugging Environment | 5 |
| CHAPTER 2 Testing Drivers | 7 |
| 2.1 Driver Verifier | 7 |
| 2.1.1 Capabilities of Driver Verifier | 8 |
| 2.1.2 Capabilities of Driver Verifier for Graphics Drivers | 15 |
| 2.1.3 Activating and Monitoring Driver Verifier | 19 |
| SECTION 2 PLUG AND PLAY, POWER MANAGEMENT, AND SETUP DESIGN GUIDE | |
| PART 1 REQUIREMENTS FOR PLUG AND PLAY AND POWER MANAGEMENT | |
| CHAPTER 1 Introduction to Plug and Play and Power Management | 33 |
| 1.1 What Is Plug and Play? | 34 |
| 1.1.1 PnP Components | 35 |
| 1.1.1 Levels of Support for PnP | 36 |
| 1.2 What Is Power Management? | 36 |
| 1.2.1 Industry Initiatives for Power Management | 38 |
| 1.2.2 Levels of Support for Power Management | 38 |
| 1.2.3 System-Wide Overview of Power Management | 38 |
| 1.2.4 Power States | 40 |
| 1.3 Device Tree | 40 |
| 1.4 Driver Layers and Device Objects | 42 |
| 1.4.1 Kinds of Drivers | 42 |
| 1.4.2 Driver Layers — An Example | 45 |
| 1.4.3 Kinds of Device Objects | 48 |
| 1.4.4 Device Objects — An Example | 50 |
| CHAPTER 2 Required Driver Support for PnP and Power Management | 55 |
| 2.1 Overview of Required PnP Support | 55 |
| 2.2 PnP and Power Management DriverEntry Routine | 56 |
| 2.3 PnP and Power Management AddDevice Routine | 58 |
| 2.3.1 Guidelines for Writing AddDevice Routines | 60 |
| 2.4 The DispatchPnP Routine | 61 |
| 2.5 The DispatchPower Routine | 62 |
| 2.6 PnP and Power Management Unload Routine | 63 |
| PART 2 PLUG AND PLAY | |
| CHAPTER 1 Understanding PnP | 67 |
| 1.1 PnP Driver Design Guidelines | 67 |
| 1.2 PnP and the Device Tree | 69 |
| 1.3 PnP Device States | 70 |
| 1.4 Dynamically Adding a New PnP Device | 72 |
| 1.5 Hardware Resources | 80 |
| 1.5.1 Logical Configurations | 82 |
| 1.6 Using GUIDs in Drivers | 83 |
| 1.6.1 Defining and Exporting New GUIDs | 84 |
| 1.6.2 Including GUIDs in Driver Code | 85 |
| CHAPTER 2 Rules for Handling Plug and Play IRPs | 87 |
| 2.1 PnP IRP Requirements | 87 |
| 2.2 Passing PnP IRPs Down the Device Stack | 89 |
| 2.3 Postponing PnP IRP Processing Until Lower Drivers Finish | 91 |
| CHAPTER 3 Starting, Stopping, and Removing Devices | 97 |
| 3.1 Starting a Device | 97 |
| 3.1.1 Starting a Device in a Function Driver | 98 |
| 3.1.2 Starting a Device in a Filter Driver | 100 |
| 3.1.3 Starting a Device in a Bus Driver | 100 |
| 3.1.4 Start Device Design Considerations | 101 |
| 3.2 Stopping a Device for Resource Rebalancing | 101 |
| 3.2.1 Understanding When Stop IRPs Are Issued | 101 |
| 3.2.2 Handling an IRP_MN_QUERY_STOP_DEVICE Request | 103 |
| 3.2.3 Handling an IRP_MN_STOP_DEVICE Request | 106 |
| 3.2.4 Handling an IRP_MN_CANCEL_STOP_DEVICE Request | 107 |
| 3.2.5 Holding Incoming IRPs When a Device Is Paused | 108 |
| 3.3 Removing a Device | 109 |
| 3.3.1 Understanding When Remove IRPs Are Issued | 109 |
| 3.3.2 Handling an IRP_MN_QUERY_REMOVE_DEVICE Request | 112 |
| 3.3.3 Handling an IRP_MN_REMOVE_DEVICE Request | 115 |
| 3.3.4 Handling an IRP_MN_CANCEL_REMOVE_DEVICE Request | 119 |
| 3.3.5 Handling an IRP_MN_SURPRISE_REMOVAL Request | 120 |
| CHAPTER 4 Using PnP Notification | 125 |
| 4.1 PnP Notification Overview | 126 |
| 4.2 Guidelines for Writing PnP Notification Callback Routines | 128 |
| 4.3 Using PnP Device Interface Change Notification | 128 |
| 4.3.1 Registering for Device Interface Change Notification | 129 |
| 4.3.2 Handling Device Interface Change Events | 130 |
| 4.4 Using PnP Target Device Change Notification | 130 |
| 4.4.1 Registering for Target Device Change Notification | 131 |
| 4.4.2 Handling a GUID_TARGET_DEVICE_QUERY_REMOVE Event | 131 |
| 4.4.3 Handling a GUID_TARGET_DEVICE_REMOVE_COMPLETE Event | 132 |
| 4.4.4 Handling a GUID_TARGET_DEVICE_REMOVE_CANCELLED Event | 133 |
| 4.5 Using PnP Hardware Profile Change Notification | 133 |
| 4.5.1 Registering for Hardware Profile Change Notification | 133 |
| 4.5.2 Handling Hardware Profile Change Events | 134 |
| 4.6 Using PnP Custom Notification | 135 |
| CHAPTER 5 Supporting Multifunction Devices | 137 |
| 5.1 Supporting Multifunction PC Card Devices | 138 |
| 5.1.1 Supporting PC Cards That Conform to the Multifunction Standard | 138 |
| 5.1.2 Supporting PC Cards That Have Incomplete Configuration Register Addresses | 139 |
| 5.1.3 Supporting PC Cards That Have Incomplete Configuration Registers | 142 |
| 5.2 Supporting Multifunction PCI Devices | 146 |
| 5.3 Supporting Multifunction Devices On Other Buses | 147 |
| 5.4 Using the System-Supplied mf.sys | 147 |
| 5.5 Creating Resource Maps for a Multifunction Device | 150 |
| PART 3 POWER MANAGEMENT | |
| CHAPTER 1 Supporting Power Management in Drivers | 155 |
| 1.1 Kernel-Mode Power Management Components | 156 |
| 1.1.1 ACPI BIOS | 156 |
| 1.1.2 ACPI Driver | 156 |
| 1.1.3 Power Manager | 157 |
| 1.1.4 Driver Role in Power Management | 157 |
| 1.2 Power Management Responsibilities for Drivers | 158 |
| 1.2.1 Reporting Device Power Capabilities | 158 |
| 1.2.2 Setting Device Object Flags for Power Management | 162 |
| 1.2.3 Handling Power IRPs | 163 |
| 1.2.4 Powering Up a Device | 167 |
| 1.2.5 Powering Down a Device | 168 |
| 1.2.6 Enabling Device Wake-up | 168 |
| 1.3 Rules for Handling Power IRPs | 169 |
| 1.3.1 Using PoCallDriver | 169 |
| 1.3.2 Passing Power IRPs | 170 |
| 1.3.3 Queuing I/O Requests While a Device Is Sleeping | 172 |
| 1.3.4 Handling Unsupported or Unrecognized Power IRPs | 172 |
| CHAPTER 2 Managing Power for Individual Devices | 173 |
| 2.1 Device Power States | 174 |
| 2.1.1 Device Working State D0 | 175 |
| 2.1.2 Device Sleeping States D1, D2, and D3 | 175 |
| 2.1.3 Required Support for Device Power States | 177 |
| 2.2 Managing Device Power Policy | 178 |
| 2.3 Handling IRP_MN_SET_POWER for Device Power States | 180 |
| 2.3.1 Handling Device Power-down IRPs | 181 |
| 2.3.2 Handling Device Power-up IRPs | 184 |
| 2.3.3 IoCompletion Routines for Device Power IRPs | 186 |
| 2.4 Handling IRP_MN_QUERY_POWER for Device Power States | 187 |
| 2.5 Sending IRP_MN_QUERY_POWER or IRP_MN_SET_ POWER for Device Power States | 189 |
| 2.6 Detecting an Idle Device | 191 |
| 2.6.1 Using Power Manager Routines for Idle Detection | 191 |
| 2.6.2 Performing Device-Specific Idle Detection | 192 |
| CHAPTER 3 Handling System Power State Requests | 193 |
| 3.1 System Power States | 194 |
| 3.1.1 System Working State S0 | 194 |
| 3.1.2 System Sleeping States S1, S2, S3, S4 | 195 |
| 3.1.3 System Shutdown State S5 | 197 |
| 3.1.4 System Power Actions | 198 |
| 3.2 System Power Policy | 199 |
| 3.3 Preventing System Power State Changes | 199 |
| 3.4 Handling IRP_MN_QUERY_POWER for System Power States | 200 |
| 3.4.1 Failing a System Query-Power IRP | 201 |
| 3.4.2 Handling a System Query-Power IRP in a Device Power Policy Owner | 202 |
| 3.4.3 Handling a System Query-Power IRP in a Bus Driver | 203 |
| 3.4.4 Handling a System Query-Power IRP in a Filter Driver | 203 |
| 3.5 Handling IRP_MN_SET_POWER for System Power States | 204 |
| 3.5.1 Handling a System Set-Power IRP in a Device Power Policy Owner | 205 |
| 3.5.2 Handling a System Set-Power IRP in a Bus Driver | 207 |
| 3.5.3 Handling a System Set-Power IRP in a Filter Driver | 208 |
| CHAPTER 4 Supporting Devices that Have Wake-up Capabilities | 209 |
| 4.1 Overview of Wait/Wake Operation | 210 |
| 4.1.1 Determining Whether a Device Can Wake the System | 211 |
| 4.1.2 Understanding the Path of Wait/Wake IRPs through a Device Tree | 212 |
| 4.1.3 Overview of Wait/Wake IRP Completion | 217 |
| 4.2 Steps in Handling a Wait/Wake IRP | 218 |
| 4.2.1 Handling a Wait/Wake IRP in a Function (FDO) or Filter Driver (Filter DO) | 219 |
| 4.2.2 Handling a Wait/Wake IRP in a Bus Driver (PDO) | 220 |
| 4.2.3 IoCompletion Routines for Wait/Wake IRPs | 221 |
| 4.3 Sending a Wait/Wake IRP | 222 |
| 4.3.1 Determining When to Send a Wait/Wake IRP | 222 |
| 4.3.2 Wait/Wake IRP Requests | 223 |
| 4.3.3 Wait/Wake Callback Routines | 223 |
| 4.3.4 Canceling a Wait/Wake IRP | 224 |
| 4.4 Cancel Routines for Wait/Wake IRPs | 225 |
| PART 4 SETUP | |
| CHAPTER 1 DEVDevice Installation Overview | 229 |
| 1.1 Device Installation Components | 229 |
| 1.2 Sample PnP Device Installation | 232 |
| 1.3 How Does Setup Select a Driver For a Device? | 235 |
| 1.4 System Setup Phases | 239 |
| CHAPTER 2 Providing a Driver For a Device | 241 |
| 2.1 Driver Files | 241 |
| 2.2 Driver Information in the Registry | 242 |
| 2.3 Specifying Driver Load Order | 244 |
| 2.4 Installing Filter Drivers | 247 |
| 2.5 Installing a Null Driver for a Device | 249 |
| CHAPTER 3 Creating an INF File | 251 |
| 3.1 General Guidelines for INF Files | 251 |
| 3.2 Specifying the Source and Target Locations for Device Files | 252 |
| 3.3 Creating a Cross-Platform and/or Dual-OS INF File | 254 |
| 3.4 Creating International INF Files | 256 |
| 3.5 Tightening File-Open Security in a Device INF File | 256 |
| 3.6 Accessing INF Files From an Application | 258 |
| 3.6.1 Opening and Closing an INF File | 258 |
| 3.6.2 Retrieving Information From an INF File | 258 |
| CHAPTER 4 Writing a Coinstaller | 259 |
| 4.1 Coinstaller Overview | 259 |
| 4.2 Coinstaller Interface | 262 |
| 4.3 Coinstaller Operation | 264 |
| 4.3.1 Handling DIF Codes | 264 |
| 4.4 Registering a Coinstaller | 266 |
| 4.4.1 Registering a Device-Specific Coinstaller | 268 |
| 4.4.2 Registering a Class Coinstaller | 269 |
| CHAPTER 5 Writing a Class Installer | 271 |
| 5.1 Class Installer Interface | 271 |
| 5.2 Device Installation Functions Summary | 273 |
| 5.3 Registering a Class Installer | 273 |
| 5.4 Tightening File-Open Security in a Class Installer INF File | 274 |
| CHAPTER 6 Writing a Custom Device Installation Application | 277 |
| 6.1 Installing a Software Utility That Accompanies a Driver | 277 |
| 6.2 Custom Installation Application Guidelines | 278 |
| CHAPTER 7 Providing Device Property Pages | 281 |
| 7.1 Required Support for Device Property Pages | 281 |
| 7.2 Handling DIF_ADDPROPERTYPAGE_ADVANCED Requests | 282 |
| 7.3 Property Page Callback Function | 284 |
| 7.4 Handling Windows Messages for Property Pages | 285 |
| CHAPTER 8 Troubleshooting Device Installation | 287 |
| 8.1 Using SetupAPI Logging | 289 |
| 8.1.1 Setting SetupAPI Logging Levels | 289 |
| 8.1.2 Interpreting a Sample SetupAPI Log File | 291 |
| 8.2 Displaying Hidden Devices in Device Manager | 294 |
| CHAPTER 9 Installing a Device Required to Boot the Machine | 295 |
