Page 6
www.osr.com
The NT Insider Sept - Oct 2017 © OSR Open Systems Resources, Inc.
M
ost of the WDF topics I write about suggest themselves to me as a result of a set of exchanges on our NTDEV list, or as a
result of trends I see in driver code that I review or update. This me, I was inspired by both of these.
There was a recent, and reasonably interesng, thread on NTDEV about the use of Cleanup and Cancel Event Processing Callbacks.
Also recently, I had the opportunity to update two very dierent device drivers. One was a WDM driver that was wrien in the NT
V4 meframe. The other was a KMDF driver wrien by a new Windows driver developer shortly aer the release of KMDF. While
these two drivers were for very dierent types of devices, they had one thing in common: The developers of both misunderstood
how to terminate in-progress Requests and used (or, rather, misused) Cleanup events in place of Cancel.
That’s how I came to be movated to write at length about Cleanup, Close, and Cancel handling in WDF drivers. An addional,
private, movaon is that while we cover this topic in our Wring WDF Drivers seminar, we almost never have the me to talk
about it in the level of depth that I’d prefer. So, I gured an arcle would be useful for many purposes.
Some Preliminaries
The rst thing to understand is that, at least in the driver world (as opposed to the le systems), you need to consider processing
for Cleanup, Close, and Cancel together. This is because they’re oen confused and processing for these funcons oen interact.
Also, as we begin our discussion, please keep in mind that what we say here about Cleanup, Close, and Cancel is enrely specic to
WDF. As in most things WDF, it is never a good idea to aempt to “map” from WDM to WDF (or vice-versa) in your head and
expect to be able to gure things out. That way madness lies. The WDF Framework is its own I/O processing ecosystem. Sure, it
interacts with WDM, but the rules for how WDF drivers work are established solely and enrely by WDF. Just because something
works a certain way in WDM is no reason to believe the same is true for WDF.
The Problem
Let’s start with a couple of simple examples of the problems that Cleanup, Close, and Cancel are designed to solve. I want to
emphasize that these are just two random examples in which these operaons can be useful. There are lots of other important
uses for Cleanup, Close, and Cancel events that these two examples don’t address.
Assume your driver has a single Queue that uses Sequenal Dispatching. A user-mode applicaon successfully calls the Win32
funcon CreateFile specifying FILE_FLAG_OVERLAPPED to allow it to do asynchronous I/O. The app then successfully calls ReadFile
100 mes from within a loop, specifying an OVERLAPPED structure each me. The result is that when the applicaon’s loop is
complete, there are 100 Read Requests pending in your driver.
Now let’s say that applicaon calls CloseHandle on the handle it used to send those 100 reads to your device. At least some of
those 100 reads are sll in progress. What happens to the in-progress I/O Requests? How does your driver handle this situaon?
As a second example, consider what happens when instead of closing the handle to your device when those 100 reads are in
progress, the applicaon exits or is terminated. As Windows begins terminaon processing for the app, your driver potenally has
a pointer to one or more data buers into
which to return data into the applicaon’s
address space. You can see this in Figure 1.
In Figure 1, you can see a driver with a single
WDFQUEUE that has two Read Requests
queued (I didn’t want to put all 100 I/O
Requests in the diagram). Each Read Request
has (stored internally) a pointer to the data
buer into which the Read (output) data is to
be returned.
If Windows were to allow the Process to
terminate completely with I/O requests in
(CONTINUED ON PAGE 7)