My travels with WDF

Where have you been?!

2012-10-15T21:24:53Z

Well, as you could probably guess, I haven't had much to say for a while for a couple of reasons - first and foremost, the Windows 8 product cycle was really intense. A lot of changes under the hood came down the pipe, so with the big additions to WDF (UMDF especially) we really had a ton of work to do! Secondly I really couldn't talk about a lot of what was coming and a lot of the issues I would like to have made topics about I couldn't. :)

But thanks to everybody who provided feedback on the WDK integration with Visual Studio! I hope those changes that did get in helped, and I know they'll be looking at those other suggestions going forward. And a big thank you to all who emailed me asking questions. Hopefully we got your drivers up and running and we look forward to having more driver writers moving over to UMDF, especially now that it supports hardware interrupts!

The last thing for today is - with some sadness, I'm leaving the WDF team and moving over to the Hardware Certification Kits team! It's a big change for me actually. I've worked with kernel mode device drivers and technologies since Windows 98 (USB,1394 then to WDF), only venturing outside of kernel mode to write tests cases and 99.99999...% of those were in C/C++. So this move is actually really exciting as I'll be "forced" to write more using "modern" languages. :)

Not that the blog has been really active for a while for the aforementioned reasons, but I have been getting questions and requests for help during that downtime, so I'm really happy that I (we) were able to provide some help to you guys that you might not have been able to get elsewhere! And the biggest impact I think we had (you and I) was there were bugs that we found in the Frameworks along the way and we were able to fix those for UMDF 1.11!

Thanks everybody! And keep writing those drivers!

-patrick

You’ve had the time, let’s hear the feedback.

2011-12-02T19:40:57Z

I hope those of you who are using the new Visual Studio 2011 with the WDK integration are having some fun, even if it’s just been wandering around and playing. What, if anything, are you not liking about it? Anything that’s unintuitive or confusing? What do you like about it, but would like to maybe see tweaked?

Now that I finally have my VS 2010 plug-ins to fixed to work with VS 2011 (real subtle changes as all these two plug-ins are wholly internal tools) and have been using it exclusively for the last few weeks. In particular, how have the KMDF / UMDF templates been working out?

So, either use the “send feedback” option or leave a comment – I’ll post them so long as you’re not screaming at me *g*. I have got direct line of access to the team(s) involved in these projects, so your feedback won’t go off in to the vapor. :)

Now listening to: Caravan by Rush

Well, you can kind of see why we’ve been quiet around here…

2011-09-15T17:12:00Z

If you’re watching what’s going on at //BUILD (and why wouldn’t you be?), you may have seen that UMDF now supports hardware access (via ports and registers) and interrupt handling! If you haven’t seen it, you can go read more here.

And the other big one. Something I’ve been begging to get done for years and believe me in all my years at Microsoft it’s been one of, if not the most, commonly requested thing I’ve heard at all the WinHECs, Developer Conferences, Trade Association meetings, etc from you guys. – Visual Studio integration of the WDK. Even down to templates for UMDF and KMDF drivers! You know what that means, native Intellisense (not that we haven’t figured out how to do that already), but more importantly, the one thing I couldn’t give you (partly because I couldn’t get the plug in to work across all VS editions) integrated WDK build support. :D

There are still a couple of other very cool things in the UMDF / KMDF space we’ll get to start talking about pretty soon, and for sure I’ll start digging more in to these two as we move closer to the Windows 8 / WDF 1.11 release timeline.

So the blog will be spooling back up with some fun posts in the coming months.

Let me know if you have any questions or comments!

-p

The sounds of silence.

2011-06-17T18:48:34Z

Greetings one and all (who may be only one left reading at this point *g*). Some cool things are happening here which is why I’ve been heads down working. And I can’t tell you about them just yet – pretty soon though.. But one of the cool things I can tell you about, if you haven’t seen it already - the Kinect SDK has been released. And I’m very proud to say – it’s using a KMDF driver.

