Developing Windows NT Device Drivers: A Programmer's Handbook, Vol. 0

PREFACE: \ Welcome to the World of Device Drivers\ This is a book on how to write Device Drivers. Device Drivers are those very specialized pieces of software that live inside the operating system and allow it, and thus your programs, to communicate to the outside world. Every communication NT makes to the outside world, including the keyboard, mouse, display, disks, CD-ROMS, and printers requires a Device Driver. Most of the key ones have been written by Microsoft, and NT supports all the "standard" devices.\ But what about "nonstandard" devices? This doesn't mean the devices don't conform to a standard; what it means is that these are devices that are not found on "standard" PCs. Often they are specialized devices whose market is far too small for Microsoft to devote any energy to supporting. These could be devices such as drivers that support IEEE-488 communications (used for laboratory equipment and test equipment), analog-to-digital data input boards, digital-to-analog data output boards, specialized communications boards, and the like.\ The core problem in Windows NT is that if you don't have a Device Driver you can't talk to a device. In Windows 3.x and Windows 9x you can cheat; you can write an application program that goes "for the bare metal" and directly manipulates the hardware interface to the device. But in Windows NT, because of the requirements for being certified at C2 Security (an important certification commercially and for government sales), an application program is simply not permitted to manipulate the hardware directly. So you are confronted with the problem of writing a device driver.\ That's what this book is all about.\ How This Book Happened\ One evening after a long day at Comdex, Ed and I (jmn) were sitting around discussing our Latest Adventures. Ed was telling me about all the really cool, largely non-obvious (not undocumented, but obscurely documented) things he'd learned about writing device drivers. I said to him, "Ed, you should write a book". (At this point I was well into the writing of Win32 Programming, so writing books was at the top of my consciousness). He looked at me and said "Joe, I don't know how to write a book". I immediately responded "Well, I don't know how to write a device driver!" The conclusion was obvious. So we wrote a proposal to Addison-Wesley, and you are holding the result.\ What We Cover\ The purpose of this book is to allow you to write NT Device Drivers for a new device that you would want to connect to an NT machine. These include polled, programmed I/O, interrupt-driven, and DMA devices. Modern interrupt drivers add complexity, because interrupts may be shared by several devices. DMA has changed from the use of the PC's onboard DMA controller to external DMA controllers and Bus Mastering controllers. Many drivers for modern devices need access to onboard memory, and we show how to do that. In some cases, you might want to write a "user level" system that does most of the work, calling the I/O subsystem only to initiate certain input or output transactions, and using it to handle interrupts. We show how to construct these drivers.\ We talk about how to build robust, portable, multithread- and multiprocessor-safe drivers. We talk about what you have to do to ensure that your driver won't bring the system crashing down around the user. We lay out the protocols you must use in communicating to the rest of the system; if you don't follow these fairly exactly, the system won't work as expected. It may crash, it may corrupt the disk, it may ignore the device, it may lose information on input or output, or it may misinterpret the intention of the application programmer who calls the services of the driver. Writing a Device Driver is fairly exacting. We try to capture much of the Art of building a device driver here, as well as the Technology.\ In addition, we talk about how to actually build drivers, that is, the mechanics of compilation and linking; what they have to do to register themselves with the system, and most importantly, how to debug them. Most of the useful techniques for debugging device drivers is either undocumented or difficult to find; we've summarized our experiences in this book.\ What We Don't Cover\ There is only so much that one book or set of books can cover. We've chosen our goals to cover what most device driver writers want or need. But there are several aspects we don't cover at all:\ Graphics drivers. These include display drivers and printer driver. The Graphics Driver contains the code to render an image into the internal frame buffer of the Video Adapter or printer engine. Most of the effort goes into understanding the incredibly clever hacks needed to get optimal efficiency on a particular piece of hardware. Graphics drivers are in the range of tens of thousands of lines of code. Generally, unless you work for a display card vendor or printer vendor, you will never encounter a need to write one of these. And while there is often a desire to support some old printing or plotting device, frankly, the cost of developing one of these drivers would buy several modern equivalents of those old printers. Chapter 25 contains a very high-level overview of graphics drivers. To do them justice would take another book about this size.\ File System Drivers would be worthy of an entire book on their own. In fact, this has already been done (see Further Reading). To write an entire file system is far more complex and is beyond the scope of this book. We've never written a file system, and are not now qualified to write about how to do it. Network Drivers. Network drivers are worthy of an entire book devoted just to that subject (there is a pattern here). The chances that most device writers will ever need to write a full network driver are fairly slim. At the lowest level (for example, the card driver) a network card driver bears a strong resemblance to most other devices, but there are some additional complications that require a deep understanding of network protocols. There is just not enough space available in this book to cover network drivers.\ In addition, recognize that this is software. There are dozens of ways to do anything. We present the core methods, and possibly one or two interesting alternatives. We cannot tell you every possible way to do every possible thing (for one thing, we haven't done every possible thing in every possible way ourselves!) Many techniques are unique to particular devices, and in some cases our ability to talk about some of the more interesting advanced techniques is circumscribed by various Non-Disclosure Agreements we have signed. What we hope to give you here is a sound footing in basic driver technology and illustrate a few of the more interesting advanced techniques that you may need. But the coverage here is not "complete". If we started to write a "complete" book on version n of NT, we would not have delivered the manuscript before version n+1 was released. This wouldn't help anyone.\ The Physics Model for Software\ No, not "Software Physics". That's something else entirely. The "Physics Model" refers to a comment by a physics professor, who said "We have an advantage in physics; we teach it by an ever more refined set of lies". What he was referring to is that when physics is first taught, you learn about Newtonian physics. In this model, we have phenomena such as the wave model of light, the particle model of light, and so on. Physical objects are real, and their masses interact according to specified laws of gravity or of energy transfer. But relativity theory tells us that Newtonian physics is really relative to a particular inertial frame, and what is really going on is something different. In Quantum Mechanics, you learn that at a certain scale, physical objects don't exist, and phenomena like the Heisenberg Uncertainty Principle come into play, and you get an explanation of what is really going on. Then there's Quantum Electrodynamics, in which the real model of what is going on is explained, and then...well, it's been too long since our physics courses and anyway you should have the idea by now.\ We apply this same principle to teaching software. So don't be surprised if there are some apparent discrepancies between the illustrations and text on one page and the illustrations and text on a later page. We're trying to avoid giving you infinite detail too early and thus avoid being too confusing. Ideally, the earlier text or illustration is a subset of the later one.\ About URLs\ While many people know about URLs, not everyone might be familiar. A URL is a Universal Resource Locator, a designator for a page of information on the World Wide Web. A URL has a form like\ \ ...\

