Windows Server 2003 Service Pack 1 (SP1)
Driver Development Kit (DDK)

Installation Issues

Dirs Files

The method of generating dirs files has changed. The dirs file is now created by the Microsoft® Windows® Driver Development Kit (DDK) setup program during kit installation. If the dirs file needs to be recreated after installation of the kit, a command-line tool (makedirs) is supplied in the \bin\x86 directory. The uninstall program also updates the dirs file if Basic Uninstall is selected.

The DDK Build Environment

Use the Microsoft® Windows Server™ 2003 Service Pack 1 (SP1) build environments in this DDK to build drivers that use new features or functionality available only in Windows Server 2003.

Use the Microsoft Windows XP build environments in this DDK to build drivers that do not use new functionality as described above, and that are targeted for either Windows XP or both Windows Server 2003 and Windows XP. The Windows XP build environment in this kit contains minor updates to the DDK shipped with Windows XP with no service packs installed.

Use the Microsoft Windows 2000 build environments in this DDK to build drivers that are designed to run on Windows 2000 only, or Windows 2000 or later operating systems. The Windows 2000 build environment in this kit includes an update of headers and libraries for Windows 2000 Service Pack 3 (SP3).

Changes to Support Conditional Compilation Based on Build Environment

The environment variable DDK_TARGET_OS has been introduced to allow conditional testing in the sources file to determine if a driver is being built in the Windows 2000 build environments. This variable is set to "WinNET", "WinXP", or "Win2K", respectively. For more information, see "DDK_TARGET_OS" in the DDK documentation.

Building DDK Samples (See also Sample Issues)

All samples included in this DDK build are without errors or warnings in the Microsoft® Windows Server™ 2003 build environments and function properly on Windows Server 2003.

Some of the samples may use new features or functionality present for the first time in Windows Server 2003 Service Pack 1 (SP1). These samples will not build properly in the Windows® XP or Windows 2000 build environments. Similarly, some samples use features or functionality first present in Window XP. These samples will not build properly in the Windows 2000 build environments.

If you build the entire kit, samples that are not supported in the active build environment will not be built because of one (or more) of the following issues:

• Changes to the driver's sources file
• Changes to one of the driver's makefile files
• Changes to a dirs file

The result is that the correct set of drivers is always built when a Command Prompt window is opened for a given build environment and the build -cZ command is issued from the DDK's src directory.

When a Command Prompt window is opened for a given build environment, a user can manually change directories using the cd command to the driver directory that uses features or functionality that are not supported in that environment. If the user attempts to build such a driver in an unsupported environment, and the driver was blocked from building by a dirs file, the build command fails with a variety of errors and/or warnings; this is the expected behavior.

Expected Warnings When Building Samples Under the Windows XP and Windows 2000 Environments

Some samples in the Windows Server 2003 SP1 DDK are not supported on Windows XP and/or Windows 2000. These samples now generate a warning when they are built in a non-supported build environment. The warning, which appears in the build warning log, is in the following format:

BUILDMSG: Warning : The sample "" is not valid for the current OS target

Extensible Firmware Interface (EFI)

Developers who want to build 64-bit Extensible Firmware Interface (EFI) executable images for the Intel Itanium processor family can use the 64-bit DDK build environments for compiling and linking images. This includes EFI-compliant system firmware, EFI applications and option ROMs. EFI drivers and applications will only run in the pre-boot EFI firmware environment before Windows Server 2003 or Windows XP is loaded. At this time, only the 64-bit compiler and linker have been tested with the EFI Sample Implementation releases and the Toolkit. For further information about EFI specifications and sample source code, go to http://developer.intel.com/technology/EFI.

Changes to the Windows 2000 Build Environment

Additional headers have been added to more completely match the headers shipped for the Windows XP environment. This was necessary to allow some of the samples to compile when built in the Windows 2000 build environment.

When creating the Windows 2000 build environment using the Start menu, the environment variable BUILD_OPTIONS is set to exclude many samples from default compilation under this environment. This has the following effects and limitations, which apply only to the Windows 2000 environment:

• Running build -cZ from the DDK root now results in a clean build with no errors or warnings.
• Not all samples are built.
• Does not prevent changing directories to an arbitrary sample directory and attempting to build it. When doing so, samples that do not work correctly in the Windows 2000 build environment will still produce errors and/or warnings.

 

Compiling and Linking

Tested Platforms and Compilers

The Microsoft® Windows® DDK ships a complete set of tools for building drivers. These tools have been upgraded from those released with the Windows XP DDK. As in the Windows XP DDK, Microsoft Visual C++® is no longer required to be installed.

Use the included tools for all Windows Server™ 2003, Windows XP, and Windows 2000, drivers. This version of the DDK does not support building drivers using a version of Visual C++ other than the one supplied with the DDK.

Some Windows Millennium Edition (Me) drivers, such as Microsoft DirectX® drivers for that platform, 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.

This toolset has not been fully tested for use other than driver development. Development work on this toolset is not complete.

Buffer Overflow Checking and DriverEntry

The Windows Server 2003 Service Pack 1 (SP1) DDK enables the /Gs compiler option for both free and checked drivers built in the Windows Server 2003 build environment. This compiler option implements stack buffer overflow checking. To support this feature, the Windows Server 2003 build environment set the driver entry point to GsDriverEntry. GsDriverEntry performs some brief initialization, and then calls the driver's DriverEntry entry point.

Experience with using this switch at Microsoft has shown that the /Gs option adds very little overhead to a kernel module and simultaneously helps to counter a potential security risk.

Buffer overflow checking can be turned off by setting the environment variable BUFFER_OVERFLOW_CHECKS to 0 in the Windows Server 2003 build environment.

Updated SetEnv.bat File

The <BASEDIR>\SetEnv64.bat file has been merged into a <BASEDIR>\SetEnv.bat file. The Windows Server 2003 and Windows XP build environments are supported with the <BASEDIR>\SetEnv.bat file; however, the command line has been updated. For more information, see "Using the SetEnv.bat Command Line" in the DDK documentation.

Building Binary Compatible Drivers

Typically, drivers should be built in the build environment of the earliest operating system that the driver supports. Therefore, a driver that needs to run on Windows XP and Windows 2000 should be built in the Windows 2000 build environment.

To enable your driver to use the additional features that are available on a more recent operating system, you can use technology-specific functions, such as IoIsWdmVersionAvailable() and MmGetSystemRoutineAddress().

Thorough testing is required to determine whether a driver built for a more recent operating system works properly on an earlier operating system.

KeNumberProcessors Definition Change

The kernel variable KeNumberProcessors indicates the number of active CPUs in the system on which a driver is running. The definition for this variable has been 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 (for example, *KeNumberProcessors). As a result of the variable’s change in , drivers built in the Windows XP build environment must not dereference this variable (for example, KeNumberProcessors).

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

Regardless of the declaration used, drivers that properly reference KeNumberProcessors, according to the environment in which they are built, work properly on Windows Server 2003, Windows XP, and Windows 2000. Therefore, a driver that properly references KeNumberProcessors, and that is built in the Windows 2000 build environment, receives the proper value for this variable when the driver is run on Windows Server 2003, Windows XP, or Windows 2000.

New SList Implementation

Additional improvements have been added to the Windows XP and later implementations of singly-linked lists (SLists). The Windows 2000 implementation of SLists remains in the DDK to enable drivers built on Windows 2000 to run unchanged on Windows XP and later systems. The functions affected are ExInterlockedPopEntrySList() and ExInterlockedPushEntrySList(), as well as ExAllocateFromPagedLookasideList(), ExFreeToPagedLookasideList(), ExAllocateFromNPagedLookasideList(), and ExFreeToNPagedLookasideList().

The Windows XP and later 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 in another build environment and use the Windows 2000 SList implementation by defining the symbol _WIN2K_COMPAT_SLIST_USAGE at compile time, before including any other DDK header files.

Identifying Obsolete Functions in Your Driver

The DDK Windows Server 2003 and Windows XP build environments include a feature that, when enabled, identifies obsolete functions in your driver. When the environment variable DEPRECATE_DDK_FUNCTIONS is defined, the compiler generates a warning message whenever an obsolete function or macro from ntddk.h is referenced. For more information about the obsolete functions, see 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. The following example shows an error message:

\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 which, if any, function or mechanism you should use instead of the obsolete function. For more information, see the DDK documentation. In the previous example, if you look at line 3106 of ntddk.h, you'll find the following declaration, which instructs you to use native 64-bit math instead of RTL functions:

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

This feature helps developers discover functions in their drivers that are obsolete. All of 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 might be other obsolete functions, both in ntddk.h and in other header files that have not yet been declared deprecated. Refer to the DDK documentation for functions that are obsolete or currently supported.

Predefined Paths

The 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 Includes=directive in the sources file.

WDM Audio Drivers

The Microsoft® Windows Server™ 2003 Service Pack 1 (SP1) 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 the Windows Server 2003 SP1 release, this DDK supports Windows Server 2003, Windows XP, and Windows 2000. This DDK does not support, nor do we recommend, the development of WDM audio drivers for Windows 9x. 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 direct memory access (DMA) capabilities. Included with this sample driver are additional subdirectories that contain 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 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 downloadable sounds (DLS) synthesizer. This sample can be adapted for a MIDI output device as well.
• dmusuart—MPU-401 miniport driver for processing Microsoft 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 Server 2003 or later and Windows XP Service Pack 1 (SP1). These samples implement support for a sample 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 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 one of the following different facets of the WDM audio driver architecture:
• ac3—Demonstrates support for a non-PCM audio data format.
• drmmult—Demonstrates support for multiple-stream audio with secure audio path (SAP)-protected content. For information about SAP, 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 Microsoft 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 (SB) 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 more information about the samples, see the Readme documentation that accompanies each of these samples in the DDK.

To install the portion of the DDK that contains the WDM audio driver samples, complete the following instructions:

1.      Run the Windows DDK setup application.

2.      From the list of component groups that the setup application displays, under Windows DDK, select WDM Samples, and 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 with Windows Millennium Edition (Me) and Windows 98, but it no longer provides build environments for Windows Me or Windows 98. If you require those build environments, and the related tools, refer to the Windows XP SP1 DDK located in the archive section on MSDN.

Windows Server 2003 Service Pack 1 (SP1), Windows XP, and Windows 2000 Compatibility

Windows Memory Manager

A change was made in the memory manager starting with Microsoft® Windows® XP that affects how functions such as ZwMapViewOfSection and MmMapLockedPagesSpecifyCache work.

In the past (on Windows 2000 and Windows NT® Server 4.0), it was up to the driver writer to ensure that the same physical page was not mapped with different caching attributes, which is an error and can cause internal processor corruption leading to undefined results.

In Windows XP and later, the memory manager catches this problem. That is, when mapping the same physical page, the page must always be mapped with the same caching attribute. If conflicting attributes are specified by the caller of the above APIs, the Windows memory manager automatically tries to determine and use the correct attribute. If the correct attribute cannot be determined, then ZwMapViewOfSection returns STATUS_CONFLICTING_ADDRESSES and MmMapLockedPagesSpecifyCache returns NULL.

Sample Issues

Signed Sample Installation

The samples moufiltr and kbdfiltr include INF files that demonstrate the proper use of the "CatalogFile=" directive. The catalog files (CATs) included in these samples are not true catalog files, therefore, installation of the input samples moufiltr and kbfiltr does not work. To temporarily fix the installation, edit moufiltr.inf and kbfiltr.inf by removing the line that begins with "CatalogFile=" from the version section of each INF file. Before distributing your drivers that use the "CatalogFile=" INF directive, you must obtain a true catalog file from WHQL.

IME Warnings Under the Japanese System Locale

When the system locale has been set to Japanese, the following 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.

Tools

FusionManifestValidator

For the Microsoft® Windows Server™ 2003 Service Pack 1 (SP1) DDK, not all files may compile correctly on a Windows® 2000 computer using the FusionManifestValidator tool. This will be fixed for future releases.

IrDA Tools

For the Windows Server 2003 SP1 DDK, Itanium-based and x64-based platform versions of the IrDA tools are not available.

Miscellaneous

None 

Late Breaking Release Notes

Please see our page on http://www.microsoft.com/whdc/DevTools/default.mspx for any updates.

Top of page

Copyright © 2005 Microsoft Corporation