Chris Cant: Writing Windows WDM Device Drivers

First, I suggest that you check the book's web site at www.phdcc.com/wdmbook/. These pages will list any errata, etc., and include a feedback page. This book was written mainly using Windows 98 and the Beta 2 version of Windows 2000, with some updates for the Beta 3 version. I will try to ensure that I post any necessary updates on the book's web site.

Although this book and the Microsoft documentation can give you a good start when writing device drivers, it is only when you write one yourself that you really learn about device drivers. Often it is only when you make mistakes that you find out how to write code correctly. I have tried to include some anecdotes of when I have erred and the techniques I have used to track down the problem and sort it out. Trying to explain the example code in detail in this book has helped iron out some wrinkles, so I recommend that you describe your code line by line to someone else.

Read this book if you want to learn how to write device drivers for Windows 98 and Windows 2000. It covers the core Windows Driver Model (WDM) fully and looks at two types of system class driver in detail, for the Universal Serial Bus (USB) and Human Input Devices (HID).

The book also covers Window NT 4 and NT 3.51 drivers. These "NT style" drivers will also run in Windows 2000 and sometimes in Windows 98.

I suggest that you run all the examples and study their source code to get the full benefit. The book software includes some software called DebugPrint that lets you view the trace debug statements produced by the example drivers.

If you use a proprietary device driver toolkit, you should still find this book useful. First, the core WDM chapters give a background to the whole subject and might help explain how your toolkit works. Some features of WDM may not be covered by your toolkit and so will need to be implemented "by hand". More importantly, the class driver chapters give you the information you need to write drivers for various device categories.

Firmware or hardware engineers will also find it useful to read some sections of this book. When you design your external device, a software engineer will need to write a device driver to talk to it. Reading the first chapters of this book should let you speak "their language". Help them by providing clear specifications of your hardware at the appropriate level.

If you are currently a VxD driver writer, then many of the general concepts presented in this book will be familiar. However, you will find that the implementation techniques are quite different.

If you have written drivers for NT 4 and NT 3.51, some of the core WDM chapters will be familiar territory. However, Plug and Play and Power Management are crucial new areas of functionality. Supporting Windows Management Instrumentation (WMI) is desirable. The system class drivers will be new to you as well.

NT drivers should run unchanged in Windows 2000, and can sometimes run in Windows 98. However, you should seriously consider migrating to the Plug and Play if it's appropriate. Supporting Power Management will help to reduce power on and shutdown delays, making PCs more pleasant to use. The Direct Memory Access (DMA) system is used in a slightly different way by WDM device drivers.

Whenever a new and important piece of terminology is introduced, it is highlighted in italic text. Kernel function names (e.g., IoCompleteRequest) and driver function names (e.g., Wdm1Create) are in bold monospaced text. Code examples are in monospaced text.

Acronyms are spelled out when they are first used. Please refer to the Glossary for a full list.

Globally Unique Identifiers (GUIDs) are long obscure strings used to identify Component Object Model (COM) objects and device interfaces. A full GUID such as

{C0CF0640– 5F5E -11d2-b677-00c0dfe4c1f3} is often abbreviated as {COCF0640…}.

When I refer to "Windows", you can take it that I mean both Windows 98 and Windows 2000. "Windows" does not refer to NT 3.51 and NT 4 unless the text specifically says so. In case it is not obvious, W98 refers to Windows 98 and W2000 refers to Windows 2000. Windows 2000 was originally called NT5.

You will have to endure the coding style that I have used for the book and its example source code. You will find that actual driver code on disk often contains more comments than the main text listings.

Most of the code examples are written using C++ although I do not make great use of C++ features. For example, there are no C++ classes used.

Boolean true and false values arc represented by two different types. Kernel calls must use the BOOLEAN type, which is really an unsigned char, where zero means FALSE and non-zero means TRUE. For any other Boolean values, I use the intrinsic C++ bool type that has false and true values.

The main text often refers to Win32 applications. I have not yet come to grips with the implications of Win64, the 64-bit version of Windows 2000. However, you can assume that whatever calls a Win32 application can make, a Win64 application will also be able to make.

Of more importance, I have not yet found out what happens to device drivers in Win64 systems.

Revised source code for the following files are on the Writing Windows WDM Device Drivers web site, www.phdcc.com/wdmbook:

• DebugPrint\sys\DebugPrint.INF

• Wdm3\sys\Wdm3free.inf

• NT\install.cpp

Several people have helped directly and indirectly in making this book. First, thanks to Alec Erskine for drawing the cartoons and Ian Cuthbert for scanning them. Caz, Jenny, and Viv have stoically endured months of me "'putering too much". Berney Williams at R&D provided the initial impetus for the project and gave crucial support as the book was written. My brother John and my friend Robin Sillem have helped considerably with ideas and proofreading. Thanks to Vireo Software, Inc., for the review copies of Driver::Works and Driver::Agent, and for a useful web site.

In this book, I will tell you how to write some types of device driver for Windows. I will primarily describe the Windows Driver Model for Windows 98 and Windows 2000. Additionally, I will cover device drivers that also run in Windows NT 3.51 and NT 4, which I call "NT style" drivers.

A device driver provides a software interface to hardware connected to a computer. It is a trusted part of the operating system. User application programs can access hardware in a well-defined manner, without having to worry about how the hardware must be controlled. For example, a disk driver might hide the fact that data must be written in 512-byte chunks. A driver is a piece of software that becomes part of the operating system kernel when it is loaded. A driver makes one or more devices available to the user mode programmer, each representing a physical or logical piece of hardware. For example, one physical hard disk may be viewed as two logical disks called C: and D:.

In Windows, a driver always makes a device look like a file. A handle to the device can be opened. An application program can then issue read and write requests to the driver, before the device handle is finally closed.

Clearly, there are many pieces of hardware that are essentially alike, because they share a bus or do similar tasks. Microsoft provides several generic drivers that perform these common tasks. Device drivers can use the facilities of these standard drivers. This approach makes it easier to share a common bus, and makes it simpler to write new drivers.