In addition to that we’ve seen an increase of new WDF based drivers coming from some of you readers. A few I have helped get their drivers up and running, and others my teammates have been helping. It’s so nice to see the adoption rates really starting to pick up! I know refactoring / writing new drivers is a hard sell to some companies, but when the upside is that increased stability and reduction in support costs, it makes that sell a lot easier.

We’ll be churning up the blog posts again, so stay tuned for more tidbits and tales from the driver side.

Thanks again everybody – and keep firing questions my way.

The WDF book is back in print…

2011-01-05T23:40:59Z

http://www.amazon.com/Developing-Drivers-Windows-Foundation-Developer/dp/0735623740/ref=sr_1_1?ie=UTF8&s=books&qid=1294270728&sr=8-1

http://oreilly.com/catalog/9780735623743/

We now return you to your normally scheduled programming.

Hope you all had a great holiday season and safe New Years!

How active are you?

2010-10-07T17:59:00Z

Was pondering a few questions the last few days.

How many of you UMDF writers use ATL in your drivers?
If you do, do you have more of a kernel driver background or a user mode background?

Since UMDF works on an object model very similar to COM, the ATL does provide a lot of useful object lifetime management functions and interface implementation (BEGIN_COM_MAP / COM_INTERFACE_ENTRY).

Like I said, just some curious questions for the group. Post comments or send me an email if you feel like chiming in. I’m thinking if enough people are interested in using ATL, I could do a series of how to migrate non-ATL drivers to ATL drivers.

Currently playing: nothing

Because inquiring minds want to know

2010-09-10T17:22:25Z

A follow up question was posed from my last post about the WDF book no longer being in print and I thought it would be better to do a post so it will show up in RSS feeds;

Q: Any idea what triggered this? I realize that our technology area doesn't sell as much as others, but seems strange to pull the only book on the topic.

Inquiring minds...

-scott

A: We’re digging around to find an answer for you all. The digital versions are still available though so all hope is not lost.

Heads up!

2010-08-26T18:14:05Z

Sharing a cross post that is of interest to you WDF users;

http://blogs.msdn.com/b/doronh/archive/2010/08/25/developing-drivers-with-the-windows-174-driver-foundation-i-e-the-wdf-book-is-apparently-out-of-print.aspx?wa=wsignin1.0

Time keeps on slippin’

2010-08-03T21:15:48Z

Greetings one and all! Been heads down on some work around here and haven’t been able to post an update in a while.

A couple of real good case studies have come up recently with regards to driver stability and effective testing of those drivers. So I want to call out some processes we’ve been presenting in our talks and slide decks to you folks for a while, but they are things we do internally as well.

One of the things we are always using in office and test labs are the Object Tracking and Reference History tracking features in UMDF. Cleaning up and maintaining proper lifetime scope of UMDF objects is a real must. Plus we like to make sure the documentation for those DDIs and objects calls out that you need to release a reference once you’ve finished using the object. And we really like to have those trackers on when running negative path testing. Hitting functional code blocks is nice, but we also want to make sure we’re hitting those negative cases as hard, and ideally, harder. It’s never what you expect to work that kills your driver’s resource management. ;)

One easy way to get that extra coverage for negative path testing is to use Application Verifier with its fault injection engine running. I’ve been able to find quite a few fun bugs in code using that little trick. Another bonus you get from Application Verifier is the object leak mechanisms. We’ve all been prone to forgetting to delete objects (mostly handles *g*) and having these caught at incident time makes them easier to track down and in the end, that makes everybody happier.

I know there are some good questions out there, so please feel free to speak up! I love hearing from you all with good case studies or blog fodder.

Now Playing – Charlie Parker Easy to Love

A funny thing happened on the way to the keyboard

2010-05-28T19:04:19Z

