The Windows 2000 Device Driver Book

ART BAKER, founder of Cydonix Corporation, has spent 30 years writing device-control software. For 15 years, he has trained professional developers to write device drivers. JERRY LOZANO is an Electrical Engineer and has been writing low-level device and OS code since 1976. For several years, he has been training and consulting on Microsoft system tools and development.

1. Introduction to Windows 2000 Drivers.


Overall System Architecture. Design Goals for Windows 2000. Hardware Privilege Levels in Windows 2000. Portability. Extendability. Performance. Executive Components. System Service Interface. Object Manager. Configuration Manager. Process Manager. Virtual Memory Manager. Local Procedure Call Facility. I/O Manager. Active Directory Service. Extensions to the Base Operating System. The Win32 Subsystem. Integral Subsystems. Kernel-Mode I/O Components. Design Goals for the I/O Subsystem. Kinds of Drivers in Windows 2000. Special Driver Architectures. Video Drivers. Printer Drivers. Multimedia Drivers. Network Drivers. Summary.



2. The Hardware Environment.


Hardware Basics. Device Registers. Command. Status. Data. Accessing Device Registers. I/O Space Registers. Memory-Mapped Registers. Device Interrupts. Interrupt Priority. Interrupt Vectors. Signaling Mechanisms. Processor Affinity. Data Transfer Mechanisms. Programmed I/O. Direct Memory Access. DMA Mechanisms. System DMA. Bus Master DMA. Device-Dedicated Memory. Auto-regulation and Auto-configuration. Device Resource Lists. No Jumpers or Switches. Change Notification. Buses and Windows 2000. ISA: The Industry Standard Architecture. Register Access. Interrupt Mechanisms. DMA Capabilities. Automatic Recognition and Configuration. EISA: The Extended Industry Standard Architecture. Register Access. Interrupt Mechanisms. DMA Capabilities. Device Memory. Automatic Recognition and Configuration. PCI: The Peripheral Component Interconnec. Register Access. Interrupt Mechanisms. DMA Capabilities. Device Memory. Autoconfiguration. USB: The Universal Serial Bus. Register Access. Interrupt Mechanisms. DMA Capabilities. Automatic Recognition and Configuration. IEEE 1394: The FirewireTM Bus. Register Access. Interrupt Mechanisms. DMA Capabilities. Automatic Recognition and Configuration. The PC Card (PCMCIA) Bus. Register Access. Interrupt Mechanisms. DMA Capabilities. Automatic Recognition and Configuration. Hints for Working with Hardware. Learn about the Hardware. Bus Architecture. Control Registers. Error and Status Reporting. Interrupt Behavior. Data Transfer Mechanisms. Device Memory. Make Use of Hardware Intelligence. Test the Hardware. Basic Tests. Standalong Tests. Summary.



3. Kernel-Mode I/O Processing.


How Kernel-Mode Code Executes. Trap or Exception Context. Interrupt Context. Kernel-Mode Thread Context. Use of Interrupt Priorities by Windows 2000. CPU Priority Levels. Interrupt Processing Sequence. Software-Generated Interrupts. Deferred Procedure Calls (DPCs). Operation of a DPC. Behavior of DPCs. Accessing to User Buffers. Buffer Access Mechanisms. Structure of a Kernel-Mode Driver. Driver Initialization and Cleanup Routines. DriverEntry Routine. Reinitialization Routine. Unload Routine. Shutdown Routine. Bugcheck Callback Routine. I/O System Service Dispatch Routines. Open and Close Operations. Device Operations. Data Transfer Routines. Start I/O Routing. Interrupt Service Routine (ISR). DPC Routines. Resource Synchronization Callbacks. ControllerControl Routine. AdapterControl Routine. SynchCritSection. Other Driver Routines. I/O Processing Sequence. Preprocessing by the I/O Manager. Preprocessing by the Device Driver. Device Start and Interrupt Service. Start I/O. ISR. Postprocessing by the Driver. Postprocessing by the I/O Manager. Summary.



4. Drivers and Kernel-Mode Objects.


Data Objects and Windows 2000. Windows 2000 and OOP. Windows 2000 Objects and Win32 Objects. I/O Request Packets (IRPs). Layout of an IRP. IRP Header. I/O Stack Locations. Manipulating IRPs. IRPs as a Whole. IRP Stack Locations. Driver Objects. Layout of a Driver Object. Device Objects and Device Extensions. Layout of the Device Object. Manipulating Device Objects. Device Extensions. Controller Objects and Controller Extensions. Layout of the Controller Object. Manipulating Controller Objects. Controller Extensions. Adapter Objects. Layout of an Adapter Object. Manipulating Adapter Objects. Interrrupt Objects. Layout of an Interrupt Object. Manuipulating Interrupt Objects. Summary.



