Using WDF in an NDIS driver

Can, Should, and How?

WDF is a framework that makes it easier to write Windows drivers.  NDIS is a framework for writing low-level Windows network drivers.  The purposes of these frameworks overlap a bit, and some people (okay, probably many people) are confused about the relationship between NDIS and WDF.  Today we’ll set down a few guidelines.  But first – let’s dispel one tenacious myth.

Myth: Some people think that NDIS drivers cannot use WDF.

In reality, you can use WDF in your NDIS driver.  I know this works rather well, because I have personally written several WDF-based NDIS drivers.

So where do people get the idea that WDF is incompatible with NDIS?  There are a few sources of this idea:

• When writing an NDIS miniport driver, certain parts of WDF are not compatible with NDIS.  You must put WDF into a mode sometimes referred to as “miniport mode”.  Not all WDF APIs are available in miniport mode.  See the step-by-step checklist here.  Note that this restriction only applies to NDIS miniport (and IM) drivers; protocols and LWFs can use the full breadth of WDF functionality.
• Miniport drivers must also put NDIS into a special mode, called NDIS-WDM mode.  This is a poor name, because it seems to indicate that you must use WDM.  The reality is that NDIS-WDM mode just means your driver can use any non-NDIS framework.  (At the time that NDIS-WDM mode was invented, there were no other frameworks besides WDM, so the name didn’t seem to be too constraining.  If it helps, you can think of it as NDIS-WD* mode.)
• Most of the NDIS drivers that are included with Windows (like TCPIP) don’t use WDF.  But this isn’t because Windows developers are avoiding WDF; it’s because most inbox drivers simply predate WDF.  If we were writing the network stack from scratch, we’d use more WDF.  New drivers like MSLLDP, an NDIS protocol driver included with Windows 8, are indeed based on WDF.

Now that we know you can combine WDF with NDIS, let’s talk about whether you should combine WDF with NDIS.  In nearly all cases, an NDIS driver will work with or without WDF.  So you rarely have the decision forced upon you by the technology.  Ultimately, it will come down to what you decide, based (hopefully) on a good engineering judgment call.  Let’s collect some evidence to help you make that decision.

Reasons you should use WDF in your NDIS driver

• Your engineering team is already familiar with WDF.
• You will be developing several drivers, including non-networking drivers.  (Might as well learn WDF now, and maybe you can share some library code between your drivers.)
• Your driver already uses WDF.
• You are writing an NDIS miniport that uses IRPs on its lower edge (USB, SDIO, etc.)
• You are writing a protocol or LWF that interacts with non-NDIS parts of the OS (usermode IOCTLs, WSK requests, etc.)
• Your code would benefit from WDF’s clever object management system to avoid memory leaks.
• You are new to Windows driver development, and have no idea where to start 😰

Generally speaking, it’s a good idea to consider WDF.  But there are a few reasons why WDF might not be very useful to your NDIS driver:

Reasons that WDF won’t help in your NDIS driver

• Your engineering team is already very familiar with NDIS, but has no experience with WDF.
• You are maintaining a mature driver that does not use WDF.
• You are writing a simple NDIS miniport on a directly-connected bus (like PCI).
• You are writing a protocol or LWF that has minimal interaction with the rest of the OS.  This driver mostly only calls NDIS APIs.
• Your codebase must be compatible with platforms where WDF is not available (like Windows CE).

Mind you, it’s still quite possible to link against WDF in these situations.  But you’ll probably find that there aren’t a lot of opportunities to actually use WDF APIs.  Integrating with WDF doesn’t give a lot of value if you don’t call its APIs.  In those cases, the pragmatic engineering decision may be to just not use WDF.

Okay, so let’s suppose you’ve decided to give WDF a spin.  You’ll eventually notice that WDF overlaps somewhat with NDIS.  For example, both frameworks have APIs for workitems (NdisQueueIoWorkItem versus WdfWorkItemEnqueue).  Which API should you use?  Again, in many cases, either framework’s APIs will work.  Again, it’s an engineering decision that ought to consider several factors, including maintaining consistency with your other code, etc.  But if you are new to NDIS and WDF, you can use this quick-reference table as a starting place for your decision-making process.

API family	Use NDIS APIs?	Use WDF APIs?	Use WDM APIs?
Work items	Avoid	Preferred	Do not use
Timers	Avoid	Preferred	Do not use
Memory allocation	Avoid	Preferred	Okay
Locks & interlocks	Avoid (but RW locks are okay)	Preferred	Preferred
Events	Avoid	Preferred	Preferred
String handling	Avoid	Preferred	Preferred
DMA	Preferred	Preferred	Avoid
Interrupts	Preferred	Not permitted	Not permitted
DPCs (for miniports)	Preferred for interrupts	Okay for non-interrupts	Avoid
DPCs (for non-miniports)	Avoid	Preferred	Avoid
Processor information	Avoid (except RSS APIs)	(no equivalent)	Preferred
IRPs and IOCTLs (for miniports)	Required	Not permitted	Not permitted
IRPs and IOCTLs (for non-miniports)	Avoid	Preferred	Avoid
Direct bus/port access	Okay	Preferred	Preferred
Reading configuration	Preferred for standard keywords	Preferred for other registry values	Okay for other registry values
File I/O	Avoid	(no equivalent)	Preferred

Remember, the above table only contains guidelines.  It is still acceptable to ship a driver that uses an API marked "Avoid".  You should use the table to help nudge your decision-making when you have no other compelling reasons to use a particular API family.