Tested Platforms and Compilers

As was the case for the Windows XP DDK a complete set of tools is supplied with the Windows XP Service Pack 1 DDK for building drivers. Microsoft Visual C++ is no longer required to be installed to use the DDK.

Please use the included tools to build Windows 2000 or Windows XP device drivers. Do not use compilers, linkers or other build tools from other development products such as Visual Studio .NET to build Windows 2000 or Windows XP device drivers. This version of the Windows DDK does not support using a version of Microsoft Visual C++ other than the one supplied with the DDK. Attempts to use in incorrect version of Visual C++ will result in the following error message from the compiler:

error C1189: #error : Compiler version not supported by Windows DDK

Some Windows Millennium (Me) drivers may require Visual C++ version 6.0 to be installed for use regardless of the platform being used to build the drivers. Later versions of Visual C++ will not work in the Windows Me build environment.

The DDK toolset has not been fully tested for use other than driver development. The DDK toolset is not complete in respect to developing all types of applications.

Updated Setenv.bat

The <BaseDir>\setenv64.bat has been merged into a <BaseDir>\setenv.bat. All build environments are still supported with the <BaseDir>\setenv.bat but the command line has been updated. The new command line is: SetEnv <Directory> [fre|chk] [64] [WXP|W2K]. Directory is the install location of the DDK, fre or chk are the build types and 64 is to select the building of the 64 bit platform. If the 64 option is used, fre or chk are required. WXP or W2K select the desired target platform.

Building Binary Compatible Drivers

Drivers should typically be built in the build environment of the earliest operating system that the drivers will support. Therefore, a driver that will need to run on Windows 2000 and Windows XP should typically be built within the Windows 2000 build environment.

Some drivers, however, may wish to use additional features that are available on the newer operating system, when they run on that operating system. Such drivers may do this by carefully utilizing functions such as IoIsWdmVersionAvailable() and MmGetSystemRoutineAddress(), or similar technology specific functions.

Extreme care and thorough testing will be required to determine if a driver built for a later operating system will work properly on an earlier operating system. This may not always be possible.

One problem that you may encounter when building a driver in the Windows XP Checked Build Environment, and running that driver on Windows 2000, concerns functions that are only exported by the Windows XP or Windows XP Service Pack 1 version of NTOSKRNL. If your driver calls one of these functions, it may crash or fail to load when run on any platform other than Windows XP or Windows XP Service Pack 1. The Free Build of your driver is not typically affected, as these newly exported functions typically resolve to intrinsics when optimizations are enabled in the Free Build. This problem may be avoided by defining the value USE_LIBCNTPR=1 in your driver's sources file.

Change In Definition of KeNumberProcessors

The kernel variable KeNumberProcessors indicates the number of active CPUs in the system on which a driver is running. The definition for this variable was changed in the Windows XP versions of ntddk.h and wdm.h from a pointer to a value. The Windows 2000 definition of this variable required that KeNumberProcessors be dereferenced (e.g. *KeNumberProcessors). As a result of the change in the defintion of this variable, drivers built in the Windows XP Service Pack 1 build environment need not (and in fact must not) dereference this variable (e.g. KeNumberProcessors).

Drivers that fail to use KeNumberProcessors correctly will get an "illegal indirection" error at compile time.

Note that regardless of the declaration used, drivers that properly reference KeNumberProcessors according to the environment in which they are built will work properly on both Windows 2000 and Windows XP. Therefore, a driver that properly references KeNumberProcessors and that is built in the Windows 2000 build environment, will get the proper value for this variable when the driver is run on either Windows 2000 or Windows XP Service Pack 1.

Windows 9x Development Platform

Using Windows 9x as a development platform for WDM drivers is not supported. Drivers that target Windows XP or Windows 2000, with or without Windows 9x as an additional target, should be developed on a machine running Windows XP or Windows 2000.

New Slist Implementation

Additional optimizations were added in Windows XP to the implementation of singly linked lists (Slists). The Windows 2000 implementation of Slists also remains on Windows XP Service Pack 1 to enable drivers built on Windows 2000 to run unchanged on Windows XP Service Pack 1. The functions affected are ExInterlockedPopEntrySList() and ExInterlockedPushEntrySList() as well as ExAllocateFromPagedLookasideList(),ExFreeToPagedLookasideList(),ExAllocateFromNPagedLookasideList(), and ExFreeToNPagedLookasideList().

The Windows XP Service Pack 1 implementation of these functions, by default, is not binary compatible with the implementation on Windows 2000. If your driver uses SLists and needs to run on Windows 2000, you should build your driver in the Windows 2000 build environment. Optionally, you can build your driver on Windows XP Service Pack 1 and use the Windows 2000 Slist implementation by defining the symbol _WIN2K_COMPAT_SLIST_USAGE at compile time, prior to including any other DDK header files.

Identifying Obsolete Functions In Your Driver