5. General Development Issues.


Driver Design Strategies. Use Formal Design Methods. Use Incremental Development. Examine and Use the Sample Drivers. Coding Conventions and Techniques. General Recommendations. Naming Conventions. Header Files. Status Return Values. Windows 2000 Driver Support Routines. Discarding Initialization Routines. Controlling Driver Paging. Driver Memory Allocation. Memory Available to Drivers. Working with the Kernel Stack. Working with the Pool Areas. System Support for Memory Suballocation. Zone Buffers. Lookaside Lists. Unicode Strings. Unicode String Data Types. Working with Unicode. Interrupt Synchronization. The Problem. Interrupt Blocking. Rules for Blocking Interrupts. Synchronization Using Deferred Procedure Calls. Synchronizing Multiple CPUs. How Spin Locks Work. Using Spin Locks. Rules for Using Spin Locks. Linked Lists. Singly Linked Lists. Doubly Linked Lists. Removing Blocks from a List. Summary.



6. Initialization and Cleanup Routines.


Writing a DriverEntry Routine. Execution Context. What a DriverEntry Routine Does. Announcing DriverEntry Points. Creating Device Objects. Choosing a Buffering Strategy. Device Names. Code Example: Driver Initialization. DriverEntry. CreatDevice. Writing Reinitialize Routines. Executive Context. What a Reinitialize Routine Does. Writing and Unload Routine. Execution Context. What an Unload Routine Does. Code Example: Driver Unload. Writing Shutdown Routines. Execution Context. What a Shutdown Routine Does. Enabling a Shutdown Notification. Testing the Driver. Testing Procedure. Visual C++ Device Driver AppWizard. The WIndows 2000 DDK. Results of the Driver Build. Installing a Kernel-Mode Driver Manually. Loading the Driver. Windows 2000 Computer Management Console. The WINOBJ Utility. Summary.



7. Driver Dispatch Routines.


Announcing Driver Dispatch Routines. I/O Request Dispatching Mechanism. Enabling Specific Function Codes. Deciding Which Function Codes to Support. Writing Driver Dispatch Routines. Execution Context. What Dispatch Routines Do. Exiting the Dispatch Routine. Signaling an Error. Completing a Request. Scheduling a Device Operation. Processing Read and Write Requests. User Buffer Access. Buffered I/O. Direct I/O. Neither Method. Code Example: A Loopback Device. Extending the Dispatch Interface. Defining Private IOCTL Values. IOCTL Argument-Passing Methods. Writing IOCTL Header Files. Processing IOCTL Requests. Managing IOCTL Buffers. METHOD_BUFFERED. MEHTOD_IN_DIRECT. METHOD_OUT_DIRECT. METHOD_NEITHER. Testing Driver Dispatch Routines. Testing Procedure. Sample Test Program. Summary.



8. Interrupt-Driven I/O.


How Programmed I/O Works. What Happens During Programmed I/O. Synchronizing Driver Routines. Driver Initialization and Cleanup. Initializing the Start I/O Entry Point. Initializing a DpcForIsr Routine. Connecting to an Interrupt Source. Disconnecting from an Interrupt Source. Writing a Start I/O Routine. Execution Context. What the Start I/O Routine Does. Writing an Interrupt Service Routine (ISR). Execution Context. What the Interrupt Service Routine Does. Writing a DpcForIsr Routine. Execution Context. What the DpcForIsr Routine Does. Priority Increments. Some Hardware: The Parallel Port. How the Parallel Port Works. Device Registers. Interrupt Behavior. A Loopback Connector for the Parallel Port. Code Example: Parallel Port Loopback Driver. Purpose of the Driver. Driver.H. Driver.cpp. CreateDevice. DispatchWrite. DispatchRead. StartIo. ISR. DpcForIsr. Testing the Parallel Port Loopback Driver. Testing Procedure. Summary.



9. Hardware Initialization.


The Plug and Play Architecture: A Brief History. Goals of Plug and Play. Components of Plug and Play. Plug and Play Manager. Power Manager. Registry. INF Files. Plug and Play Drivers. The Role of the Registry for Legacy Drivers. Detecting Devices with Plug and Play. The Role of Driver Layers in Plug and Play. The New WDM IRP Dispatch Functions. Required Plug and Play IRPs. PDO Plug and Play IRPs. Passing Down Plug and Play Requests. I/O Completion Routines. Bus Driver Plug and Play Requests. Device Enumeration. Hardware Resource Descriptions. Using Hardware Resources within the Driver. Driver Interfaces. Interface Definition. Interface Construction. Interface Reference Counting. Registering and Enabling an Interface. Code Example: A Simple Plug and Play Driver. Summary.



10. Power Management.


