[Previous] [Next]

Figure 3-1 illustrates some of the components that make up the Microsoft Windows NT operating system. Each component exports service functions whose names begin with a particular two-letter prefix:

• The I/O Manager (prefix Io) contains many service functions that drivers use, and I'll be discussing them all throughout this book.
• The Process Structure module (prefix Ps) creates and manages kernel-mode threads. An ordinary WDM driver might use an independent thread to repeatedly poll a device incapable of generating interrupts.
• The Memory Manager (prefix Mm) controls the page tables that define the mapping of virtual addresses onto physical memory.
• The executive (prefix Ex) supplies heap management and synchronization services. I'll discuss the heap management service functions in this chapter. The next chapter covers the synchronization services.
• The Object Manager (prefix Ob) provides centralized control over the many data objects with which Windows NT works. WDM drivers rely on the Object Manager only for keeping a reference count that prevents an object from disappearing while someone is still using it.
• The Security Reference Monitor (prefix Se) allows file system drivers to perform security checks. Someone else has usually dealt with security concerns by the time an I/O request reaches a WDM driver, so I won't be discussing these functions in this book.
• The so-called run-time library component (prefix Rtl) contains utility routines, such as list and string management routines, that kernel-mode drivers can use instead of regular ANSI standard library routines. For the most part, the operation of these functions is obvious from their names, and you would pretty much know how to use them in a program if you just were aware of them. I'll describe a few of them in this chapter.
• Windows NT implements user-mode calls to the Win32 subsystem in kernel mode with routines whose names begin with the Zw prefix. The Microsoft Windows 2000 DDK exposes just a few of these functions for use by drivers, including functions for accessing files and the registry. I'll discuss those functions in this chapter.
• The Windows NT kernel (prefix Ke) is where all the low-level synchronization of activities between threads and processors occurs. I'll discuss the KeXxx functions in the next chapter.
• The very bottom layer of the operating system, on which the support sandwich rests, is the hardware abstraction layer (or HAL, prefix Hal). All the operating system's knowledge of how the computer is actually wired together reposes in the HAL. The HAL understands how interrupts work on a particular platform, how to implement spin locks, how to address I/O and memory-mapped devices, and so on. Instead of talking directly to their hardware, WDM drivers call functions in the HAL to do it. The driver ends up being platform-independent and bus-independent.

Figure 3-1. Overview of kernel-mode support routines.

Historically, the Windows NT architects have preferred that drivers not use the run-time libraries supplied by vendors of C compilers. In part, the initial disapproval arose from simple timing. Windows NT was designed at a time when there was no ANSI standard for what functions belonged in a standard library and when many compiler vendors existed, each with its own idea of what might be cool to include and its own unique quality standards. Another factor is that standard run-time library routines sometimes rely on initialization that can only happen in a user-mode application and are sometimes implemented in a thread-unsafe or multiprocessor-unsafe way.

Until now, the official rule has been that kernel-mode drivers should call only functions specifically documented in the DDK. Rather than call wcscmp, for example, one should call RtlCompareUnicodeString. It's been a pretty open secret, however, that the standard import library that one uses to build a driver (ntoskrnl.lib) defines many of the functions declared by application header files such as string.h, stdio.h, stdlib.h, and ctypes.h. So why not call them? In fact, there's no reason not to call them, provided you understand all the implications. Don't, for example, switch to always calling memcpy instead of RtlCopyBytes, because there's a subtle difference between the two. (RtlCopyBytes is guaranteed to proceed byte by byte instead of in larger chunks, which can matter on particular RISC [reduced instruction set computing] platforms.)

Many of the support "functions" that you use in a driver are defined as macros in the DDK header files. We were all taught to avoid using expressions that have side effects (that is, expressions that alter the state of the computer in some persistent way) as arguments to macros for the obvious reason that the macro can invoke the argument more or less than exactly once. Consider, for example, the following code:

int a = 2, b = 42, c; c = min(a++, b);

What's the value of a afterward? (For that matter, what's the value of c?) Take a look at a plausible implementation of min as a macro:

#define min(x,y) (((x) < (y)) ? (x) : (y))

If you substitute a++ for x, you can see that a will equal 4 because the expression a++ gets executed twice. The value of the "function" min will be 3 instead of the expected 2 because the second invocation of a++ delivers the value.

You basically can't tell when the DDK will use a macro and when it will declare a real external function. Sometimes, a particular service function will be a macro for some platforms and a function call for other platforms. Furthermore, Microsoft is free to change its mind in the future. Consequently, you should follow this rule when programming a WDM driver:

Never use an expression that has side effects as an argument to a kernel-mode service function.