The Windows DDK has a very useful feature that driver developers can enable. When the environment variable DEPRECATE_DDK_FUNCTIONS is defined, the compiler will generate a warning message whenever particular obsolete functions or macros from ntddk.h are referenced. Such obsolete functions are clearly marked in the DDK documentation.

The compiler warning message shows both the line in your source file that invoked the obsolete function, and the line in ntddk.h where the function is declared. An example of an error message you'll get is:

\test\mydriver.c(1785) : error C4996: 'RtlExtendedIntegerMultiply' was declared deprecated

\winddk\WinXP\inc\ddk\wxp\ntddk.h(3106) : error see declaration of 'RtlExtendedntegerMultiply'

Each of the functions that have been declared deprecated in ntddk.h have comments that indicate what, if any, function or mechanism you should use instead of the obsolete function. You can find this same information in the DDK Documentation. Continuing the example above, if you look at line 3106 of ntddk.h you'll find the following declaration, instructing you to use native 64-bit math instead of RTL functions for this purpose:

DECLSPEC_DEPRECATED_DDK          // Use native __int64 math
NTSYSAPI
LARGE_INTEGER
NTAPI
RtlExtendedIntegerMultiply (
        LARGE_INTEGER Multiplicand,
        LONG Multiplier
        );


The goal of this feature is to help developers easily discover functions in their drivers that have been obsoleted. All the functions that have been declared deprecated in the DDK have been obsolete at least since Windows 2000. Only a subset of functions that are obsolete have been actually declared as deprecated. There may other obsolete functions, both in ntddk.h and in other header files that have not yet been declared deprecated. Please refer to the DDK documentation as the ultimate guide regarding which functions are obsolete and which are presently supported.

Predefined Paths

The Windows DDK, by default, will not use any pre-defined Include or Library paths (as specified by the %include% and %lib% environment variables). This is due to the stand alone nature of the DDK and to avoid possible conflicts with other installed source or compiler programs. Any drivers that need to alter the search path for include files should use the Includes= directive in the SOURCES file.

WDM Audio Drivers

This Windows® XP Service Pack 1 DDK should be used for all WDM audio driver development. Please rebuild your driver with this DDK to take advantage of recent changes and fixes. As of this release, this DDK supports Windows 98 Second Edition, Windows Me, Windows 2000, and Windows XP. This DDK does not support nor do we recommend the development of WDM audio drivers for the original Windows 98 release. The code samples that are listed below will work interchangeably on the supported operating systems with the INF files that are provided with the samples:

• ac97 - A sample audio driver that runs on an Intel motherboard with an integrated AC97 controller. This sample shows how to write a WDM audio adapter driver that implements WavePci support for a PCI add-in card with scatter/gather DMA capabilities. Included with this sample driver are additional subdirectories containing sample code that works in conjunction with the driver. The subdirectories are named as follows:
  • cpl - This sample shows how to write a control panel application. It requires that both the proppage sample DLL and the ac97 sample driver be installed.
  • driver - This is the sample audio driver for the AC97 controller.
  • INFViewer - This subdirectory contains an HTML version of the driver's INF file with hot-linked references to INF sections and keyword definitions in order to facilitate easy exploration.
  • proppage - This sample shows how to write a property-page DLL that gets loaded by the device manager when a user elects to display the properties of your device. In addition to displaying the default property sheets, the device manager also displays the property sheet that is defined in the sample. This sample DLL requires that the ac97 sample driver be installed.
• ddksynth - Kernel-mode DLS synthesizer. This sample can be adapted for a MIDI output device as well.
• dmusuart - MPU-401 miniport driver for processing DirectMusic and MIDI input and output streams. This is the source code for the built-in DMusUART miniport driver in portcls.sys. Hardware vendors can adapt this sample to write their own custom miniport drivers.
• fmsynth - FM-synth miniport driver for MIDI. This sample driver provides an interface to a device that implements OPL3-style synthesis. This is the source code for the built-in FMSynth miniport driver in portcls.sys. Hardware vendors can adapt this sample to write their own custom miniport drivers.
• gfx - The two GFX samples appear in the DDK for Windows XP SP1, Windows .NET Server, and later. These samples implement support for a simple GFX (global effects) filter:
  • driver - This sample GFX driver performs a simple data transformation on a stereo audio stream that is played through a pair of USB speakers.
  • GFXProp - This sample implements a property page that the user accesses through the Windows Multimedia control panel in order to configure the GFX filter.