Hot Plug Devices. Bus Considerations. Device Considerations. OnNow Initiative. Power States. Power Policies. Power State Matrix. Power State Changes. Wake Requests. Canceling the Wake-Armed IRP. Power Management Issues. Idle Management. User Interface for Power Management. Summary.



11. Timers.


Handling Device Timeouts. How I/O Timer Routines Work. How to Catch Device Timeout Conditions. Code Example: Catching Device Timeouts. Device Extension Additions. AddDevice Additions. Create Dispatch Routine Changes. StartIo Changes. ISR Changes. I/O Timer Callback Routine. Managing Devices without Interrupts. Working with Polled Devices. How CustomTimerDpc Routines Work. How to Set Up a CustomTimerDpc Routine. How to Specify Expiration Times. Other Uses for CustomTimerDpc Routines. Code Example: A Timer-Based Driver. Device Extension Additions. AddDevice Modifications. TransmitBytes Changes. PollingTimerDpc Routine. Summary.



12. DMA Drivers.


How DMA Works under Windows. Hiding DMA Hardware Variations with Adapter Objects. The Scatter/Gather Problem. Memory Descriptor Lists. Maintaining Cache Coherency. CPU Data Cache. Adapter Object Cache. Packet-Based and Common Buffer DMA. Limitations of the Windows 2000 DMA Architecture. Working with Adapter Objects. Finding the Right Adapter Object. Acquiring and Releasing the Adapter Object. Setting Up the DMA Hardware. Flushing the Adapter Object Cache. Writing a Packet-Based Slave DMA Driver. How Packet-Based Slave DMA Works. IRP_MN_START_DEVICE Handler. Start I/O Routine. Adapter Control Routine. Interrupt Service Routine. DpcForIsr Routine. Splitting DMA Transfers. First Transfer. Additional Transfers. Code Example: A Packet-Based Slave DMA Driver. DRIVER.H. GetDmaInfo Routine. Start I/O Changes. AdapterControl Routine. DpcForIsr Routine. Writing a Packet-Based Bus Master DMA Driver. Setting Up Bus Master Hardware. AdapterControl Routine. DpcForIsr Routine. Hardware with Scatter/Gather Support. Building Scatter/Gather Lists with Map Transfer. AdapterControl Routine. DpcForIsr Routine. Writing a Common Buffer Slave DMA Driver. Allocating a Common Buffer. Using Common Buffer Slave DMA to Maintain Throughput. AddDevice Routine. IRP_MN_START_DEVICE Handler. Dispatch Routine. Start I/O Routine. Interrupt Service Routine. DpcForIsr Routine. IRP_MN_STOP_DEVICE Handler. Writing Common Buffer Bus Master DMA Driver. How Common-Buffer Bus Master DMA Works. IRP_MN_START_DEVICE Handler. Start I/O Routine. Interrupt Service Routine. IRP_MN_STOP_DEVICE Handler. Summary.



13. Windows Management and Instrumentation.


WMI: The Industry Picture. The WMI Architecture. Providing WMI Support in a WDM Driver. MOF Syntax. Example MOF Class Definition. Compiling the MOF Source. Handling WMI IRP Requests. Classes and Instances. WMILIB. DpWmiQueryReginfo. DpWmiQueryDataBlock. DpWmiSetDataBlock. DpWmiSetDataItem. DpWmiExecuteMethod. DpWmiFunctionControl. WMI Summary. Conventional Driver Event Logging. How Event Logging Works. Working with Messages. Writing a Message Definition Files. A Simple Example. Header Section. Message Section. Compiling a Message Definition File. Adding Message Resources to a Driver. Registering a Driver as an Event Source. Generating Log Entries. Allocating an Error-Log Packet. Logging the Error. Summary.



14. System Threads.


Definition and Use of System Threads. When to Use Threads. Creating and Terminating System Threads. Managing Thread Priority. System Worker Threads. Thread Synchronization. Time Synchronization. General Synchronization. KeWaitForSingleObject. KeWaitForMultipleObjects. Using Dispatcher Objects. Event Objects. Sharing Events Between Drivers. Mutex Objects. Semaphore Objects. Timer Objects. Thread Objects. Variations on the Mutex. Fast Mutexes. Executive Resources. Synchronization Deadlocks. Code Example: A Thread-Based Driver. How the Driver Works. The DEVICE_EXTENSION Structure. The AddDevice Function. The DispatchReadWrite Function. Thread.C. WorkerThreadMain. KillThread. Transfer.C. PerformDataTransfer. AcquireAdapterObject and AdapterControl. PerformSynchronousTransfer. DpcForIsr. Summary.



15. Layered Drivers.