List of FiguresList of TablesCode ListingsPrefaceCh. 1Overview of Drivers1Ch. 2I/O: User-Level Overview31Ch. 3Planning a Device Driver45Ch. 4I/O Hardware: Internal Busses71Ch. 5Device Driver Basics95Ch. 6Overview of Kernel Memory: Caching, Paging, and Pipelining107Ch. 7Driver Data Structures129Ch. 8Device Driver Structure151Ch. 9Debugging a Device Driver169Ch. 10Approaching Reality: Moving Data221Ch. 11Approaching Reality: Synchronization247Ch. 12Achieving Reality: Memory Management265Ch. 13Achieving Reality: Touching the Hardware279Ch. 14Achieving Reality: Interrupts and the Driver291Ch. 15Achieving Reality: Timers311Ch. 16Achieving Reality: Driver Initialization325Ch. 17Achieving Reality: Direct Memory Access337Ch. 18Achieving Reality: The Rest of the Details353Ch. 19Mapping Kernel and Device Memory to User Space363Ch. 20I/O Hardware: The ISA Bus383Ch. 21I/O Hardware: The PCI Bus395Ch. 22Serialization within the Driver433Ch. 23Layered Drivers461Ch. 24Driver Threads491Ch. 25Specialized Drivers in NT: An Overview525Ch. 26Useful Driver Techniques553Ch. 27A Hardware Simulator605Ch. 28Windows 2000 Preview635Ch. 29I/O Hardware: The Universal Serial Bus683Ch. 30The Win32 Driver Model739App. A: Reference779App. BError Codes and NTSTATUS Codes1001App. CBugCheck Codes1107Index1119

\ BooknewsA guide to the techniques, tools, methods, and pitfalls of building device drivers for Windows NT 4.0. Coverage focuses on drivers for polled, programmed I/O, interrupt-driven, and DMA devices. The authors discuss the components of a kernel mode device driver, with background on two primary bus interfaces currently used: the ISA and PCI buses. They also explain the mechanics of compilation and linking, how the drivers register themselves with the system, mapping device memory or kernel memory into user space, and techniques for debugging. Annotation c. by Book News, Inc., Portland, Or.\ \