Driver Verifier

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.

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.

Installation Issues

Dirs Files

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 directory).

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).

Compiler Notes

Visual C++ 6.0 requires Visual C++ 6.0 Service Pack 2 (or greater), available from http://msdn.microsoft.com/visualc/downloads/updates.asp.

Visual C++ 5.0 requires Visual C++ 5.0 Service Pack 3 (or greater), available from http://msdn.microsoft.com/visualc/downloads/updates.asp.

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: importlib(STDTYPE_TLB)

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:

importlib("STDTYPE_TLB")

Then save your changes.

Debugging

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.

WDM 1.0

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.

Sample Issues

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) ? '?' : '?');

to this:

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.)

 
	ICreateDevEnum *pCreateDevEnumTmp;
	CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC_SERVER,
					 IID_ICreateDevEnum, (void**)&pCreateDevEnumTmp);
	IEnumMoniker *pEmTmp = 0;
	if(pCreateDevEnumTmp)
	{
		pCreateDevEnumTmp->CreateClassEnumerator(
			CLSID_VideoInputDeviceCategory,
			&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.

KAnalyze

The sample will not build properly under IA64 due to a missing header file. This will not affect 32 bit compilation.

DvdTs

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.

Toaster

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:

Change:

_inline Display(PWCHAR Format, PWCHAR Str);

to:

_inline VOID Display(PWCHAR Format, PWCHAR Str);

This will be fixed in the next release of the DDK.

KeWaitForSingleObject

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.

Affected samples:

%basedir%\src\input\kbdclass
%basedir%\src\input\mouclass
%basedir%\src\kernel\parclass
%basedir%\src\kernel\parport
%basedir%\src\kernel\serenum
%basedir%\src\network\mdis\e100bex
%basedir%\src\smartcrd\bulltlp3
%basedir%\src\storage\class\cdrom
%basedir%\src\storage\class\disk
%basedir%\src\storage\fdc\3mode\fdc
%basedir%\src\storage\fdc\3mode\fdc.2
%basedir%\src\storage\fdc\3mode\flpydisk
%basedir%\src\storage\fdc\fdc
%basedir%\src\storage\flpydisk
%basedir%\src\storage\filters\cdaudio
%basedir%\src\wdm\acpi\ec
%basedir%\src\wdm\hid\gameenum
%basedir%\src\wdm\hid\hidgame
%basedir%\src\wdm\scancam\scsiscan
%basedir%\src\wdm\usb\bulkusb
%basedir%\src\wdm\usb\isousb
%basedir%\src\wdm\videocap\atiwdm

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.

Tool Issues

Grapher

The Grapher tool will not run without a supported sound card installed.

SCSIINF

The SCSIINF tool does not run correctly on Windows NT 4.0.

GenINF

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

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.