Windows Driver Kit (WDK) Documentation Blog

Refresh of the Kernel-Mode Driver Architecture Reference section

Hi, I’m Seth McEvoy and I’m the writer for the Kernel-Mode Driver Architecture section of the Windows Driver Kit (WDK). My section is here: http://msdn.microsoft.com/en-us/library/aa973498.aspx. I’ve only been writing on the kernel for about a year, but I’ve been at Microsoft for 17 years writing about all sorts of programming topics, including several other operating systems, OLE, COM, and Windows Media.

Most device drivers for Microsoft Windows use routines exported by the kernel to do their work. For the past several years, while the focus of the WDK writing team was on device technologies such as networking or video, the only work done on the kernel documentation consisted of fixing existing material. As part of a general house-cleaning of the WDK documentation, we decided to have a fresh and complete technical review of all 802 topics in the Kernel-Mode Driver Architecture Reference section. Even though the kernel developers were already working around the clock to create a better kernel for Windows Vista SP1 and Windows Server 2008, they carefully read the kernel reference topics and provided detailed feedback on every single one.

Many of the topics were fine, but some needed to be rewritten completely and many more had changes of one sort or another. Some of the errors were just plain old typos that nobody had ever noticed, some involved changes for Vista, some were based on changes inside the kernel, and some were based on newer understandings of how the kernel works (it’s complicated). For example, a minor fix would be something like changing an IN parameter from a ULONG to a SIZE_T. But one of the more interesting changes was to warn our readers that for MmGetMdlPfnArray, “Manipulating the contents of this array can cause subtle system problems that are very hard to diagnose. Reading or changing the contents of this array is not recommended for driver writers.” In other words, don’t even read the array!

All in all, we updated 182 topics and we will continue to be vigilant about keeping the kernel routines accurate. The kernel developers were extremely helpful and often worked nights and weekends to help us track down the truth of a particular topic. We all agree that we need to have a kernel API that is 100% accurate.

The next item on our plate is to start scrubbing the Kernel-Mode Driver Architecture Design Guide, which is here: http://msdn.microsoft.com/en-us/library/ms796245.aspx. These topics cover Windows kernel architecture, device driver fundamentals, and kernel-mode programming techniques. Many of these topics are old or were placed anywhere they fit. We want to examine the Design Guide topics for overall effectiveness, clarity, usability, and technical accuracy.

If you find any areas of the Kernel-Mode Driver Architecture Reference section that you think are still not clear or are causing you problems, please provide feedback on the topic by using the MSDN feedback dialog or the feedback link that’s on every page in Document Explorer. You can also help by telling us about any areas of the Kernel-Mode Driver Architecture Design Guide that aren’t clear or for which you would like to have more information given. And of course, the rest of the WDK documentation team is always eager to hear about any errors or omissions, through either of the feedback mechanisms given above. We really want to hear from you!