So as I was crafting some UMDF HID driver code for your consumption, and I was working with one of you (and you know who you are *g*) during some of that time frame, we sort of discovered everything already exists between my earlier blog posts and some of the WDK samples. So rather than reinvent the wheel and the internal combustion engine, let’s just dump all that information in a blog post.

First up, I touched upon secure HID stacks and how to get your UMDF HID Collection Filter driver working in them and a little on how to use impersonation. And in retrospect, the 30 second and little technical extension in that post are really all that was / is required for getting a basic driver up and running. Make a note that not all HID stacks require secure connection, so you kind of have to do some debugging or digging around to determine those requirements for your own driver. Sorry. :)

The second part was to alleviate the issues with Windows session spaces in order to access some Win32 desktop APIs. As one of the driving forces to craft a HID Collection filter in UMDF is to have access to those APIs, that session work around is vital.

The last part is proper implementation required for a secure HID stack is using IImpersonateCallback::OnImpersonate method and its invocation from the IWDFIoRequest::Impersonate method. Turns out one of the existing samples available in the WDK has a really good implementation; src\usb\osrusbfx2\umdf\fx2_driver\impersonation\

Put all that together and you can easily craft a HID collection filter driver for the majority of HID devices. Remember though, UMDF cannot be used to filter keyboard and mouse collections. But you can go crazy writing drivers for a load of other HID devices.

As always, feel free to ask me questions if you run in to any road blocks.

Now Playing – Rush Show Don’t Tell

0 and 1 are not just numbers, they’re spaces!

2010-03-31T22:33:31Z

Again, thanks to our intrepid explorer Ilia S. for helping uncover some more traps in the UMDF HID Collection Filter journey.

Two things to keep in mind as you’re creating your driver:

1. UMDF drivers are hosted in a Session 0 based executable on Vista and above -

- and -

2. A lot of Win32 APIs for controlling desktop and user interactions on the desktop are exclusive to user sessions (anything 1 and above) because Session 0 technically doesn’t have a desktop and is intended to be a protected space.

So those of you who are wanting / trying to get HID Collection Filter drivers running in UMDF so you can do some magic on the desktop, you will need to do some of the following:

A Session 0 overview for you with some tips, hints and tricks on how to “exit out” to user desktop sessions.

http://msdn.microsoft.com/en-us/library/bb756986.aspx

But focus more on this portion;

Leverage Windows 7, Windows Vista and Windows Server 2008 capability:

Use client or server mechanisms such as remote procedure call (RPC) or named pipes to communicate between services and applications.
Use the WTSSendMessage function to create a simple message box on the user’s desktop. This allows the service to give the user a notification and request a simple response.
For more complex UI, use the CreateProcessAsUser function to create a process in the user's session.
Explicitly choose either the Local\ or Global\ namespace for any named objects, such as events or mapped memory that the service makes available.

And a good tutorial on how to make an application using those patterns (this does require the Platform SDK)

http://msdn.microsoft.com/en-us/library/aa379010(VS.85).aspx

And finally for today, I am still working on getting you some sample code for a UMDF HID Collection Filter driver, but life decided it needed some attention last week so I’m a tad behind on that. :)

And a thank you to one of our developers, Kumar for pointing me to those Session 0 links and tips!

Now playing – Transatlantic The Whirlwind (yes, I do love my prog rock)

How to avoid getting a HID to the head (a guide to making a UMDF - HID collection filter)

2010-03-24T17:38:00Z

First of all, HUGE thanks to Ilia S. for helping to track down this little trap. I’m glad we finally got your driver up and running! Nothing like having an 8 hour time difference to slow things down. :)

For those of you who like the 30 second version;

If you need to use Impersonation in a UMDF driver, regardless of being a filter or a function driver, you cannot have AutoForwardCreateCleanupClose set to WdfTrue. For filter drivers this means you must invoke AutoForwardCreateCleanupClose with WdfFalse AFTER you call SetFilter and BEFORE you call CreateDevice and then follow all the rules for balancing Create and Close and handling Impersonation (same link as above for impersonation). Easy enough? :)

