Windows Driver Kit (WDK) Documentation Blog

September Documentation Update

wdkblog — Wed, 07 Oct 2009 04:41:00 GMT

September’s documentation updates were posted to MSDN on October 2^nd, 2009. You can access the updated documentation here:

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

You can download the offline version of the documentation (in Hxs format) here:

http://www.microsoft.com/whdc/DevTools/WDK/WDKdocs.mspx

As a reminder, we only release the documentation in Chm format for major OS milestones.

The File System Filter Test Suite

wdkblog — Fri, 02 Oct 2009 04:11:00 GMT

The Microsoft File System Filter team has created a Filter Test Suite to help filter ISVs prepare for the release of Windows 7. The test suite is a collection of regression tests that apply to a number of filtering points in the Windows platform: This test suite offers improved test coverage for file systems, networking, process, and registry filtering.

The primary goals of the test suite are to help in the following areas:

Identify potential reliability bugs in filter drivers
Reduce the number of Windows crashes that customers experience

Be aware that the test suite is not part of the Windows Logo Kit (WLK), and is not a logo requirement at this time.

The Filter Test Suite, which requires Windows 7, is available from the Microsoft Connect Web site. If you do not have a Microsoft Connect account, you can request one by sending E-mail to fsfcomm@microsoft.com.

-- Karlito Bonnevie [MSFT], Installable File Systems Programming Writer

Changes to XPS Rasterization Filter Sample for Windows Vista SP2 with Platform Client Update

wdkblog — Wed, 30 Sep 2009 03:43:00 GMT

If you are working with the Windows Vista SP2 with Platform Client Update, you will need to make some minor changes to the Print XPS Rasterization Filter Sample. If you want to know more about the Platform Client Update, see KB article 971644.

Follow these steps to make the sample work in Vista SP2 with Platform Client Update:

Buld the sample using Windows 7.
Change the xpsrassmpl.inf file.
Install the sample on Windows Vista SP2 with Platform Client Update.

For step 2, make these changes to the XPSRASSMPL.INF file:

Change the Manufacturer section to read:

[Manufacturer]%Microsoft%=Microsoft,NTx86.6.1,NTia64.6.1,NTamd64.6.1,NTx86.6.0,NTia64.6.0,NTamd64.6.0

Add the following sections after the Manufacturer section:

[Microsoft.NTx86.6.0]
"XPSRas WDK Sample Driver" = INSTALL_FILTER
[Microsoft.NTia64.6.0]
"XPSRas WDK Sample Driver" = INSTALL_FILTER
[Microsoft.NTamd64.6.0]
"XPSRas WDK Sample Driver" = INSTALL_FILTER

－Seth McEvoy [MSFT], WDK Senior Programming Writer

IFS Plugfest 21 Goodies

wdkblog — Tue, 22 Sep 2009 04:14:00 GMT

Did you attend IFS Plugfest 21 but didn't get a chance to grab all the goodies? If so (and you signed the IFS Plugfest 21 NDA), you can access the following goodies via Microsoft Connect.

