WdfVerifier Basics- Managing Verifier Settings for one or more KMDF drivers
In this article, I'll cover the basic things you need to do to use the new WdfVerifier tool to easily work with KMDF verifier, and let the enhanced verification features of KMDF help you to create a more solid driver.
Step 1: Install your driver
You should do this on a machine where you are ready to do kernel debugging. If the device fails to function after the installation, that's OK- you can still use WdfVerifier to help you debug the situation as long as the driver installation (and any KMDF installation needed as a part of that) was successful.
If you have trouble getting your driver to install, and little success in getting it to work, this article from Doron Holan's blog may help you get started. The driver development newsgroups on MSDN may also be able to help, and osronline.com's NTDEV mailing list also has helpful and knowledgeable people. If none of that works, you can use our email feedback alias, or contact me directly through this blog.. I used to try to help every case- unfortunately, as the number of people adopting rises, there's not enough of our team to individually help every one, and since others have been there and can share their experiences with you through those means, it would be better to work through that list in the order presented...
Since this is in a Beta WDK, does that mean it only works on WDF 1.7?
NO! WdfVerifier will work with any KMDF or UMDF version we have shipped to date. By all means use it on any existing driver. This tool is meant to help you TODAY.
Step 2: Run WdfVerifier directed at the target machine
What I mean here is that you have two choices:
- You can go to your copy of the WDK and copy the platform-specific version of WdfVerifier.Exe to the machine your driver is on, OR
- You can run it from the machine on which the WDK is installed if you have administrative privileges on the test machine by adding the "-machine MachineName" switch to the command line when you invoke it.
I like the second option, but it does have some limitations:
- You may need to work through some firewall and security issues to enjoy the full function. I will cover these more fully in a future article.
- If you did not invoke the KMDF coinstaller to install each individual driver service (including filters), you will not see all of them.
The second is mitigated slightly if you run WdfVerifier the first way even once after installing the drivers. The problem is that for performance, WdfVerifier looks for some registry keys the coinstaller will create when it installs a KMDF driver, and if it finds them, it assumes that a given KM driver service uses KMDF. Since not all drivers use the coinstaller, when you run WdfVerifier on the machine with the drivers, it will also examine each kernel driver binary to see if it links to the KMDF runtime loader. This is also a KMDF driver- and WdfVerifier will simply create the registry key for you in this case, so it starts faster the next time you use it (and as a side effect, it also now works remotely).
If you're worried that you'll lose track of what machine you are controlling, have no fear- take a look at the title bar for WdfVerifier (it lists the computer name for the machine being controlled) and rest easy.
Step 3: Find one of your drivers on the driver list
Most of the left side of the first tab on the WdfVerifier property sheet is a list of KMDF drivers on the target machine. The list shows (within the limits of the box itself) the service name, whether the driver binary is currently loaded or not, and its KMDF version.
When you select a driver from this list, then most of the rest of the tab will be updated to show information related to that selection. The controls for the verifier settings will reflect the in-progress settings for the driver, while the device instance list will show device instances (present or not) for which the selected driver is a function or filter driver.
Tool tips- did you have to?
Out of the box, WdfVerifier will present some huge balloon-style tool tips as you mouse over the controls. They contain detailed information about each setting and control I (with the assistance of the WDF team) thought would be useful to you in understanding KMDF verifier (the same will apply to UMDF when we get to that article). Because they have so much detail, they have a very long "pop" time so they can be read in their entirety without continual jiggling of the mouse (25 seconds, but moving the mouse away should dismiss them sooner).
Some people will appreciate the effort in trying to help them. Some will absolutely hate it. To accommodate the latter audience, I'll tell you now:
- You can reduce the pop time in 1-second increments to a minimum of about 2 seconds.
- You can turn them off entirely.
I suspect many people will turn them off except when they want to check something. That's fine- they're only there if you need them. You can do this and many other tool customizations on the tab titled Tool Preferences.
Step 4: Make the changes you want to make
The tool tips will help guide you here, describing what individual settings do. You will find some setting affect other settings, so when you change them, other settings may change. This is deliberate, what you see is always a working configuration (something registry edits might not give you).
But I have more than one driver- I don't want to lose my changes when I switch to a different one!
If you are making changes for multiple drivers, have no fear- WdfVerifier will remember what you've already changed, even if you switch to another driver. But it won't actually change the registry until you tell it to (the exception being its own configuration- so if you turn tool tips off or on, that is effective immediately).
I want to make the same settings apply to 6 different drivers- it's a pain having to do that six times!
Not to worry- Doron got there ahead of you! Make the changes to one driver, press the button Paste Settings To... and you now have a list of all the other KMDF drivers on the system. Just mark the ones you want to have the same settings, and press OK. You're there!
Step 5: Press OK or Apply
The final thing to do is to commit the changes (nothing changes permanently until you do). Either button will begin the process.
What does that prompt mean?
KMDF verifier settings are established at the time a driver is loaded. If you made changes to a driver that was loaded, and I was able to find running device instances that used that driver as a function or filter driver, then I have given you a list of device instances that must be disabled and re-enabled for your settings to take effect. More precisely, I have given you a list of every device instance that must be treated this way in order to have all changes you have made take effect, and I am offering to handle this task for you.
This comes with some caveats:
- If you are using KMDF in an NT-4 style driver, a file system driver, or a class filter, you won't be covered. I don't attempt to stop these cases because they are currently rare, and I have no clear way to handle them.
- If you changed the loader diagnostics flag, EVERY KMDF driver must be unloaded and reloaded for the change to take effect. So if you have any of the items in the first list, the actions WdfVerifier will take won't take care of your problem.
- The list has been pruned for topology- by this I mean that if you change settings on a KMDF bus driver, I won't bother trying to disable KMDF devices on that bus, because disabling the bus will of necessity disable them. So you may not see all the devices you expect to see in this case.
- If you use a software bus driver, you want to be careful here- odds are that after this completes you will have to do whatever it is you usually do to make child devices appear on your bus (for instance, use the toaster bus' enum tool).
So, if you want to take the easy way out, and you trust me (or at least figure it's worth a shot), say OK, and WdfVerifier will first disable all of the devices listed, and if that succeeds, it will try to re-enable them. You can also do this yourself with Device Manager (and then say "No" to my offer), or decide you don't care if the settings take immediate effect.
Reboot?
There will be cases where the preceding steps will fail. When this happens, a reboot is needed to make your changes stick. So the application will ask about that.
OK, I like that it does that (or I hate it and will never use it)- does it have to keep asking?
No. On each prompt, there is a "Don't Ask Me Again" choice. If you click that, then your ultimate answer- Yes or No- becomes the action WdfVerifier will take from now on. So you can have it try to disable/enable, but ask to reboot, have it do both on its own, never ask at all, or do what it does out of the box. If you decide after a while the way that you've got it set up isn't working for you after all, you can pick any of these variations directly on the Tool Preferences tab.
Hey- the loader diagnostics are DbgPrints- aren't those suppressed on Vista and Server 2008?
Yes, but WdfVerifier will turn them on for you when you need them if you let it. It will either turn DbgPrint on and off to match the loader diagnostics flag setting, or (helpful if you use DbgPrint in your driver, as well) it will turn them on if they are off, but not turn them off. Finally, of course, if you don't trust the feature or just like to do it yourself, you can tell it to leave that part of the registry alone!
What next?
Use those features to get the most benefit out of KMDF! Turn on verbose logging to see the kernel-side event trace- turn up the number of memory pages used for logging if the default isn't enough. Turn the WDFVERIFY and WdfVerifierBreakpoint features on and off as you need to. Let us know what works for you and what doesn't (the same applies to the WdfVerifier tool itself, of course).