For those of you who like long winded technical posts, I am going to do a write up on how to get a UMDF driver to sit on top of a HID collection.

And for those of you who like to work ahead and start digging around on your own, you first need to match your INF section for HWID to HID\VID_<nnnn>&PID_<nnnn>&XX_xx&&ColNN. Second install WUDFRd as an upper filter to that HWID. Now, if your collection has enforced secure read, you’re going to need that little tip above.

I’ll work on getting the first part of the write up done this week and posted by early next week. I need to do a little code work on a sample for you faithful readers. *thumbs up*

As always, fire off any questions you have!

Now Playing – Stone Temple Pilots Trippin’ on a hole in a paper heart

It’s time to party!

2010-03-03T00:20:17Z

Fresh from the oven, Windows Driver Kit (WDK) 7.1.0 is ready for your consumption!

You can get it from the Download Center;

http://www.microsoft.com/downloads/en/results.aspx?freetext=WDK&displaylang=en&stype=s_basic

Or off Microsoft Connect (remember, you have to be signed in to your connect account).

https://connect.microsoft.com/site148

Now, go forth and code!

It’s a bird, it’s a plane..

2010-02-16T19:36:24Z

Just wanted to make sure you all saw this great guest post on Doron’s blog from Jake Oshins.

http://blogs.msdn.com/doronh/archive/2010/02/02/what-is-irql.aspx

That’s all for today.

Housekeeping

2010-01-21T20:39:40Z

There have been a couple of asks recently, in various forums, on how to build drivers using Visual Studio. I thought since I had shown you how to make better use of Visual Studio as an IDE for driver writing, I better share the last yard of how people are integrating the WDK build environment(s) in to Visual Studio.

For those of you who don’t already know about or already use them, there are two commonly used tools to integrate the WDK build environment in to Visual Studio. Please note that these are not Microsoft supported solutions by any means and any support questions should be directed towards the tool owners, not me. I don’t use these tools internally. I have some other voodoo that I use. :)

http://www.osronline.com/article.cfm?article=43

http://www.hollistech.com/resources.htm

Speaking of Visual Studio, I’ve been using VS 2010 for the last few weeks and there is one SWEET addition I have to share with the group (again, some of you probably know about it already) -

You can undock source tabs and float them across your desktop(s)!

That makes for a happy Patrick when I can span code modules across my two 24” monitors all from one IDE. *g* All of that awesomeness goes along with some nice performance increases in the IDE and the pretty new blue UI. I’m sure there’s some other big ticket stuff the Visual Studio Team is just as jazzed about with 2010 edition. ;)

But don’t just take my word for it, go give it a spin for yourself;

http://msdn.microsoft.com/en-us/vstudio/dd582936.aspx

Now Playing – Transatlantic My New World

It’s okay to assert yourself, just be careful how forcefully you do it. (Op. Ed.)

2010-01-12T23:39:00Z

We recently had a good discussion internally about the nature of ASSERTs in code. I, being the rebel that I am, took the time honored stance of, “if you’ve hit it, you’ve triaged it and changed to code to handle that condition gracefully (at least as gracefully as possible), it’s safe to remove that assert.” The other camp had a few different views, but the basis of their retort was, “just because you hit it, doesn’t mean that you’ve covered all scenarios in which that particular condition can be triggered, and removing it lessens the ability to catch those scenarios”. Which is a very valid argument as well, but my problem with that stance starts simply at the entry. The scope of an ASSERT should be as narrow as possible, ASSERTs should not be there to validate that each caller does not trigger that particular condition. If the changes made to handle the condition gracefully cause that calling function to fail, or misbehave in some other fashion, it’s up to them to fix their code. If it happens to be another block of your code, c’est la vie.

