Windows 2000 Device Driver Book, The: A Guide for Programmers, 2nd Edition

About

Features

• NEW -

Description

The Windows 2000 Device Driver Book can lead any experienced Windows programmer through every step of device driver development: planning, implementation, testing, debugging, installation, and distribution. Thoroughly updated to reflect Microsoft's Windows Driver Model (WDM) for Windows 2000 and 98, it covers everything from architecture to tools, and includes a powerhouse library of exclusive tools and C and C++ code for streamlining device driver projects. Starting with a high-level overview of WDM components, the book quickly moves into the details of the development environment and driver installation. Master the I/O Manager, its data structures, and its interaction with drivers. Understand Plug and Play and Power Management through extensive practical examples; learn how to construct safe reentrant driver code; log errors and events using Windows Management Instrumentation; utilize kernel-mode threads; layered drivers; and more. The accompanying CD-ROM includes sample drivers, C++ classes to jumpstart your projects, driver installation utilities, even an exclusive device driver AppWizard!

Sample Content

Downloadable Sample Chapter

Click here for a sample chapter for this book: 0130204315.pdf

Table of Contents

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Preface

Preface

This book explains how to write, install, and debug device drivers for Windows 2000. It is intended to be a companion to the Microsoft DDK documentation and software.

Windows 2000 represents a major improvement to previous versions of Windows NT. Device drivers for Windows 2000 may be designed for the new Windows Driver Model (WDM) architecture. If so, the driver will be source compatible with Windows 98. This book covers the new WDM specification.

This book will also prove useful to those studying the internals of Windows 2000, particularly the I/O subsystem and related components.

What You Should Already Know

All instruction assumes a base knowledge level. First, the reader should be familiar with Windows 2000 administration—security and setup, for example. Since experimentation with kernel-mode code can (and will) cause system problems, the reader should be prepared and able to restore a chaotic OS.

Second, the reader should be competent in the C programming language and somewhat familiar with C++. Only a little C++ is used in this book, and then only for the purpose of simplifying tedious code.

Third, experience with Win32 user-mode programming is useful. Knowing how user-mode code drives I/O devices is useful in designing and testing device driver code. The test code for the examples in this book rely on the console subsystem model for Windows. To review this topic, the reader is referred to the Win32 Programmers Reference, particularly the chapters on I/O primitives (CreateFile, ReadFile, WriteFile, and DeviceIoControl). The bibliography lists other references for this topic.

Finally, while no specific prior knowledge of hardware or device driver software design is assumed, it would be useful if the reader had experience with some aspect of low-level device interfacing. For example, knowledge of writing device drivers for a Unix system will prove quite useful when reading this book.

What's Covered

The focus of this book is to first explain the architecture of the hardware, environment, and device driver, and then to explain the details of writing code.

Chapters are grouped within this book as follows:

• Chapters 1-5: The first five chapters of this book cover the foundation of what's needed to write a device driver. This includes coverage of the Windows 2000 architecture, hardware terminology and bus basics, and an in-depth view of the Windows 2000 I/O Manager and related services.
• Chapters 6-13: The next eight chapters form the nucleus of this book. The chapters cover everything from the mechanics of building a driver to the specifics of instrumenting a driver to log errors and other events.
• Chapters 14-15: These two chapters deal with somewhat more advanced topics within device driver construction. This includes the use of system threads, layering, filtering, and utilizing driver classes.
• Chapters 16-17: The final chapters deal with the practical but necessary details of driver installation and debugging. The use of Windows 2000 INF files for "automatic" installation of a plug and play device driver is covered (as well as manual installation for legacy devices). The use of WinDbg is covered in sufficient detail so that the programmer can actually perform interactive debugging.
• Appendices: The appendices cover reference information needed for driver development. The mechanics of Windows 2000 symbol file installation, bugcheck codes, and so on are listed.

What's Not

Since the purpose of this book is to cover driver development from "the ground up," some specific topics fall outside its scope. Specifically, the list of topics not covered includes

File system drivers

Currently, the construction of a full Windows 2000 Installable File System requires the acquisition of the Microsoft IFS kit. The bibliography of this book points to one source for more information on this topic. Potential users of the IFS kit will benefit greatly from this book, as the material covered is essential prerequisite knowledge.

Device-specific driver information

The construction of NIC (Network Interface Card), SCSI, video (including capture devices), printers, and multimedia drivers is not specifically covered in this book. Chapter 1 discusses the architectural implications of such drivers, but even individual chapters on each of these driver types would seriously shortchange the requisite knowledge.

Virtual DOS device drivers

The current wave of driver development is toward the WDM 32-bit model. Legacy 16-bit VDDs are no longer of interest.

About the Sample Code

Most chapters in this book include one or more sample drivers. All code is included on the accompanying CD. Samples for each chapter are in separate subdirectories on the CD, so installation of individual projects is straightforward.

The CD also includes a device driver application wizard for Microsoft Visual C++ version 6. This wizard configures the build environment so that code can be written, compiled, and linked within Visual Studio.

Platform dependencies:

The sample code included with this book has been targeted and tested on Intel platforms only. Since it appears that the last non-Intel platform (Alpha) was dropped from the final release of Windows 2000, this should come as no surprise. Be advised, however, that Windows 2000 is intrinsically a platform-independent OS. It is a straightforward process to port the OS to many modern hardware sets. Driver writers should consider designs that take advantage of the Windows 2000 abstractions that permit source compatibility with non-Intel platforms.

To build and run the examples:

Besides the Microsoft DDK (Device Driver Kit) (which is available on an MSDN subscription or, at present, free for download from the Microsoft web site at www.microsoft.com/DDK), the sample code assumes that Microsoft Visual C++ is installed. The device driver application wizard was built for Visual Studio version 6. Obviously, with some effort the sample code can be built using other vendors' compilers.

Of course, an installed version of Windows 2000 (Professional, Server, or Enterprise) is required. For interactive debugging using WinDbg, a second host platform is required.

History of this Book

The first version of this book was written by Art Baker, entitled The Windows NT Device Driver Book. By any account, the book was required reading for any NT driver author. The Microsoft driver model is a continuously moving target. As such, recently introduced books on this subject provided more and up-to-date information. The goal of this revision of the book is to carry forward the goals, style, and clarity of Art's original work while updating the material with the very latest information available from Microsoft.

If you are a previous reader of the original version of this book, I hope you will find this version just as useful. I have attempted to provide accurate, concise, and clear information on the subject of Windows 2000 device drivers. While I have relied heavily on Art's original work, any errors present in this book are entirely mine.

Training and Consulting Services

The material in this book is based on training and consulting performed for various companies within the industry.

The subject matter of this book is presented exclusively by UCI in the format of a five-day instructor-lead lecture/lab course. The course is available as public or on site classes. UCI provides comprehensive training in high-end programming, web development and administration, databases, and system technologies.

For more information please visit the UCI web site at www.ucitraining.com or use the address information below:

UCI Corporation
4 Constitution Way
Suite G
Woburn, MA 01801

1-800-884-1772

The revision author, Jerry Lozano, provides seminars and workshops on the topic of device drivers and other related subjects. For more information visit the web site: www.StarJourney.com

Updates

Submit Errata