Getting Started Writing Windows Drivers
OSR Staff | Published: 04-Apr-02| Modified: 01-Feb-05
Are you a beginner with a question that isn't answered by this FAQ? Are you an experienced driver writer who seems something missing from the list? If so, post a comment using the link provided at the right or at the bottom of this article. Contribute! Help your community
Are you a beginner with a question that isn't answered here? Are you an experienced driver writer who sees something missing from the list? If so, post a comment using the link provided at the right or at the bottom of this article. Contribute! Help your community!
BACKGROUND
What Are Some Of The Key Concepts In Operating Systems and Computer Science That I Need To Understand Before Learning To Write Drivers?
You need to understand some basics about operating systems and devices before you can learn to write drivers. Here's a list of things you should know:
- The difference between wait locks versus spin locks, and why spin locks might be used in an Operating System
- Threads and processes: What these are in the Windows world versus the Unix world
- What we mean by "thread safe", fully re-entrant, and MP safe
- Processor modes -- What's the difference between Ring 0 and Ring 3 in an x86 architecture system
- Memory management - User mode, versus Kernel Mode. What we mean by "demand paged virtual memory"
- What are multiple, nested, interrupt levels
- The difference between I/O port space and memory space
- Something about how devices work: What a device register looks like, why/when devices interrupt
- The definition of "direct memory access" (DMA) and the basic differences between DMA and programmed I/O relevant to a driver
What Are The Most Important Things To Know Abour Writing Drivers?
Listen to me now, and listen closely: You absolutely cannot write a WDM driver without understanding the basic architecture concepts of the operating system. This means that you must understand threading, serialization and synchronization, IRQLs, the basic objects used in the I/O subsystem (driver, device, etc), and the general flow of an I/O request through the system. Writing drivers is not like writing most applications; you absolutely cannot just find a sample and start hacking away at it to make it do what you want. It simply won't work. You have to put the work in up front to get a basic clue, or you'll be condemned to having problem after problem with no idea of how to fix what you've done.
So, you need to learn something about Windows operating sytem architecture. This means, at the very least, you need to read Inside Windows whatever-is-the-most-recent-version. You also need to read the Getting Started With Windows Drivers section of the DDK, and please, please, please, try to read as much as you can stomach of the Kernel-Mode Driver Architecture Design Guide in the DDK. There's a ton of good information in there, and while it isn't much fun to read, it'll be good for you in the end and you'll be very happy you did it.
Trust me on this one. There are very few shortcuts. Learn about the O/S. Then start to learn about how to write drivers.
How Do I Learn How To Write A Driver for Windows?
If you've written drivers for VMS or one of the many UNIX variants, and you're familiar with NT O/S concepts, you might be able to learn what you need to know by reading the documentation provided with the Windows Driver Development Kit (DDK). Get the most recent version of the DDK (see later question), and read the section entitled Getting Started with Windows Drivers. This documentation is surprising good, and covers a very broad range of topics. This is particularly true of the DDK starting with Windows XP.
If you're new to drivers, or if tackling the DDK straight off seems like a bit more than you want to handle, you can augment your sources with some of the technical books that are available. We recommend:
- Inside Microsoft Windows 2000, 3rd Edition, by Solomon and Russinovich, Microsoft Press. Good overall introduction to Windows o/s architecture.
- Windows NT Device Driver Development, by Viscarola and Mason, published by New Riders. Written by OSR's consulting partners, this book contains the details about the NT I/O subsystem. The only disadvantage of this book is that it was written in the NT V4 timeframe, before Win2K and therefore before the introduction of Plug and Play support. No matter, it's still the most solid architectural reference around. (And what's more, you can order this book directly through the OSR Online Store.)
- Programming the Microsoft Windows Driver Model, by Walter Oney. This is a solid book that covers the details of Plug and Play.
Probably the best way to come up to speed on Windows drivers fast is to take a seminar on the topic. Don't be too quick to dismiss this option, even if you consider yourself pretty smart. Sure, it costs some money. But NT drivers are both complicated and confusing enough that it can be extremely helpful to have somebody brain-dump you with just the required information. Also, if the person teaching the class has real hands-on knowledge, they can probably save you lots of time by helping you avoid some of the better-known "gotchas" that lurk in this space.
If you do opt to take a seminar, do not take one from a "local" company. There are three seminar companies to consider that offer seminars world-wide: OSR, Azius, and OneySoft. Each of these companies offer either lecture-only or lecture-plus-lab seminars, lasting from three days to a week in duration. Almost nobody (even experienced NT driver writers) takes one of these seminars and says it was a waste of time.
TOOLS OF THE TRADE
What Tools Do I Need To Write Windows Drivers?
Starting with the Windows XP DDK and later, the DDK contains everything you need. You can use this DDK to build drivers for Windows 2000 and forward. It has the compiler, header files, and everything else. Because of licensing issues, you cannot download this DDK from the web unless you are an MSDN subscriber (in which case you download it from the MSDN site). However, you can get Microsoft to send you the DDK on CD, for nothing more than shipping and handling changes. Check out http://www.microsoft.com/ddk/ for more information. The XP DDK is also part of MSDN.
If you still need to develop drivers for Windows NT V4.0, you'll need the NT V4.0 DDK, MSVC++ and the platform SDK.
Do I have to use Microsoft's Compiler?
Face it: There is very little that you really have to do in this world, besides breathe and die. Strictly speaking, you do not have to use the MS VC++ compiler. A few brave souls over the past years have used other compilers. But trying to use another compiler is best described as an exquisitely painful exercise. The DDK header files use a significant number of Microsoft specific features (such as language extensions, pragmas, and the like). Writing drivers is hard enough. Trying to write drivers using something other than the Microsoft compiler is really not something that you want to try.
What Language Can I Write Drivers In?
You write drivers for Windows in either C or C++. Support for using C++ is tenuous (click here to download an interesting paper on this topic written by one of the Microsoft kernel devs), but it can be done. Don't even think about trying to use another language. All the functions and data types are only defined in C/C++ header files. There are no assembly language definitions provided, so you can't use assembly language, either.
Further, it seems that the Microsoft Visual C++ compiler is a lot more rigorous in terms of catching ordinary errors than the MSVC compiler. So, even though it's probably best for most people to write drivers in "plain C", it's also probably a good idea to name your files *.cpp, to gain the added rigor that the C++ compiler provides.
What Debuggers Can Be Used for Driver Debugging?
WinDbg, Microsoft's standard kernel mode debugger, comes with the DDK. You can also download the latest version from here. In general, WinDbg is a powerful and reliable tool.
If you're just starting out in the world of drivers, you probably should use WinDbg. You'll hear lots of whining and carping about WinDbg from some of the "old hands" that have been doing NT driver development for years. While WinDbg is quite reliable now, this has not always been the case.
An alternative to using WinDbg is the use of Compuware's NuMega Labs SoftICE. This debugger gained fame for its speed and reliability debugging Windows 95 drivers. Even under Windows, SoftICE has a loyal developer following.
Whichever debugger you choose, be sure to read the documentation. WinDbg, especially, has very considerable documentation that describes everything from how to set up the debugger to how to configure its many features.
What Testing Tools Are Available?
The Windows operating system contains the most powerful testing tool available, Driver Verifier.
Driver Verifier is available starting with Windows 2000. Its features are very much enhanced in Windows XP and later releases.
Driver Verifier (usually, referred to as just "Verifier") comprises special set of modules in the operating system that carefully monitor the execution of specific drivers. If Verifier detects an inconsistency, or any incorrect operation, it will display a diagnostic message in the debugger and then crash the system.
Driver Verifier is setup and controlled using the utility verifier.exe, located in the Windows system directory. Using verifier.exe, you can configure Driver Verifier to monitor specific drivers (such as a driver that you are writing) for problems.
Driver Verifier is best when it's used throughout your entire debugging process. That is, you should always have Verifier enabled for your driver on your test machine. As you go through the process of adding functionality to or modifying your driver, Driver Verifier will be there to watch your driver's actions.
It's important to realize that Driver Verifier is essentially a passive monitor. That means that while it might occasionally modify the information sent to your driver, it mostly just watches what your driver does. Driver Verifier itself is not a tester. It doesn't send any I/O requests to your driver. Therefore, in order to make use of Driver Verifier, you will have to send the broadest range of both valid and invalid I/O requests to your driver. This will allow Driver Verifier to monitor your driver's behavior in the broadest possible set of conditions.
Are There Other Test Tools, Besides Verifier?
Absolutely. Check the \tools directory in the DDK. With each new release of the DDK, more tools are added. Some of these tools are exceptionally powerful and useful. For starters, check out DC2 (called "device path exerciser" in the DDK documentation). We may provide a more comprehensive list later, if we get to it.
In the mean time, look into "Call Usage Verifier" (CUV) and deprecated function checking, both described in the DDK. Strictly speaking, these aren't test tools; but then again, neither is Driver Verifier.
How Do I Get Started Using The DDK?
Install the DDK on your development machine. Note that drivers are built from the command line using the BUILD utility, not from Visual Stuido (though, if you really want to, you can invoke BUILD from within Visual Studio... see the OSR Online article here for how to do this and operationally download the command procedure that will help you do this). You run the BUILD utility from a command prompt window that's been started through the shortcut menus that the DDK installs on your system. Go to Start->Programs->Development Kits->Windows DDK->Build Environments and choose a target build environment. If you don't know which build environment to target, choose the most recent version of Windows. Be sure to read about the build environment and the build utility buried in the DDK documentation under the topic Driver Development Tools, Tools For Building Drivers, Build.
Where Can I Get The Latest DDK?
If you're an MSDN subscriber, you can log in and download the latest Windows DDK from Microsoft's MSDN Website. If you are not an MSDN subscriber, you can visit Microsoft's DDK site and request that Microsoft send you a free copy of the DDK on CD, however you will have to pay a nominal fee for shipping and handling (this was US$15 for shipping within the USA when this FAQ was last updated).
What's This Checked Build Stuff?
Windows comes in two basic flavors: (a) The normal distribution kit that everybody uses, and (b) A special build that has debugging information in it. The build with debugging information is for use by driver writers, and for diagnosing serious system problems. This debug build is called the "Checked Build."
See the XP DDK's Getting Started section, Guide to Using the Free and Checked Builds, for a full run-down on what the checked build is, where you get it, and how to best make use of it.
CREATING YOUR DRIVER
There Are Many Different Driver Models -- How Do I Know What KIND Of Driver I Should Write?
This is a much harder question than it might at first appear. Basically, get the latest DDK. Look at the Table of Contents. It has a list of major sections, one per class of device. For example, the DDK that I'm looking at as I write this has:
Battery Devices
Display and Print Devices
IEEE 1284.4 Devices
Modem Devices
Multifunction Devices
Network Devices
Parallel Ports and Devices
Serial Ports and Devices
Smart Card Devices
Storage Devices
Streaming Devices (Video and Audio)
Other Devices
System Support For Buses
If your device type doesn't jump out at you right away above, be sure to look under "System Support for Buses." If you need to support, for example, a SCSI adapter, that's where you'd look.
If your device falls into one of the categories described (not including "Other Devices"), you're all set. This is good, because Windows provides shortcut models for writing drivers for common types of adapters (some of these shortcut approaches are called "mini-drivers" or "mini-ports"). Unless you need to do something very unusual, you can save a ton of time using one of these custom-tailored driver environments.
On the other hand, maybe you're trying to write a device driver for a battleship or something that's not in the list. In this case, you'll be writing what's known as a "Standard Kernel Mode Driver." Refer to the DDK section named "Kernel-Mode Driver Architecture" and go from there. This is also the type of driver that you'd write if, for some strange reason, you can't use the typical mini-port or mini-driver model for a well-known device type.
Where Can I Get Driver Samples?
The DDK is a good place to start. There are a bunch of example drivers that are provided, under the src directory. These drivers are often the source code for the actual drivers that ship with the operating system. The DDK's license specifically allows you to start with these drivers as a base for your own driver, so go for it.
If you take a seminar, especially a lab seminar, you'll undoubtedly walk away with one or more sample drivers.
If you don't see a sample that's similar to the type of driver you need to write, ask one of the sources listed in "Where Do I Get Help."
How Do I Start Cranking Code?
Get the source code sample driver for a device of similar type to the one that you need to support. Assuming your license allows it, start by modifying this driver.
After I Write It, How Do I Install It?
You'll need to create an installation control file (AKA a ".inf file") to get your driver installed in the system. The .INF file is used by the setup program, which is invoked from the "Add/Remove Hardware" option in Control Panel. Yes, even if you're writing a driver that isn't directly associated with any hardware, it's still installed from "Add/Remove Hardware." Of course, if you want to get really fancy, you could write an attractive GUI program that invokes your .INF file to do the installation.
What Is WDM? WDF?
WDM stands for Windows Driver Model. There's been a number of changes in the meaning of this term over the years, so almost everybody is confused about exactly what it means. However, as of Windows XP, WDM is the "forward moving" model by which drivers are built.
Note that there is also a new, emerging way to write Windows drivers called the Windows Driver Foundation (WDF). This Microsoft-developed solution comprises a User-Mode Framework and a Kernel-Mode Framework. It is much cleaner, and easier to understand, than WDM. As of the date of this writing (Nov 2004) these Frameworks were not yet formally released by Microsoft. When they are released, you will want to use WDF to write your drivers, not WDM.
Do I Include WDM.H or NTDDK.H?
You want to include WDM.H. Though the definition has changed over the years, this header contains all the definitions for the Windows Driver Model. WDM is the "forward moving" model by which drivers are built. If it's not in WDM, it's probably a legacy driver type or function, and you should probably stay away from it.
I Want to Change The Way A Standard Driver Works - Can I Modify The DDK Sample and Just Replace The Standard Windows Driver?
No! A million times no. This causes nothing but trouble. Plus, Windows File Protection (otherwise known as System File Protection) will probably "get" you in the end (see related questions).
The right way to modify the behavior of a standard Windows driver is to write a filter driver. This driver can sit either above or below the standard driver, and modify its behavior. You can even use this approach to provide additional functionality.
What Is Windows File Protection?
This is also called System File Protection. It is the mechanism by which Windows ensures that standard system files (files in %systemroot% and below) are not modified. If you attempt to delete or change one of the files in your Windows system directory, such as a standard driver or standard DLL, Windows File Protection will simply overwrite your changed file with the original. It's very effective. Microsoft does not allow you to turn it off on your customers' machines, so forget about it.
SUPPORT CONSIDERATIONS
Do I Have To Support PnP In My Driver?
If you're writing a driver for Windows 2000 or later, the answer is (effectively) "YES." There are some weird types of drivers that strictly speaking do not fall into the Plug and Play category (like file systems, or some specific pseudo drivers), but in general your driver has to support PnP.
Do I Have To Support PnP, Even If My Device Can Never Be Removed From The System?
Yes. PnP is the basic process by which Win2K and later finds devices.
Can I Write My Driver First, and Add PnP Later?
The only real answer to this question is "no." You could do it, but it would make things harder than just implementing PnP in the first place. Sorry, the bottom line is you have to implement PnP.
Do I Have To Support Power Management In My Driver?
Strictly speaking, no, but you want to. Really. The reason is that if your driver does not support power management, the entire system on which your driver is running will not support power management. Worse, if the system tries to suspend, and it can't because your driver doesn't support power management, a little message box pops up saying something like "Attempt to suspend failed because the xyz driver does not support power management." So, Windows shames you into needing to support power management, even if you weren't so inclined out of the goodness of your heart.
GETTING HELP
Where Can I Get Help?
You mean where can you get free help, right? If you subscribe to MSDN, you automatically get the privilege of calling DDK Developer Support once or twice with problems. These folks are generally very helpful. Do not expect them to write your driver for you, however.
There are a surprising number of peer help forums. Check out the NTDEV (for driver developers), NTFSD (for file system developers), and WINDBG (for WinDbg debugger users) lists here at OSR Online. You must subscribe to contribute. Note that you can choose to join these groups either as traditional list server mailing lists, online or as private usenet news groups. To do the latter, point your news reader to lists.osr.com. You will be required to log in to these groups by providing your username and password (that you specified when you joined) in order to post to the group.
Another fairly good usenet news group is comps.os.ms-windows.programmer.nt.kernel-mode.
The people in all of these forums are generally very helpful. Surprisingly often, the MS support folks or developers informally answer questions on all these lists. All the lists expect you to do your homework: Check the DDK documentation and the Microsoft Knowledge Base, and be sure to read the group archives before asking your question. Don't expect people in these groups to write your driver for you.
A very useful publication is The NT Insider, published every two months by OSR. One of the best things about it is that it's free. Visit http://www.osr.com/ for your free subscription.
Suppose I Want To Pay for Help?
One option is per-incident support from Microsoft's DDK Developer Support group. It's relatively inexpensive, and the support people are typically very helpful and know what they're doing.
There are also a significant number of companies that provide services ranging from per-incident consulting to per-project design/build/test pricing. The costs range from pretty inexpensive to stratospheric, depending on whom you choose. In general (assuming you want to write the driver yourself), we advise you to first exhaust the (free) peer-support options and all possibility of help from Microsoft DDK Developer Support before even considering paying anybody else for assistance.
Question any company carefully as to their real hands-on skills and experience in your specific type of driver before forking over your money. Don't pay somebody who develops printer drivers for a living to help you with your driver for a mass storage device. These two types of drivers have fundamentally nothing in common. On the other hand, don't engage a high-end expert firm to help you with your garden variety simple driver. This is a bit like taking your Ford to a Ferrari mechanic for a tune up. He can do it, but you'll wind up paying Ferrari prices.
Related Articles
WINVER Incorrectly Defined in XP/.NET Beta DDK's Win2K Build Environment
Advantage: Driver Writer -- New Functions in the Windows XP DDK
XP DDK Resets PATH Environment Variable
New DDK Package -- The DDK Suite (Update)
Need the XP DDK FAST?
Must Use New DDK Compiler
Windows XP® DDK
Interview: All About the DDK
Guest Article: Simplifying Development with DDK Macros
The DDK Is Dead -- Long Live the LDK!
User Comments
Rate this article and give us feedback. Do you find anything missing? Share your opinion with the community!
Post Your Comment
"Most Important Things To Know..."
In the article: "What Are The Most Important Things To Know About Writing Drivers?"
It is mentioned: "...you need to read Inside Windows whatever-is-the-most-recent-version."
Please note that most recent version of the "Inside Windows whatever-is-the-most-recent-version" book is currently titled: "Microsoft Windows Internals (4th Edition)..." This edition doesn't cover Windows Vista. However, the 5th Edition should be release in a week or two. that edition does cover Windows Vista.
Rating:
07-May-09, Bruce Olney
"Useful information"
This article is useful for new beginner.
Rating:
29-Oct-06, Mike Dawn
"'windowsupdate' for checked build"
Is there such a thing as windowsupdate.microsoft.com for the checked build? Or does that site cater to updating both normal and check builds?
Rating:
06-Feb-04, Richard Chan
"test tools"
Are there not newer test tools available in the DDK? Looking for that "comprehensive list" you mention in Q22...
Rating:
16-May-03, James Covey
|
|