I’ve been there, as I’m sure all of you have as well. But my point being, the removal of an ASSERT should only happen if that condition is now handled AND that condition has been; invoked, triaged and understood. And hopefully all of the aforementioned comes from a well defined test case triggering the ASSERT. Here again, the counter-argument provided, “the retention of the ASSERT provides another layer to protect against regressions in the callers as the immediacy of the regression is felt when the ASSERT is triggered.” I would simply contest that by saying, the test is just as immediate of a regression trap, and will also be caught under both FRE and CHK builds. Sure there is a chance that the nature of the test case will change where it will cease to act as a valid regression test, but the onus should be on the owner of the tests to ensure that any changes made does not remove or redefine those test cases.

Both sides of the debate sound reasonable no matter what your preference for using ASSERTs. And I’d agree with you 50% of the time on either side. :)

Now, there are two extra data points that may or may not sway you to either side of this discussion and these lend themselves to reaffirming that there is something to break every rule;

The tests triggering these ASSERTs are run as part of an automated test pass and as such, will trigger this ASSERT 100% of the time. Yup, there’s a debug break provided for us every time we run the test under a CHK build environment. That’s kind of contrary to automation. :)
The test triggering this ASSERT is part of a super secret set of tests that actually replaces an inbox binary with a private version in order to provide an additional attack surface to a second target binary. So in this case, the reality is simple – should this ASSERT be triggered “in the wild” it would represent a valid bug in the primary component which is being replaced at test time. And thus we are presented a valid case where by the ASSERT in the underlying target component can provide a safety net against real regression and real bugs in the primary component.

Why am I bringing this all up? Well primarily, I haven’t blogged in a while (*g*). But it was a good go around amongst us and it also opened up some more possibilities for test tools and test cases through this discussion. So even though the two sides of this debate agreed to disagree, the end result is that we’ve identified more areas to improve existing tests and toolsets to allow developers the means to choose what they feel is best for the product and not block test automation in the process.

See, there is no such thing as a “failed experiment” in science. ;)

Now Playing – Jonathan Coulton Skullcrusher Mountain

And here you thought I had a cloaking device

2009-12-01T23:48:00Z

Got a good one to share with the group;

Q: Can I make a kernel mode driver that opens a handle and talks to a UMDF based driver in another device stack?

A: Why yes you can! Quite simply done provide you follow all the rules. This is a variant of the UMDF initiated cross stack communication we talked about a while ago, but KMDF, being a DF (driver framework) supports essentially the same IoTarget model that UMDF does.

Now Playing – Rush Far Cry

We’re gonna need a bigger stick!

2009-10-06T23:42:17Z

So, some of you may recognize Eliyas’ name from WinHECs and various other driver dev presentations, but guess what he’s done now?! He’s become a blogger.

Go on feel free to hound him about your USB driver problems. :)

I/O Queues and You

2009-08-24T21:48:00Z

I got an interesting question via mail recently, “Do I really need to create a queue object in my UMDF driver?” Well, this is another one of those, “only if” type questions.

For instance - Only if your driver is not handling any I/O from a top edge method which results in the I/O manager being involved in talking to the UMDF driver for those operations. At that point you don’t need to create a queue object.

Example -

The UMDF driver wants to send I/O to a KM driver in another stack based on some form of simple event being raised and consumed by the UMDF device. Provided you have a handle open to that KM stack and have created the I/O target object (all shown here) you can simply create and format a request, and then send that request to the target.

Should you want to send requests asynchronously and need a completion callback, you can still do so with out requiring a queue. The driver will have to implement a IRequestCallbackRequestCompletion::OnCompletion method. And during the packing of the request to submit, invoke the request’s SetCompletionCallback prior to invoking the FormatRequestxxx method.

Once the lower driver has completed the request, the OnCompletion method will be invoked. Voilà.

There’s one little caveat around UMDF completion routines that I talked about a while ago and I should bring it up here; you can only define one OnCompetion method per device object.

Cross stack communications

2009-08-16T23:57:00Z