Plugfest slides and videos
Filter Test Suite VHD
Windows Error Reporting Gadget (as demo'd by Kevin Hill)
Security Provider Jumpstart Kit

If you don't already have a Microsoft Connect account, you can request one by sending E-mail to fsfcomm@microsoft.com.

-- Karlito Bonnevie [MSFT], Installable File Systems Programming Writer

What’s new in WDF docs for Win7?

wdkblog — Wed, 26 Aug 2009 05:52:00 GMT

I’m the doc writer for both Kernel-Mode Driver Framework (KMDF) and User-Mode Driver Framework (UMDF) documentation that’s in the Windows Driver Kit. Perhaps you’d like to know what I’ve been working on for Windows 7.

I’ve always been the owner of KMDF docs in the WDK. At the beginning of the Windows 7 product timeframe I also took ownership of UMDF documentation, so all WDK documentation for both of the frameworks is now my responsibility. One of my goals is to bring UMDF documentation in alignment with KMDF documentation in terms of style, organization, and completeness. I’ve been able to make some headway on this goal for Windows 7. For example, the reference sections of KMDF and UMDF are more aligned than previously. In addition, when I’ve added to the UMDF design guide, I’ve used the equivalent KMDF sections as prototypes.

Naturally, I’ve spent a good deal of my time updating KMDF and UMDF docs for WDF version 1.9, which ships with Windows 7. Want to know what changes I’ve made? For KMDF, see the KMDF revision history in the WDK docs on MSDN. For UMDF, see UMDF version information, also in the WDK docs on MSDN.

What’s next for me and WDF docs? In future documentation updates, I’ll be focusing on filling in gaps in the UMDF design guide and aligning its structure more closely to the KMDF design guide. When the UMDF and KMDF design guides and reference pages are in alignment, you’ll be able to more easily see where the two driver models are similar and where they diverge.

Your feedback is always welcome.

— Richard Brown [MSFT], WDK Senior Programming Writer

MSDN Wiki Discontinued for WDK Documentation

wdkblog — Fri, 21 Aug 2009 07:32:00 GMT

We’ve decided to shut off the Community Content (aka “wiki”) section of WDK documentation on MSDN.

A few months ago I provided this blog post, which questioned the usefulness of the Community Content feature for WDK documentation. Your responses to that post, and other feedback that we have received, confirmed our impression that the Community Content feature is providing little value to our customers.

We continue to value your feedback about our documentation. We encourage you to point out errors and provide suggestions, and to send them to us by clicking on the “send feedback” link that’s at the bottom of each topic. The link appears both in the offline documentation that installs with the kit and in the online version on MSDN.

Community Content removal coincides with the Windows 7 RTM update of WDK documentation on MSDN.

— Richard Brown [MSFT], WDK Senior Programming Writer

Do You Have the Very Latest WDK Documentation?

wdkblog — Sat, 15 Aug 2009 01:57:00 GMT

Hopefully you've already downloaded the new Windows 7 version of the WDK, which has all the latest Windows 7 headers, libraries, samples, and test applications: http://www.microsoft.com/whdc/DevTools/WDK/WDKpkg.mspx.

We've also released an even later version of the documentation. It has additional topics that we wrote after the rest of the Windows 7 WDK was frozen. A few examples:

· Device and Driver Installation: Device Metadata Packages (three new topics)

· Display: Installing Display Drivers Optimized for Windows 7 and Later

· Network: Wake-on-Wireless LAN

Grab this latest documentation at: http://www.microsoft.com/whdc/DevTools/WDK/WDKdocs.mspx#.

To view all the new Windows 7 material, in the Table of Contents click on New Information -> New for Windows 7.

－ Mark Lawler [MSFT], WDK Programming Writer

WDK Documentation Downloads Available

wdkblog — Tue, 11 Aug 2009 19:43:00 GMT

You can now download the Microsoft Windows Driver Kit (WDK) documentation for Windows 7 in either hxs or chm format from:

http://www.microsoft.com/whdc/DevTools/WDK/WDKdocs.mspx

Please use the feedback link at the bottom of each documentation page to send us any comments you may have regarding these packages.

Windows 7 WDK Documentation is Live on MSDN Online

wdkblog — Fri, 07 Aug 2009 03:05:00 GMT

As of a few minutes ago, the Windows 7 RTM WDK documentation refresh went live on MSDN online.

You can access the new documentation here:

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

Next week, the same content will be available in hxs and chm format on WHDC.

You can also now download the WDK kit via the Microsoft Download Center. For details, see:

http://www.microsoft.com/whdc/DevTools/WDK/WDKpkg.mspx

XPS Document API Now Available for Printer Driver Filter Modules

wdkblog — Sat, 11 Jul 2009 00:32:00 GMT

If you are a Print Driver developer using the XPS Filter Pipeline, you can now use unmanaged XPS functions that were previously only available as .NET managed code. Because these functions were originally written for .NET, they could not be called from a Print driver until now.

These XPS functions will enable driver developers to modify XPS documents in greater detail when they are in the filter pipeline. This will make it possible to make custom changes to the documents before they get to the printer. In addition, this API allows you to have access to the document metadata and content.

This API was previously unavailable to Print Driver developers, but has been recently converted to unmanaged code and is now documented in the Windows SDK. The new documentation includes overviews of the XPS Object Model and complete coverage of all interfaces, methods, structures, and enumerators that are implemented by the XPS API.

For more information, see the XPS Document Programming Guide and Reference at http://msdn.microsoft.com/en-us/library/dd316976(VS.85).aspx.

－Seth McEvoy [MSFT], WDK Senior Programming Writer

Customizing a Microsoft Auto Code Review (OACR) Project

wdkblog — Sat, 11 Jul 2009 00:09:00 GMT

Microsoft Auto Code Review (known by the acronym OACR) integrates PREfast for Drivers (PFD) into the WDK build environment and is available when you install the latest WDK for Windows 7. OACR automatically begins working when you open a build environment window, so you can start using OACR and PFD without any special setup.

Side note- the name game

When you expand the acronym OACR it should spell Microsoft Auto Code Review. For some reason, and I won’t mention names, it was inadvertently converted to Windows Auto Code Review in earlier documentation. Go figure. This oversight has been corrected and the expanded name will appear as it should in future documentation. I apologize for any confusion this mix-up might have caused.

OACR configuration files

OACR uses two configuration files OACR.ini and OACRUser.ini to set preferences and to configure projects. Projects are your build targets, that is, a project is whatever driver or library you are building with the WDK build utility. The names of projects are determined by the directory where you are building and settings in the configuration file, OACR.ini, and by the projects.mk file. The OACRuser.ini file can be used by individuals to override the project settings in the OACR.ini configuration file. The location of the OACRUser.ini file is specified by the UserIniLocation setting in the OACR.ini file. The default setting in the WDK is as follows:

UserIniLocation=%BASEDIR%\config\

If you want to use an OACRUser.ini file, you will need to create the file and the %BASEDIR% \config directory. The file and the directory are not provided when you install the WDK. The %BASEDIR% is the root directory of your WDK installation (for example, C:\WinDDK\7600\).

OACR projects in the WDK

In the WDK, OACR is configured for two projects: WDKsamples and Root. The WDKsamples project settings are used any time you build something under the %BASEDIR% of WDK (for example, C:\WinDDK\7600\). The Root project is the default build project and is used for anything built outside of the WDK directory structure (for example, C:\myproj\src).

Creating a private project using a custom include file

You can add your own projects to the default OACR configuration file, as described in Creating or Modifying an OACR Project. However, if you want to create a private project and you don’t want to add it to the OACR.ini file, you can set up and environment variable and point to an include file. The settings in the include file are then added to OACR.ini. Wait! What about the OACRUser.ini configuration file? Why can’t you use that? Well, the OACRUser.ini file is used to override the project settings in the OACR.ini configuration file and cannot be used to add projects. Here is how you go about creating a private project.

1. Shutdown the OACR Monitor

Right click the OACR Monitor icon in the taskbar and click Close. Or type oacr stop in a build environment window. Close any build environment window you have open. You need to stop OACR and close the windows so that OACR can pick up the changes you will make in the following steps.

2. Set the environment variable OACRUserFIles

Edit the System Properties on your computer and create the OACRUserFIles environment variable. Set the variable to point to a directory where you will create and store your private OACR project configuration file.

set OACRUserFIles=c:\myOACRprojects

3. Add the #include directive to the OACR.ini file

The OACR.ini file is in the %BASEDIR%\version\bin\arch\OACR directory. Add the following line at the end of the file:

#include optional %OACRUserFiles%\oacr.include.ini

The oacr.include.ini file is optional, so OACR does not complain if it doesn’t exist.

4. Create the include file and define your OACR projects

Create the oacr.include.ini file in the %OACRUserFIles% directory. This include file is where you define your private OACR projects. For example, the following settings in the oacr.include.ini file create a project called MyProject.

; project 'myProject': the code under src; relies on %OACRUserFIles%\project.mk

[MyProject]

; WarningLocations=^%BASEDIR%\\src

WarningNumbers=<level0>;<level1>;<level2>;<level3_PFD_samples>;

ErrorNumbers=<level0>;<level1>;

; Use PFD's settings for these

PREfastOptions=/MAXPATHS=256 /STACKHOGTHRESHOLD=1024

%_PREFAST_CYCLOMATIC%=2147483647

%PREFAST_DRIVERS%=0

[MyProject:x86]

[MyProject:x86fre]

[MyProject:x86chk]

[MyProject:amd64]

[MyProject:amd64fre]

[MyProject:amd64chk]

5. Create a project.mk file in the target project directory

Just as with any new OACR project that you add to the OACR.ini file, you need to create a project.mk file and place that in the root directory of your source files. For more information, see Creating or Modifying an OACR Project . The project.mk file for MyProject, would look like this:

_project_=MyProject

6. Restart the OACR Monitor

Open a new build environment window to start OACR. You need to open a new build environment window so that your %OACRUserFIles% environment variable is used. When OACR starts up it reads the oacr.include.ini file and treats its content as if it were part of Oacr.ini.

7. Verify that your OACR project is configured correctly

In a build environment window, use the oacr checkini command to verify that your configuration files are set up correctly. You should see something similar to the following:

c:\WinDDK\7138.0.0>oacr checkini

Configuration : C:\WinDDK\7138.0.0\bin\x86\OACR\oacr.ini

   Includes   : C:\WinDDK\7138.0.0\bin\oacr_base.ini

                C:\MyOACRProjects\oacr.include.ini

   Defines    : x86

Customizations: C:\WinDDK\7138.0.0\config\oacruser.ini

No problems found

Use the oacr showconfig project command to verify that OACR can successfully read your project settings.

oacr showconfig MyProject

If your project is set up correctly, OACR shows the project configuration.

Note that you can also use the OACR commands oacr stop and oacr monitor to stop and start OACR. These commands are useful if you need to make changes to fix problems in the configuration files.

8. Build your driver or library

After you have verified that your OACR project is setup correctly, you can build your driver or library just as you are accustomed to doing. You only need to open a build environment window and navigate to you build target directory. OACR will use all of your project-specific settings.

What Next?

There is a lot you can do to customize the build environment and your OACR and PFD settings. But the good news is you don’t have to. You can build your driver code just as you always have and still benefit from the integration of OACR in the WDK build environment.

To learn more, read the documentation about Microsoft Auto Code Review (OACR) and PREfast for Drivers (PFD) and check for new information in the monthly updates on MSDN. Also see the Static Driver Tools blog, it provides a wealth of information about using and customizing the static analysis tools, including PFD and Static Driver Verifier. A recent blog posting describes the steps to create a “Static Driver Verifier Prerequisites” filter. For more information, see Make Static Driver Verifier More Efficient: Add a Preset Filter to PFD/OACR Defect Viewer .

-- Dave Hagen [MSFT], Programming Writer

New for Windows 7: Mobile Broadband Miniport Driver Documentation

wdkblog — Tue, 07 Jul 2009 22:38:00 GMT

Windows 7 has added new device driver interfaces (DDIs) to provide support for Mobile Broadband (MB) devices, beginning with Windows 7 Beta.

MB miniport drivers are based on the NDIS 6.20 model. You can learn more about NDIS 6.20 at http://msdn.microsoft.com/en-us/library/dd568055.aspx.

The MB DDIs consist of 21 new OIDs, 20 new NDIS status notifications specific to MB, and their associated structures and enumerations including:

Features to describe the class of MB device, such as CDMA-based (1xRTT/1xEV-DO/1xEV-DO RevA/1xEvDO RevB) or GSM-based (GPRS/EDGE/UMTS/HSPA), and its capabilities
WWAN network registration and service activation
Packet data service
Data service handoff
SMS messaging
Signal strength feedback
Vendor-specific features

To learn more about writing an MB miniport driver for Windows 7, go to http://msdn.microsoft.com/en-us/library/dd445701.aspx.

See http://msdn.microsoft.com/en-us/library/dd446088.aspx for the MB reference documentation.

-- Kevin Shirley [MSFT], Programming Writer

WDK to Continue Posting Documentation in CHM Format

wdkblog — Thu, 02 Jul 2009 03:22:00 GMT

Thanks for all the feedback regarding the CHM version of the WDK documentation. Based on your overwhelmingly positive response, we’ll continue posting the CHM version to WHDC at major Windows release intervals (Beta, RC, RTM, etc.). The CHM for the Windows 7 RTM release will be posted near the end of July.

Update to Windows 7 RC Version of the XPS Rasterization Filter Service Sample

wdkblog — Wed, 01 Jul 2009 05:00:00 GMT

Here are two updates that will help Printer driver developers who are working with the RC version of the XPS Rasterization Filter Service sample.

1. If you are using the RC version of the XPS Rasterization Filter Service sample, it is strongly recommended that you work directly with the WIC bitmap returned from the XPS Rasterization service rather than the calls into WIC to encode each band as a TIFF. The sample calls into WIC for encoding each band were for demonstration purposes only and are not recommended for larger applications because they could be inefficient and difficult.

2. In the sample, the output file consists of a series of per-band TIFFs. Because this file will be a series of complete TIFFs and not a single-page TIFF, opening the file in a viewer will only display the first band of the first page. More details can be found in the bitmaphandler.cpp file that is included in the sample source code.

The Windows 7 RTM version of the sample documentation will include this update. In the meantime, until Windows 7 is released, apply these changes to the sample documentation at http://msdn.microsoft.com/en-us/library/dd434895.aspx.

－Seth McEvoy [MSFT], WDK Senior Programming Writer

Kernel Programming: Nt and Zw Versions of the Native System Services Routines

wdkblog — Tue, 30 Jun 2009 08:36:00 GMT

The Windows native operating system services API is implemented as a set of routines that run in kernel mode. These routines have names that begin with the prefix Nt or Zw. Kernel-mode drivers can call these routines directly. User-mode applications can access these routines through system calls.

With a few exceptions, each native system services routine has two slightly different versions that have similar names but different prefixes. For example, calls to NtCreateFile and ZwCreateFile perform similar operations and are, in fact, serviced by the same kernel-mode system routine. For system calls from user mode, the Nt and Zw versions of a routine behave identically. For calls from a kernel-mode driver, the Nt and Zw versions of a routine differ in the way that they handle the parameter values that the caller passes to the routine.

A kernel-mode driver calls the Zw version of a native system services routine to inform the routine that the parameters come from a trusted, kernel-mode source. In this case, the routine assumes that it can safely use the parameters without first validating them. However, if the parameters might be from either a user-mode source or a kernel-mode source, the driver instead calls the Nt version of the routine. The Nt version determines, based on the history of the calling thread, whether the parameters originated in user mode or kernel mode. (How does the Nt routine distinguish user-mode parameters from kernel-mode parameters? See Previous Mode, below.)

When a user-mode application calls the Nt or Zw version of a native system services routine, the routine always treats the parameters that it receives as values that come from an untrusted, user-mode source. The routine thoroughly validates the parameter values before it uses the parameters. In particular, the routine probes any caller-supplied buffers to verify that the buffers reside in valid user-mode memory and are properly aligned.

Native system services routines make additional assumptions about the parameters that they receive. If a routine receives a pointer to a buffer that was allocated by a kernel-mode driver, the routine assumes that the buffer was allocated in system memory, not in user-mode memory. If the routine receives a handle that was opened by a user-mode application, the routine looks for the handle in the user-mode handle table, not in the kernel-mode handle table.

PreviousMode

When a user-mode application calls the Nt or Zw version of a native system services routine, the system call mechanism traps the calling thread to kernel mode. To indicate that the parameter values originated in user mode, the trap handler for the system call sets the PreviousMode field in the thread object of the caller to UserMode. The native system services routine checks the PreviousMode field of the calling thread to determine whether the parameters are from a user-mode source.

If a kernel-mode driver calls a native system services routine and passes parameter values to the routine that are from a kernel-mode source, the driver must ensure that the PreviousMode field in the current thread object is set to KernelMode.

A kernel-mode driver can run in the context of an arbitrary thread, and the PreviousMode field of this thread might be set to UserMode. In this situation, a kernel-mode driver can call the Zw version of a native system services routine to inform the routine that the parameter values are from a trusted, kernel-mode source. The Zw call goes to a thin wrapper function that overrides the PreviousMode value in the current thread object. The wrapper function sets PreviousMode to KernelMode and calls the Nt version of the routine. On return from the Nt version of the routine, the wrapper function restores the original PreviousMode value of the thread object and returns.

A kernel-mode driver can directly call the Nt version of a native system services routine. When a kernel-mode driver processes an I/O request that might have originated either in user mode or in kernel mode, the driver can call the Nt version of the routine to ensure that the PreviousMode value of the current thread remains unaltered during the call. That way, the routine can determine whether the parameter values are from a user-mode application or a kernel-mode component, and treat them accordingly.

An error can occur if a kernel-mode driver calls an NtXxx routine and the PreviousMode value in the current thread object does not accurately indicate whether the parameter values are from a user-mode or a kernel-mode source.

For example, assume that a kernel-mode driver is running in the context of an arbitrary thread, and that the PreviousMode value for this thread is set to UserMode. If this driver passes a kernel-mode file handle to the NtClose routine, this routine attempts to close the user-mode handle of the arbitrary thread instead of the kernel-mode handle. When NtClose fails to find the handle in the user-mode handle table, it returns the STATUS_INVALID_HANDLE error code. Meanwhile, the driver leaks the kernel-mode handle, which was never closed.

For another example, if the parameters for an NtXxx routine include an input or output buffer, and if PreviousMode is UserMode, the routine calls the ProbeForRead or ProbeForWrite routine to validate the buffer. If the buffer was allocated in system memory instead of in user-mode memory, the ProbeForXxx routine raises an exception, and the NtXxx routine returns the STATUS_ACCESS_VIOLATION error code.

If necessary, a driver can call the ExGetPreviousMode routine to get the PreviousMode value from the current thread object. Alternatively, the driver can read the RequestorMode field from the IRP structure that describes the requested I/O operation. The RequestorMode field contains a copy of the PreviousMode value from the thread that requested the operation.

What Does the Zw Prefix Mean?

The Windows native system services routines have names that begin with the prefixes Nt and Zw. The Nt prefix is an abbreviation of Windows NT, but the Zw prefix has no meaning. Zw was chosen partly to avoid potential naming conflicts with other APIs, and partly to avoid using any potentially useful two-letter prefixes that might be needed for future APIs.

Today, the ZwXxx routines are more visible to drivers and to applications than the kernel architects might have anticipated in the early days of Windows NT development. In retrospect, perhaps a more meaningful prefix could have been chosen.

– Jerry Van Aken [MSFT], WDK Programming Writer