• mpu401 - Stand-alone sample adapter driver. This adapter driver implements standard functionality for an MPU-401 MIDI interface device. The source code for this sample is quite small because it uses only the system-supplied miniport drivers that are implemented in portcls.sys.
• msvad - Microsoft Virtual Audio Device. This is a collection of samples that all use the same "virtual audio device" in lieu of an actual hardware-based adapter driver. Each of these samples highlights a different facet of the WDM audio driver architecture:
  • ac3 - Demonstrates support for a non-PCM audio data format.
  • drmmult - Demonstrates support for multiple-stream audio with SAP-protected content. For information about SAP (secure audio path), see the Platform SDK documentation.
  • drmsimp - Demonstrates support for a single audio stream with SAP-protected content.
  • ds2dhw - Demonstrates support for hardware-accelerated two-dimensional mixing for DirectSound.
  • multstr - Demonstrates support for playback of multiple streams of PCM audio data.
  • pcmex - Demonstrates support for a PCM audio format that is defined by the WAVEFORMATEXTENSIBLE structure.
  • simple - A skeleton reference implementation of an audio adapter driver upon which the other msvad sample drivers are built.
• sb16 - Sound Blaster 16 sample. This sample implements an audio adapter driver for an SB-compatible adapter card on an ISA bus.
• stdunk - Standard IUnknown sample. Skeleton implementation of a standard IUnknown interface that conforms to the port-class model for using COM in the kernel.

For details, see the readme documentation that accompanies each of these samples in the DDK.

To install the portion of the Windows DDK that contains the WDM audio driver samples, follow these instructions:

• Run the Windows DDK setup application.
• From the list of component groups that the setup application displays, first select "WDM Samples" under "Windows DDK"; then select "Audio Samples".

When setup completes, you will find the audio driver samples in the src\wdm\audio subdirectory under the main directory of your DDK installation.

This DDK release includes documentation for developing drivers to run in Windows 98/Me, but it no longer provides build environments for Windows 98/Me. If you require the Windows 98/Me build environments and the related tools for these environments, refer to the DDK CD-ROM for Windows XP or earlier.

Building the Samples on Windows 9x

It is suggested that you disable virus protection when building samples on Windows 98, Windows 98 SE and Windows ME.

Signed Sample Installation

The samples moufiltr and kbdfiltr include INFs that demonstrate the proper use of the 'CatalogFile=' directive. The catalog files (CAT) included in these samples are not true catalog files, therefore installation of the input samples moufiltr and kbfiltr does not work. To temporarily fix, please edit moufiltr.inf and kbfiltr.inf. From the version section of each INF, remove the line that begins with 'CatalogFile='. Prior to distributing your drivers that use the 'CatalogFile=' INF directive, you will need to obtain a true catalog file from WHQL.

Win9x WDM Symbol Generation

Many of the WDM samples in this DDK can also be used on Windows 98 and Windows 98 SE. To create symbols in the SYM format needed by the Win9x debuggers place the keyword 'MAP_SYM=1' in the sources file for the sample.

IME Warnings Under the Japanese System Locale

When the system locale has been set to Japanese, the following three warnings occur:

cht\chajei\..\ime.rc(37) : warning RC4093: unescaped newline in character constant in inactive code
cht\phon\..\ime.rc(37) : warning RC4093: unescaped newline in character constant in inactive code
cht\quick\..\ime.rc(37) : warning RC4093: unescaped newline in character constant in inactive code

These warnings appear in both the free and checked builds. These warnings do not cause any problems in the resulting drivers.

Scanners & Cameras

When compiling drivers that include usbscan.h, be sure to specify that the structures defined in usbscan.h are packed on 8 byte boundaries. One way to accomplish this for Microsoft compilers is to insert "#pragma pack(8)" or "#pragma pack(push,8)" at the beginning of usbscan.h.

Building DDK Sample Drivers In Windows 2000 Build Environment

Unless specifically labeled otherwise, the sample drivers provided with the Windows DDK are designed to support Windows XP Service Pack 1 and to be built within the Windows XP Service Pack 1 build environment. Some samples in the DDK build correctly in other (e.g. Windows 2000) build environments. Other samples utilize features, data structures, or functions that are specific to Windows XP Service Pack 1 and therefore will only build properly in the Windows XP Service Pack 1 build environment.

Due to the reorganization of the \inc paths and directory structure, and due to the change in compiler versions between Windows 2000 and Windows XP Service Pack 1, some samples from the Windows 2000 DDK may build with errors in the Windows DDK's Windows 2000 build environment. This is the expected behavior.

Tool Issues

Old Tools

The older tools in the DDK have moved. Many of the tools that were previously located in the DDK \bin directory have been moved to individual directories located under the DDK's \tools directory. Several of the older tools, such as drivers.exe, objdir.exe, and kernprof.exe, can be found in the DDK's \tools\other\ directory.

New Tools

Many new tools are now available. In response to developer's requests, we are making many more tools available in the DDK. These tools can all be found in sub-directories of the DDK's \tools directory. Specifically, be sure to check out the PnP Driver Test utility (\tools\pnpdtest\), the sleeper tool for testing driver power management states (\tools\acpi\sleeper\), and the DeviceTree tool that displays the complete system's PnP device tree (\tools\devicetree\). Descriptions of each tool appear in the tool's directory.

Top of page

© Copyright 2002 Microsoft Corporation. All rights reserved.