The subject of how to talk to another device stack has come up again, and since I only briefly touched on it a year ago, I thought it would be good provide some code snippets and a little more background on how to accomplish such a feat. The gist of what we are trying to do here is load a UMDF based driver for one device, open a handle to a different device stack and submit I/O to that stack. To do that in UMDF we need to establish a UMDF I/O target and the foundation of that I/O target object is a file handle.

So the basic building blocks are as follows;

    //
    // Add these to your base class
    //
    IWDFIoTarget m_ExternalTarget;
    HANDLE m_ExternalHandle;

You can add these to any of your existing classes, but it probably serves best to house these elements in your Device or Queue classes. They are tied to the lifetime of the I/O you are sending to the external target, so where you house them is really down to your design and implementation.

Based on your needs and how you design your driver, you will need to determine when you proceed with the following sections. For simplicity, I’ll establish the connection to the remote stack in the Device Initialization routine, but the same can be done at just about any other point of initialization or even during a later phase of driver operations.

    IWDFFileHandleTargetFactory * pFileHandleTargetFactory = NULL;

   // .......
   // abstracted device init code for brevity
   // ........

    if (SUCCEEDED (hr)) 
    {
        m_FxDevice = fxDevice;

        //
        // We can release the reference as the lifespan is tied to the 
        // framework object.
        //
        fxDevice->Release();
    }

    // Open the device and get the handle.

    m_ExternalHandle = CreateFile (
        DeviceStack,  // path device stack to open
        GENERIC_READ | GENERIC_WRITE, // these flags are driven more by the target stack.
        FILE_SHARE_READ | FILE_SHARE_WRITE, 
        NULL,         
        OPEN_EXISTING,
        FILE_FLAG_OVERLAPPED, // You must open the handle with this flag
        NULL);        



    if (INVALID_HANDLE_VALUE == m_ExternalHandle) 
    {
        DWORD err = GetLastError();

        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "%!FUNC! Cannot open handle to device %!winerr!",
            err);

        hr = HRESULT_FROM_WIN32(err);
    }

    if (SUCCEEDED(hr)) 
    {
        hr = m_FxDevice->QueryInterface(IID_PPV_ARGS(&pFileHandleTargetFactory));

        if (FAILED(hr))
        {
            TraceEvents(
                TRACE_LEVEL_ERROR, 
                TEST_TRACE_DEVICE, 
                L"ERROR: Unable to obtain target factory for creating FileHandle based I/O target %!hresult!",
                hr);
        }
    }

    if (SUCCEEDED(hr)) 
    {
        hr = pFileHandleTargetFactory->CreateFileHandleTarget(m_ExternalHandle, &m_ExternalTarget);
    }

You’ll need to release the reference to the pFileHandleTargetFactory object, either by a SAFE_RELEASE macro, direct call to the Release(); method, or by using a CComPtr /CComQIPtr class wrapper on the object on declaration. You’ll also need to clean up the Windows file handle when it is no longer needed. And IF the IWDFIoTarget object's lifetime scope is narrower than the device object's lifetime, you will need to call DeleteWdfObject method on m_ExternalTarget.

At this point, you have your remote target object to use in sending I/O to that secondary device stack.

What I’ll cover next is going to be some hefty theory on when you should and don’t need to use queue objects and how to send I/O to an external stack based on whether you have a queue or not. Fun! ;)

House cleaning

2009-06-30T22:13:49Z

The fourth part of Abhishek’s online UMDF debugging tutorials is up now. :)

http://www.microsoft.com/whdc/devtools/debugging/umdftraining.mspx

Next up, those of you playing with Windows 7 may have noticed that the “Found New Hardware” wizard is gone! This in itself is not that big a deal, but it does mean that some of the WDK sample installation instructions are no longer valid.

Simple fix at the end of the day, the device will come up as an “Unknown Device” within Device Manager, choose “Update Driver” from the right click context menu for that device and then follow the directions to point it to the driver(s) you need!

