Introduction to the Kernel-Mode Driver Framework (KMDF)

As I have written in my previous posts, the Windows Driver Foundation (WDF) consists of the User-Mode Driver Framework or UMDF (which I introduced in my previous post) and the Kernel-Mode Driver Framework or KMDF. In this post I would like to provide some links that analyze KMDF. Everybody, who is not familiar with the basic kernel-mode concepts should take a look first at this introductory document.

First of all, I would like to repeat two of the main reasons that made WDM drivers difficult to implement:

• The driver developer needed to implement lots of functionality that had little to do with the device itself, but was more closely related to the windows internals. So, a big part of the driver code was totally unrelated to the core functionality of the driver.
• Specifically for Power Management and Plug and Play, most of the driver developers copy-pasted their code from the "Toaster" example that is in the WDK. This example is "advertised" by Microsoft to be the best well-written sample in the DDK, so everybody just re-uses the corresponding code unmodified. Therefore, most drivers have a common big blob of code, which is not altered by any driver developer.

Taking into account the above facts, Microsoft has decided to create a simpler model windows drivers. Most of the plug-n-play and power management code is now integrated in the kernel and the driver provides callbacks, which are called in predefined occasions. The driver developer needs to implement only the functionality that he needs (in contrast to WDM, in which the developer needed to implement everything regardless of whether it was needed or not), so the code becomes smaller and easier to maintain. This fact simplifies the code a lot, since there are no conversion between System and Device power-management-related I/O Request Packets, etc. For example, a sample PCI functional driver (PCIDrv.sys) was reduced from 13147 lines of code (in WDM) to 7271 lines (in KMDF). Also, a sample serial functional driver was reduced from 24000 lines (in WDM) to 17000 (in KMDF). The resulting state machine (which is shared both by UMDF and KMDF) is analyzed very well by Doron Holan in this channel9 video. Also, OSR has an inteview with Jake Oshins (need to register for free), who is the chief designer for WDF Plug and Play and Power Management. The document that analyzes there changes more extensively can be found here.

In contrast to UMDF, KMDF doesn't pose any limitations for the driver developer. That's why practically all driver categories that were developed using WDM can also be developed using KMDF. Also, after you understand how to map some concepts from WDM to WDF, it's relatively simple to port the driver. For example, the IRPs are now wrapped inside Request Objects, which can be delivered to Power-Managed queues or non Power-Managed queues. The difference between these two is that the I/O manager stops sending Request Objects to a Power-Managed queue, while the Device is not totally ON (power state D0), while this is not true for a non-Power-Managed queue.

Actually, the KMDF team has done a lot of work in presenting the porting procedure, so you can find lots of information in their videos (part 1 and part 2), their WDM-to-KMDF porting guide and the corresponding presentation. Also, for those interested in learning how to write a KMDF driver, but are not aware of WDM, the KMDF team has created the presentation on how to develop a KMDF driver (part 1), which is followed by the follow-up video that corresponds to part 2. All this information can be found at the KMDF website. Apart from the above, there are also some more advanced documentation, like the DMA support (currently UMDF doesn't support DMA, since it also doesn't support direct hardware access) and the I/O request flow.

Apart from the above, currently the most up-to-date and in-depth information about KMDF can be found in the Windows Driver Kit (WDK). Try using Internet Explorer to access the previous link. There you'll find all sorts of information that span from the driver structure to the internal architecture.

After reading all the above theoritical information, it's time to continue with some actual driver development. So, first of all you need to download KMDF. Afterwards, you should try to look at some existing tutorials:

• From OSR:
  • A software-only driver
  • A basic filter driver
  • A driver for a 24-channel digital I/O PCI card
• From codeproject:
  • A basic driver
  • A USB driver for OSR's USB FX2
• From Microsoft
  • KMDF Sample drivers

You can also find supplemental information on how to build, install, test and debug a driver here, while a list of KMDF extensions for the debugger (windbg and kd) can be found here.

Last, but definately not least, a very valuable resource is Doron Holan's blog. There you will find lots of tips and information not only about KMDF drivers, but also about kernel programming in general.

Unfortunately, currently there is no published book for KMDF (nor for UMDF or WDF in general), however there is one public announcement about one: Introduction to the Windows Driver Foundatation - Kernel Mode Driver Framework by Peter Viscarola, Tony Mason, Mark Cariddi, Brenda Ryan, Scott Noone, and OSR.