Late-Breaking News for the Microsoft® Windows® 2000 DDK
Included in this release of Microsoft® Windows® 2000 is the Driver Verifier. This facility,
built into Windows 2000, allows developers and users to perform extra testing and validation on a driver or set of drivers.
Windows File Protection
A shortcut that opens the configuration utility for the Driver Verifier is included in the DDK. This shortcut can be found at Programs\Development Kits\Windows 2000 DDK. Driver Verifier can be found at <DDKroot>\Tools\verifier.exe.
All drivers must be tested using the Driver Verifier. If a driver behaves incorrectly, the Driver Verifier will crash the system immediately. In this way, the Driver Verifier prevents the driver bug from being masked by further processing. The result is a faster, easier debugging process.
For more information on the Driver Verifier, please see the Driver Writer's Guide in the DDK documentation.
Windows File Protection (WFP) protects system files. Windows 2000 will not allow protected system files to be overwritten by another file with the same name. However, the system will allow files that are not named the same as a protected file to be installed.
Further information on WFP is available in wfp.htm, located on the root of the CD or the root
of the DDK installation.
Microsoft now provides digital signatures for most publicly distributed drivers. Please see the file drvrsign.htm for more information on this initiative.
Dirs files are created dynamically when a Build Environment window is opened. The program VCCheck will recursively walk the directory tree and if it finds a makefile in a directory the corresponding dirs will be created. If dirs files already exist in the directory tree they will be deleted. To recreate the dirs file without opening another Build Environment window execute VCCheck with the drive\path where you want the dirs to be created (example: VCCheck /p D:\ntddk /d, will start dirs creation at the d:\ntddk
If OPTIONAL_DIRS directives must be preserved, it is suggested that the \ntddk\bin\setenv.bat and/or the \ntddk\bin\setenv64.bat file
be modified to prevent automatic dirs creation.
Open the \ntddk\bin\setenv(64).bat and search for the second occurrence of
VCCheck and comment out the line. When the build window is opened the
automatic dirs creation will not occur and any changes made to the existing
dirs file will be preserved.
Icons Not Updated
Previous versions of the Windows 2000 DDK placed program icons in the Development Kits folder under the profile of the login used to install the DDK. This version of the DDK places program icons under the All Users profile. We recommend uninstalling all previous versions of the Windows 2000 DDK prior to installing this DDK. If this version of the DDK is installed on a system without uninstalling previous versions, the icons from the previous version will remain on the system and can override the current DDK icons on the Start menu.
To allow the current icons to be seen, log on as the user who originally installed the previous version of the DDK. Right-click on the Start menu, and pick Explore. Double-click on Programs. The folder Development Kits should be seen. Rename this folder and close the Explorer window. The Start menu should now contain both the current DDK icons and the previous kit icons.
Compiling and Linking
Tested Platforms and Compilers
We have tested both Microsoft Visual C++® 5.0 (SP3) and Microsoft Visual C++® 6.0 (SP2) on the following platforms: Windows® 98 (x86), and Windows 2000 (x86).
Visual C++ 6.0 requires Visual C++ 6.0 Service Pack 2 (or greater), available from
Visual C++ 5.0 requires Visual C++ 5.0 Service Pack 3 (or greater), available from
Included ATL Headers
The version of ATL that ships with this Windows 2000 DDK is not the same as the Visual C++ version and should only be used for driver development. General purpose ATL source code is available with your normal Visual C++ installation.
Build Error Messages
During the initialization of BUILD, the following message might be displayed:
invalid include statement:
To prevent this message from displaying in the future, edit the xxxx.odl file specified in the warning message. Use a text editor to open the file and
search for "importlib." When found, add quotes around the name inside the parentheses. For example:
Then save your changes.
For more information on WinDBG and the KD debuggers included in the Windows® 2000 DDK,
and on debugging,
please see the debuggers.txt file in the directory where the debugger is installed. See also the information on debugging found in the Driver Writer's Guide in the DDK documentation.
You can also find more information on debugging at http://www.microsoft.com/hwdev/driver/ntdebugging.htm.
Windows® 98 defined a unified driver model for Windows 98 and Windows 2000 operating systems by standardizing requirements and reducing the amount of code that needed to be written. Programmers who are already familiar with Windows NT® 4.0 drivers will recognize most of the features of WDM drivers. However, the enclosed documentation and samples should be studied in order to understand the subtleties of WDM. WDM drivers will not run on operating systems earlier than Windows 98 or Windows 2000.
By conforming to WDM, drivers can be binary-compatible across Windows 98, Windows 98 Second Edition, and Windows 2000 on x86-based computers.
However, subsequent operating systems will contain features not available in preceding versions. WDM is designed to be forward-compatible but not backward-compatible. That is, drivers will be compatible with the same or higher-numbered WDM versions. Such WDM drivers will not be able to take advantage of new operating system services, but they will still load and run. Newer drivers running in a lower-version environment will most likely fail while loading.
WDM driver writers should carefully consider feature-set inclusions. For example, does the driver need to run on different platforms? Will the hardware be widely available, or is it highly specialized and thus limited in distribution?
Additionally, not all hardware meets the requirements of WDM. Video drivers do not support the WDM model and must be written separately, as do certain drivers utilizing VxDs under Windows 98 and some network drivers. Virtual hardware (emulation) and nonstandard buses are not supported in a WDM class.
A multi-operating system driver is required to conform
to the lowest WDM version of any operating system supported by the driver. For cross-operating
system compatibility, thoroughly test drivers on all versions of Windows 98 and
Windows 2000, because operating system differences can produce slightly
different driver behavior. Differences are most apparent between
single-processor and multiprocessor platforms.
WDM Audio Drivers
This Windows® 2000 DDK should be used for all WDM audio driver development. As of this release, this DDK supports both the Windows 2000 and Windows 98 SE platforms. The sample code shown here will work interchangeably on either operating system with the INF files provided. Please rebuild your driver with this DDK to take advantage of recent changes and fixes. This DDK does not support nor do we recommend the development of WDM audio drivers for the original Windows 98 release.
We have added a WDM driver sample which supports the AC97 architecture. It uses the WavePCI miniport, and should work with any AC97 codec connected to an Intel motherboard with integrated AC97 controller, like the Intel 810 Chipset.
WDM NDIS Drivers
If you are creating a driver that uses both NDIS and WDM, you will need to define the environment variable NDIS_WDM and then include ndis.h. When this is done, ndis.h will include wdm.h correctly.
New IDE Driver Stack
Microsoft® has changed the driver model for IDE devices for Windows 2000. Unlike a scsiport
miniport in Windows NT 4.0, the ATA/ATAPI driver stack in Windows 2000 implements full scsiport
interface. The new driver model isolates non-standard PCI IDE controller hardware interface into
a PCI IDE minidriver. To learn more about how to write your own pci ide mini driver, see the PCI
IDE minidriver documentation in the Windows 2000 DDK.
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. Please see drvrsign.htm for more information on catalog files and driver signing.
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 (not included in this DDK) 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.
Plotter Sample Will Not Compile Under Some System Locales
When the system locale has been set to Korean, Chinese (Taiwan) or Chinese (PRC), the plotter sample, located in src\print\msplot\plotter, will fail to compile, giving errors in brush.c.
Change the code on line 640 from
Buf[Size++] = (BYTE)((bData & Mask) ? '?' : '?');
Buf[Size++] = (BYTE)((bData & Mask) ? 0xDB : 0xB0);
WDM Video Capture Drivers
The Testcap sample WDM video capture driver takes several minutes to load in the AMCap sample program on checked builds due to performance issues in Quartz.dll. The problem does not occur in free builds. Two workarounds are possible: (1) replace Quartz.dll with the free version. (2) Modify AMCap to hold a reference to the SystemDeviceEnumerator while the graph is being constructed. (See code sample below.)
CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC_SERVER,
IEnumMoniker *pEmTmp = 0;
// Release both pCreateDevEnumTmp and pEmTmp after the graph is built.
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.
The sample will not build properly under IA64 due to a missing header file. This will not affect 32 bit compilation.
The DVD sample has some minor problems, menus do not always display properly, highlights are visible over the still movie image, distorted video when doing speed changes and jumping locations. The affected functions are Stop/Pause/Play, FF/RW/Half Speed, Jump to chapter - forward and back, Title and Chapter search.
The src\general\toaster\exe\notify sample has a minor error that prevents a successful build under VC 5.
The file %ntddk%\src\general\toaster\exe\notify\notify.c needs to be updated with the following information:
_inline Display(PWCHAR Format, PWCHAR Str);
_inline VOID Display(PWCHAR Format, PWCHAR Str);
This will be fixed in the next release of the DDK.
A number of samples in the DDK are using an obsolete value in the
KeWaitForSingleObject function. The obsolete value is Suspend for the KWAIT_REASON parameter. The proper values for
KWAIT_REASON are Executive or UserRequest. Please refer to the DDK documentation for additional information on KeWaitForSingleObject.
This will be fixed in next release of the DDK.
Windows 2000 Post-RC1 Behavior Change in IoGetRelatedDeviceObject
A bug in IoGetRelatedDeviceObject was discovered in Windows 2000 RC1 and fixed in RC2. This bug caused IoGetRelatedDeviceObject to behave incorrectly in some cases where the file object represented the underlying storage device and was not known to the file system.
Fixing the bug required a minor change in the behavior of IoGetRelatedDeviceObject. Unfortunately, the change impacts a small number of drivers (primarily file system filter drivers) that called IoGetRelatedDeviceObject directly or indirectly and relied on the incorrect behavior.
When called on a file object that represents the underlying storage device, IoGetRelatedDeviceObject now always returns the highest-level device object in the storage device stack. To obtain the highest-level device object in the file system driver stack, drivers must call IoGetRelatedDeviceObject on a file object that represents the file system's driver stack, and the file system must currently be mounted. (Otherwise, the storage device stack is traversed instead of the file system stack.)
To ensure that the file system is mounted on the storage device, the driver must have specified an appropriate access mask, such as FILE_READ_DATA or FILE_WRITE_ATTRIBUTES, when opening the file. Specifying FILE_READ_ATTRIBUTES does not cause the file system to be mounted. This requirement also applies to drivers that call IoGetDeviceObjectPointer. Such drivers should pass the appropriate access mask value in that routine's DesiredAccess parameter.
Drivers that call IoAttachDevice are also affected by this change. IoAttachDevice opens the file with FILE_READ_ATTRIBUTES and then calls IoGetRelatedDeviceObject. This does not cause a file system to be mounted. Thus a successful call to IoAttachDevice returns the device object of the storage driver, not that of the file system driver.
Updated Windows NT 4.0 Samples
While this DDK does not support driver creation for Windows NT 4.0, Product Support Services (PSS) has updated many of the samples included in the Windows NT 4.0 DDK. These samples can be downloaded from http://support.microsoft.com/support/ddk/ntddk/NTsamples/default.asp. In particular, samples under the general directory demonstrate some of the NT core concepts such as IOCTLs, event synchronization, event logging, memory mapping, IRP cancellation, and queuing techniques. These samples may be useful for developers unfamiliar with Windows NT 4.0 driver development.
Some VDD Samples Require 16-bit Build Tools
The %basedir%\src\vdd\dosioctl\dosapp and %basedir%\src\vdd\dosioctl\dosioctl are 16-bit samples and require a 16-bit version of MASM and a suitable linker.
VDD Sample is a Legacy Driver
The %basedir%\src\vdd\dosioctl\krnldrvr driver does not support Power Management or Plug and Play.
WmiCli Sample Requires MFC to be Installed
To build the %basedir%\src\general\wmicli sample requires that MFC be installed for the sample to build properly.
The Grapher tool will not run without a supported sound card installed.
The SCSIINF tool does not run correctly on Windows NT 4.0.
GenINF is a GUI-based tool that guides the user through the process of creating Windows® 2000 device driver
information (INF) files.
The tool does not create fully valid INF files. However, the skeleton INF files it generates should help developers complete their device driver INF files. Users should review all INF files created by GenINF carefully and modify them as required. Users should expect to add additional INF directives, especially any directives that are device-class-specific or that contain device-class-specific information.
GenINF is located in the <DDKRoot>\Tools subdirectory. Because it is GUI-based, it can be executed from within the Windows 2000 User Interface, or from the Command Prompt. GenINF takes no arguments.
Please check the GenINF release notes for details on usage and limitations.
ChkINF is a Perl script that checks the structure and syntax of Windows 2000 device driver INF files. Results are presented in HTML format, and include a list of the errors and warnings detected in each INF file, with each error and warning shown next to the errant INF file entry. ChkINF includes support for virtually all INF
sections and directives that apply to all classes of devices.
ChkINF is located in the <DDKRoot>\Tools\Chkinf subdirectory, and should be executed from the Command Prompt. Because ChkINF is a Perl script, in order to use the tool, you will need to obtain a Perl interpreter. ChkINF requires
a Perl interpreter that is Version 5.003_07 or greater. ChkINF should work with any version of Perl 5.0 or greater, but has not been tested with any versions before 5.003_07.
Please check the release notes in <DDKRoot>\Tools\Chkinf\Chkinf.htm for details on usage and limitations.
Windows® 2000 DDK Build Environment Changes
The Windows 2000 DDK includes an environment for building drivers that closely matches the internal build environment used to build Windows 2000 drivers at Microsoft®. This environment comes in two types: free and checked.
The free environment is similar to the Microsoft Visual Studio® concept of retail builds, which are optimized for release. The checked environment has no optimization and often has extra tests in the code to catch errors. All drivers should first be written and tested in the checked environment, and then retested in the free environment after they seem to be complete.
The Build tool (Build.exe), which is part of both environments, acts as a front end to a standard compilation tool such as Nmake. Build and the makefiles included in the DDK are customized for creating Windows 2000 drivers. Most drivers do not need to specify their own custom makefile, because a simple makefile that includes the makefile.def in the DDK will suffice. However, to properly set up driver code to compile using Build, you must create a sources file
that specifies values for the environment variables that drive Build's actions. The DDK documents how to create this file plus the
related dirs file.
In past versions of Microsoft DDKs, the objects compiled through the build process often ended up in arbitrary locations. The location was defined by the environment variable TARGETPATH. Usually, the location was set to either $(BASEDIR)\lib\<platform>\Free|Checked
or to Obj\<platform>, where <platform>
could be either I386 or Alpha. The former is confusing to inexperienced users. The latter allowed
the user's checked files to be overwritten by the free ones, and vice
Previously, the common TARGETPATH setting was TARGETPATH=$(BASEDIR)\lib,
which is now explicitly disallowed by the code in makefile.def.
The version of Build included in the Windows 2000
DDK still uses TARGETPATH to place objects created by Build. If
TARGETPATH is set to point to a particular directory, the objects created will
be placed in that directory. The default for TARGETPATH is OBJ, which
is treated by Build as a special token. If TARGETPATH
is set to OBJ, the objects will be
placed in Obj$(BUILD_ALT_DIR)\<platform>.
If the environment variable BUILD_ALT_DIR is undefined, the
default is Obj\<platform>. In
the Windows 2000 DDK, the free environment sets BUILD_ALT_DIR to FRE,
and the checked environment sets the variable to CHK.
The result is that free build objects are placed in Objfre\<platform> and
checked builds are placed in Objchk\<platform>.
This allows both a free and checked version to co-exist and be built from the
same source. Use the variable $(O)
[capital O, not zero] as an easy way to refer to this directory in sources files.
BUILD_ALT_DIR is also appended to the build logs created by
the build -e command. In the DDK
environments, this causes the names of the log files to change as follows.
Free Build Name
Checked Build Name
The DDK environment also emulates this same behavior for the
libraries included in the DDK. Instead of a single Lib\<platform>
directory containing only the free versions of the
libraries, there are now two directories: Libfre and Libchk. This allows the DDK
to include both the free and checked versions of the libraries. The DDK
environment is created using a batch file, setenv.bat, which sets the variables
CRT_LIB_PATH, DDK_LIB_DEST, DDK_LIB_PATH, SDK_LIB_DEST, and SDK_LIB_PATH
correctly for the free or checked environment.
The variable TARGETPATHLIB allows you to specify a different
location than TARGETPATH for .lib and .exp files created for DLLs. When you are
building a DLL, you create the DLL itself. You also create an import library
that other images can use to reference functions exported by your DLL. Setting
TARGETPATH independently from TARGETPATHLIB allows the binary to be kept in the
current directory, while the .lib and .exp files can be shared with other
components. TARGETPATHLIB has no effect on binaries that are not DLLs.
The location of header files has also been changed in the
current DDK. Most headers remain in the $(BASEDIR)\inc directory. However, the
DDK-specific headers are now in $(BASEDIR)\inc\ddk, and the WDM-specific headers are
now in $(BASEDIR)\inc\ddk\wdm. You may need to adjust INCLUDES directives in sources
The following environment variables included in sources
files in the past are now disallowed:
- EXEPROFILEINPUT use NTPROFILEINPUT instead.
These are unneeded, so please remove them from your sources file.
If you find inaccuracies with the DDK, are looking for something not documented in the DDK, or otherwise want to provide feedback, please visit our Windows® 2000 DDK Web site at http://www.microsoft.com/ddk/. The feedback link on this page comes directly to the teams which provide input for these documents. It's your DDK, if you have an issue with it, please let us know.
Top of page
Copyright © Microsoft Corporation 2000