That’s all for today, those of you in the U.S. enjoy your 4th of July weekend. And just remember, light fuse then run away.

*Currently Playing - Dream Theater Light Fuse and Get Away

Intellisense, the Musical part 3

2009-06-04T08:47:00Z

Like all good stories, sometimes the 2nd act is the hardest to follow. In this case it was simply a matter of other things coming up rather than writers block. :)

What kicked me in the rump to get this next part up was a few more questions about driver writing, WDK integration into Visual Studio and Intellisense. One of the very cool features of Visual Studio 2008 is the ability to make a project from existing code.

The end result can look something like this (warning, this is a 1920x1200 resolution PNG *g*)

I’ll walk you through this using the “a picture is worth a thousand words” mentality;

Select “Next”

Then point it to the root of the WDK installation. Pointing it to the root rather than right at the src folder will save you some intellsense headaches later on, sure you’ll get inclusion of all the WDK folders, but it’s actually not a bad thing in the end;

Select “Next”

Then;

Select “Finish” from here. We’re still not going to use Visual Studio to do any building for now, partly because I refuse to give up all command windows in my life and also because I’m still tinkering with all the settings required to use the WDK build environments under Visual Studio.

Now your Solution Explorer will probably look like a mess of files listed alphabetically. Simply hover over the “Show All Files” button at the top and toggle it until you get an Explorer like layout of the samples sources structure.

Now you have pointer to the first picture in the blog post. :)

As a side note to any Microsoft Employees who may actually read my blog – Yes, you can do the same thing with our Source Control Enlistments (I have a VS project for each branch I work out of). And if you have one of the Source Control plugs in for Visual Studio, you can also have all the check in / check out / history that our source control provides.

UMDF Debugging talks online

2009-05-06T23:01:38Z

Our wondrous Abhishek did a series of Debugging UMDF driver talks and I’m happy to say we now have the first three live on line!

In these he covers some of the basics; where to find and how to use WDFVerifier, how to use some of the UMDF Debugger extensions and some basic debugging UMDF scenarios.

http://www.microsoft.com/whdc/devtools/debugging/umdftraining.mspx

As always, any feedback or questions you guys may have, feel free to ping me!

Double filtered for added UMDF flavor.

2009-04-27T20:54:00Z

UPDATED: 9-March-2010 Astute readers noted that I had the incorrect driver load order when talking about the UmdfServiceOrder directive. :) It IS left to right reading and the LEFT most driver is the lowest driver.

In my previous post about Filter Drivers, I mentioned that this time I would focus on a more UMDF centric stack. This one is pretty simple.

For UMDF only based driver stacks, the single most important directive is the UmdfServiceOrder INF directvie. As I mentioned last post, that directive is a left to right list determining load order for the drivers contained in the device stack. With the left most element in that list being the the lowest driver loaded.

Here are two examples – First a UMDF two driver stack with an upper filter;

[<mydriver>_Install.NT.Wdf]
UmdfService=UMDFFunction,WUDFFuncDriver_Install
UmdfService=UMDFFilter,UMDFFilter_Install
UmdfServiceOrder=UMDFFilter, UMDFFunction

Now to install a lower filter, simply flip the order in that directive;

[<mydriver>_Install.NT.Wdf]
UmdfService=UMDFFunction,WUDFFuncDriver_Install
UmdfService=UMDFFilter,UMDFFilter_Install
UmdfServiceOrder=UMDFFunction, UMDFFilter

The last tidbits here are; for a device stack that only contains UMDF drivers, there is no need to add any of these settings in the INF;

[<mydriver>_Device_AddReg]
; Load the redirector as an upperfilter on this specific device.
; 0x00010008 - FLG_ADDREG_TYPE_MULTI_SZ | FLG_ADDREG_APPEND
HKR,,"UpperFilters",0x00010008,"WUDFRd"

