The Kernel-Mode Programming Environment

Figure 3-1 illustrates some of the components that make up the MicrosoftWindows XP operating system. Each component exports service functions whose names begin with a particular two-letter or three-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, and for other purposes.
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 XP works. WDM drivers rely on the Object Manager for keeping a reference count that prevents an object from disappearing while someone is still using it and to convert object handles to pointers to the objects the handles represent.
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 XP implements the native API for kernel-mode callers using routine names that begin with the prefix Zw. The DDK documents just a few of the ZwXxx functions, namely the ones that pertain to registry and file access. I ll discuss those functions in this chapter.
The Windows XP 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 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.

Using Standard Run-Time Library Functions

Historically, the Windows NT architects 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 happen only in a user-mode application and are sometimes implemented in a thread-unsafe or multiprocessor-unsafe way.

I suggested in the first edition that it would be OK to use a number of standard runtime library functions for string processing. That was probably bad advice, though, because most of us (including me!) have a hard time using them safely. It s true (at least at the time I m writing this paragraph) that the kernel exports standard string functions such as strcpy, wcscmp, and strncpy. Since these functions work with null-terminated strings, though, it s just too easy to make mistakes with them. Are you sure you ve provided a large enough target buffer for strcpy? Are you sure that both of the strings you re comparing with wcscmp have a null terminator before they tail off into a not-present page? Were you aware that strncpy can fail to null-terminate the target string if the source string is longer than the target?

Because of all the potential problems with run-time library functions, Microsoft now recommends using the set of safe string functions declared in NtStrsafe.h. I ll discuss these functions, and the very few standard string and byte functions that it s safe to use in a driver, later in this chapter.

A Caution About Side Effects

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.