An Overview of Intermediate Drivers. Intermediate Drivers Defined. When to Use a Layered Architecture. Pros of Layered Architecture. Cons of Layered Architecture. Writing Layered Drivers. How Layered Drivers Work. Initialization and Cleanup in Layered Drivers. DriverEntry. AddDevice. RemoveDevice. Code Fragment: COnnecting to Another Driver. Other Initialization Concerns for Layered Drivers. Transparent. Virtual or Logical Device Layer. I/O Request Processing in Layered Drivers. Complete the Original IRP. Pass the IRP to Another Driver. Allocate Additional IRPs. Code Fragment: Calling a Lower-Level Driver. Writing I/O Completion Routines. Requesting an I/O Completion Callback. Execution Context. What I/O Completion Routines Do. Release the Original IRP. Deallocate the IRP. Recycle the IRP. Code Fragment: An I/O Completion Routine. Allocating Additional IRPs. The IRP's I/O Srtack Revisited. Controlling the Size of the IRP Stack. Creating IRPs with IoBuildSynchronousFsdRequest. Creating IRPs with IoBuildAsynchronousFsdRequest. Creating IRPs with IoBuildDevice IoControlRequest. Creating IRPs from Scratch. IRPs from IoAllocateIrp. IRPs from ExAllocatePool. IRPs from Driver-Managed Memory. Setting Up Buffers for Lower Drivers. Buffered I/O Requests. Direct I/P Requests. Keeping Track of Driver-Allocated IRPs. Synchronous I/O. Asynchronous I/O. Writing Filter Drivers. How Filter Drivers Work. Initialization and Cleanup in Filter Drivers. AddDevice Routine. RemoveDevice Routine. Making the Attachment Transparent. Code Example: A Filter Driver. The DEVICE_EXTENSION Structure. The DriverEntry Fuction. The AddDevice Function. GetBufferLimits. The OverriddenDispatchWrite Function. The OverriddenDispatchDeviceIoControl Function. The DispatchPassThru Function. The I/O Completion Routines. WriteCompletion. GenericCompletion. Writing Tightly Coupled Drivers. How Tightly Coupled Drivers Work. Initialization and Cleanup in Tightly Coupled Drivers. Lower AddDevice Routine. Upper AddDevice Routine. Upper RemoveDevice Routine. Lower RemoveDevice Routine. Summary.



16. Driver Installation.


Installation of a Driver. Auto-Install Using INF Files. INF File Structure. Version Section. Manufacturers Section. Models Section. DDInstall Section. CopyFiles Section. AddReg Section. SourceDisksNames Section. SourceDisksFiles Section. DestinationDirs Section. DDInstall.Services Section. ServiceInstall Section. INF Example. Validating INF Syntax. Using a Driver INF File. Manual Installation. Automatic Installation. The Add/Remove Hardware Wizard. Class Names and Device IDs. Customizing an Installation. Controlling Driver Load Sequence. Driver Stack Order. Digital Signing of a Driver. Why Microsoft Verifies Drivers. Digital Signatures. Summary.



17. Testing and Debugging Drivers.


Guidelines for Driver Testing. A Generalized Approach to Testing Drivers. When to Test. What to Test. How to Develop the Tests. How to Perform the Tests. Who Should Perform the Tests. The Microsoft Hardware Compatibility Tests. Why Drivers Fail. Categories of Driver Errors. Hardware Problems. System Crashes. Resource Leaks. Thread Hangs. System Hangs. Reproducing Driver Errors. Time Dependencies. Multiprocessor Dependencies. Multithreading Dependencies. Other Causes. Defensive Coding Strategies. Keeping Track of Driver Bugs. Reading Crash Screens. What Happens When the System Crashes. The Blue Screen of Death. An Overview of WinDbg. The Key to Source Code Debugging. Symbol Directories. Source Code Directories. Some WinDbg Commands. Analyzing a Crash Dump. Goals of the Analysis. Starting the Analysis. Tracing the Stack. High IRQL Crashes. Crashes Below DISPATCH_LEVEL. Indirect Methods of Investigation. Finding I/O Requests. Examining Processes. Interactive Debugging. Starting and Stopping a Debug Session. Setting Breakpoints. Setting Hard Breakpoints. Intermediate Output. Writing WinDbg Extensions. How WinDbg Extensions Work. Initialization and Version-Checking Functions. WinDbgExtensionDllInit. ExtensionApiVersion. CheckVersion. Writing Extension Commands. WinDbg Helper Functions. Building and Using an Extension DLL. Code Example: A WinDbg Extension. DBG.C. Header. Globals. Required Functions. Command Routines. Sample Output. Miscellaneous Debugging Techniques. Leaving Debugged Code in the Driver. Catching Incorrect Assumptions. Using Bugcheck Callbacks. Catching Memory Leaks. Using Counters, Bits, and Buffers. Sanity Counters. Event Bits. Trace Buffers. Summary.



A. The Driver Debug Environment.


B. Bugcheck Codes.


C. Building Drivers.


Bibliography.


Index.