And also as before, the filter driver needs to be a good citizen on the stack, pass on requests it does not own to the next driver and don’t touch anything unless you must. The previous code samples I’ve posted all still apply, but the basics are; GetDefaultIoTarget, FormatUsingCurrentType and Send.

There’s no need to change any code for a basic filter driver based on its load order (upper or lower filter). As you get in to more advanced driver functionality you may find a need to change default behaviors. For those cases, you can always send us mail. :)

There was also some questions about why would you want or need to be an upper or lower filter driver. That one gets in to a bit more of a “it’s up to you” but the core logic that applies to WDM / KMDF drivers applies to UMDF drivers (save the parts about bus drivers *g*).

Genuine UMDF filtered drivers

2009-04-16T03:30:00Z

Filter drivers have come up in conversations recently (both internal and external), so I wanted to take some time here to address some of the issues that were brought up with regards to UMDF filter drivers and how to make them. Note: I’m not going to cover all the configuration dynamics available for UMDF filter drivers in this one post simply to avoid the risk information overload and clutter, so expect a couple of posts on this subject.

Let’s start with some basics, we’ll simply demonstrate how to configure and load a UMDF Filter as an upper filter driver to a kernel mode driver (KMDF or WDM) in the same INF-

As some of you may remember from my earlier posts, a UMDF filter driver should use the SetFilter(); property in the DeviceInitialization routine. This tells the Framework to do a couple of things for us automatically:

Send I/O for which the Filter has not registered a callback for to the next logical driver in the stack. Example: Your filter driver registers a DeviceIoctl callback method, but not read or write. As a result your filter driver will only see IOCTLs
Automatically forward file create cleanup and close so there is no need to invoke the AutoForwardCreateCleanupClose method.

That covers the really basic code required at driver / device initialization time. Now we need to add the pertinent sections to the INF file. As we’re going to focus on being an upper filter for this example, you need to make the following modifications to your INF (in addition to the normal UMDF specific sections);

[<mydriver>.NT.Wdf]
UmdfService = "<mydriver>", <mydriver>_Install
UmdfServiceOrder = <mydriver>

[<mydriver>_Device_AddReg]
; Load the redirector as an upperfilter on this specific device.
; 0x00010008 - FLG_ADDREG_TYPE_MULTI_SZ | FLG_ADDREG_APPEND
HKR,,"UpperFilters",0x00010008,"WUDFRd"

So a couple of things to note here -

One is the UmdfServiceOrder directive, this is load order specific. I’ll address a more UMDF centric stack in the next post, but for those of you who like to work ahead, this is a left to right reading list to determine stack order.

Second thing is the registry key addition section. As WUDFRd is the kernel mode transport service for UMDF drivers, WUDFRd is the upper level filter driver to a kernel mode driver.

Now that your driver is loaded as an upper filter, what should your driver do in order to be a good citizen in the stack? Short answer is, as little as possible. You perform the same steps for handling PnP and Power as you would for any basic UMDF driver (one that lets the framework handle the heavy lifting for those two). You register your I/O callback routines and build your queues just like any normal UMDF driver, the only additional requirement here is to forward I/O requests as required.

For this example, let’s just demonstrate using a fairly simple pass through driver. How you actually implement this is up to you, but the basic requirements here are - as your driver receives the request on the queue, it needs to pas pass it on to the next driver in the stack. So first you need to get the default I/O target (next driver in the stack). Next, format the request using the same type and then finally, send the request. A condensed version would be something along these lines;

    IWDFIoTarget * kmdfIoTarget = NULL;
    
    this->GetFxDevice()->GetDefaultIoTarget (&kmdfIoTarget);

    Request->FormatUsingCurrentType();

    hr = Request->Send (
        kmdfIoTarget, 
        0,  // 0 Submits Asynchronous else use WDF_REQUEST_SEND_OPTION_SYNCHRONOUS
        0);

I also have some more basic code here for you to peruse.

So now we have a basic UMDF upper filter driver on top of a kernel mode driver.

Now Playing Capitals v. Rangers