What's New for Plug and Play in the Windows XP DDK

Updated: December 4, 2001

This article describes new and updated Plug and Play samples, tools, and documentation provided in the Windows XP DDK for Microsoft Windows XP RC2. For more detail on any item described in this article, see the readme files for samples and the Windows XP DDK documentation.

The Windows XP DDK is available through MSDN Professional Subscription.

On This Page

  Plug and Play Samples
  Plug and Play Tools
  Important Windows XP DDK Topics

Plug and Play Samples

The Windows XP DDK includes several new and updated Plug and Play samples.

Toaster Sample

%winddk%\src\general\toaster\The Toaster sample is a full sample that provides a starting point for Windows XP/Windows 2000 driver development. It contains annotated code that illustrates the functionality of bus drivers, function drivers, assorted class, device, and bus filter drivers, class installers, and device-specific co-installers for a hypothetical Toaster bus and its devices. For Windows XP, the sample has been updated as follows:

• Fixed known issues in power management.

• Cleaned up the generic filter code.

• Added a WMI event-firing feature to the toaster device function driver.

• Provided a device property page using the DIF_ADDPROPERTYPAGE_ADVANCED DIF code. This property page also demonstrates how to change the friendly name of the device.

• Added code that demonstrates how to display the Power Management tab in Device Manager.

• Provided a sample driver installation package based on Toaster (described in the next section).

Toaster Installation Package Sample

%winddk%\src\general\toaster\toastpkg\The Toaster Installation Package sample provides a comprehensive example of device driver distribution, including the driver package (driver binary, INF file, and catalog), accompanying value-add software application, and Setup program. The sample is structured to demonstrate robust handling of the two primary user scenarios for device installation:

• Installing hardware first. In this scenario, the user initiates device installation by plugging in the hardware. Plug and Play finds the device and initiates an installation for it. The device installation then proceeds using a driver package that is either supplied with the operating system or provided through CD-ROM, the Internet, or some other distribution mechanism.

• Installing software first. In this scenario, the user runs a Setup program (which might be launched as an autorun application when the vendor-supplied CD-ROM is inserted) before plugging in the hardware. This Setup program performs installation activities, including preinstallation of the vendor-supplied driver package, and then prompts the user to insert the hardware. After the hardware is inserted, Plug and Play finds the vendor-supplied driver package that was preinstalled by the Setup program and the installation proceeds as in the hardware-first scenario.

The readme file that accompanies the Toaster Package sample discusses the different approaches that end users take when adding new hardware to their computer, and describes an approach that addresses these scenarios in a consistent, robust manner that works cooperatively with Plug and Play in Windows XP and Windows 2000. It also outlines the mechanisms provided to facilitate additional vendor requirements such as the installation of value-added software.

For additional information about developing custom device driver setup applications, see "Writing a Device Installation Application" in the Windows XP DDK.

MultiOS Sample INF File

%winddk%\src\setup\infs\MultiOS\MultiOS.inf is a sample INF file that illustrates the general structure for using a single INF file to install different device driver binaries on Windows XP, Windows 2000, and Windows 9x (encompassing Windows 98, Windows 98 Second Edition, and Windows Millennium Edition). Although the sample is an INF file for thDevice Installation e Display Setup Class, it contains INF syntax that is common to all device classes. No Display-class-specific information or syntax is used. The sample includes specific INF constructs to demonstrate the following concepts:

• Platform extensions, including consistent usage throughout the INF file

• Installation on multiple platforms from one INF file

• Installation of different local language versions of binaries from one INF file

Many devices are distributed with accompanying media (typically a CD-ROM) that contain drivers targeted at multiple local languages and multiple versions of Windows. The readme that accompanies MultiOS.inf presents one possible structure for organizing such media, so that multiple languages can be supported for Windows XP, Windows 2000, Windows NT 4.0, and Windows 9x.

ClasFilt Sample INF File

%winddk%\src\setup\infs\clasfilt\ClasFilt.inf is a sample INF file that demonstrates the installation of a class filter driver that will be applied as an upper or lower filter to all devices of a specific device setup class. INF files based on ClasFilt.inf can be installed either manually or programmatically. Users can install INF files based on ClasFilt.inf manually by right-clicking on the designated INF file and selecting "Install" from the pop-up menu. A device installation program can install the class filter driver programmatically by calling the
InstallHinfSection API, which reads the indicated INF file and installs the driver listed in the indicated DefaultInstall section.

DevCon Tool Source Code

%winddk%\src\setup\devcon\The DevCon tool is a command-line utility that acts as an alternative to Device Manager. The sample code for DevCon demonstrates how to enable, disable, restart, update, remove and query one or more devices. The sample demonstrates how to use SetupAPI and CfgMgr32 APIs effectively together to enumerate devices and perform device operations. Running "devcon help" provides a list of commands along with short descriptions of what each command does. "devcon help <command>" gives more detailed help on that command. Refer to the readme for DevCon for a description of some of the more interesting functions and the APIs they use. DevCon is also available in binary form in the Windows XP DDK.

CoCpyINF Source Code

%winddk%\src\setup\cocpyinf\CoCpyINF is a sample co-installer that can be used to install additional device INF files on the target system during a device installation. CoCpyINF interprets CopyINF directives in a [
DDInstall] section in an INF file. The sample demonstrates using a co-installer to perform processing after a device has been installed, parsing the INF section that is being used for the installation, and the use of the SetupCopyOEMInf, SetupGetInfInformation, SetupQueryInfOriginalFileInformation and SetupDiGetActualSectionToInstall APIs. Note that the CopyINF directive is native in Windows XP. CoCpyINF is also available in the DDK as a redistributable binary, for vendors to use to support the CopyINF directive on target Windows 2000 systems.

 Top of page

Plug and Play Tools

The Windows XP DDK provides several tools that developers can use to test Plug and Play in drivers and installation files.

Driver Verifier

%windir%\system32\verifier.exeDriver Verifier is a tool that monitors kernel-mode drivers and graphics drivers to verify that they are not making illegal function calls or causing system corruption. It can perform a large number of checks on these drivers, as well as subject them to a variety of stresses and tests to flush out improper behavior.

Driver Verifier may be used on any number of drivers simultaneously, or on one driver at a time. It has various options that can be enabled or disabled. This allows the driver developer to put their driver through heavy stresses or through a more streamlined test.

Driver Verifier is available in every free and checked build of Windows. Use the Verifier utility to activate and monitor Driver Verifier. There are two ways to use the Verifier utility. The executable name verifier can be typed in an MS-DOS Command Prompt window, followed by at least one command-line parameter. Any output generated will be displayed in the same window. Alternately, the command verifier can be entered at a Command Prompt with no parameters, or the user can double-click on the icon associated with verifier.exe. This causes a graphical user interface named Driver Verifier Manager to appear.

Driver Verifier is available in Windows XP and Windows 2000. More information on Driver Verifier can be found in the Windows XP DDK Documentation.

ChkINF

%winddk%\tools\chkinf\ChkINF is a Perl script that checks the structure and syntax of Windows XP and Windows 2000 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 has been significantly improved for the Windows XP release and now includes support for all INF sections and directives that apply to all system-defined device setup classes. The tool also supports the checking of INF files used for installing file system filter drivers. Note that a Perl interpreter must be installed in order to use the tool. The latest version of ChkINF is included in release 10.0 of the Windows Hardware Compatibility test kit, which is used for "Designed for Windows" Logo testing.

DevCon

%winddk%\tools\devcon\The DevCon tool provides a text-mode device console. DevCon is a command line utility that acts as an alternative to Device Manager. The tool allows individual devices or groups of devices to be enabled, disabled, restarted, updated, removed and queried. DevCon provides information that is relevant to the driver developer and thus is not available in Device Manager. DevCon has been designed for use on Windows XP and Windows 2000. The source code for DevCon is provided in the Windows XP DDK for private use.

GenINF

%winddk%\tools\geninf\GenINF is a GUI-based tool that guides driver developers through the process of creating Windows XP and Windows 2000 device driver INF files. GenINF can be used to create multi-architecture INF files (x86/ia64). Developers using GenINF should review all INF files created by the tool and modify them as required.

Plug and Play Driver Test

%winddk%\tools\pnpdtest\The Plug and Play Driver Test tool provides driver developers with a tool that exercises various Plug and Play related code paths in a driver and its user-mode components. If used in conjunction with the Driver Verifier, driver developers can feel more confident that their code is performing properly. This tool is only for use on Windows XP and Windows 2000.

Although using this tool forces a driver to handle almost all the PNP IRPs, three areas are stressed specifically Removal, Rebalance, and Surprise Removal. The test provides a mechanism to test each of these separately or all together for stress. This is accomplished using a combination of user-mode API calls through the test application and kernel-mode API calls through an upper filter driver.

SetupAPI Logging

The Windows Setup and Device Installer Services, also known as SetupAPI, include the Windows functions that control Setup and device installation. As Setup proceeds, the general Setup functions (SetupXxx functions) and device installation functions (SetupDiXxx functions) create a log file that provides useful information for troubleshooting device installation problems.

SetupAPI writes log entries to the file %systemroot%\setupapi.log, which is a plain text file. To reset the log, rename or delete the file.

Developers can control the amount of information that is written to the SetupAPI log, either for all Setup applications or for individual Setup applications. To change the level of information written to the SetupAPI log for all Setup applications, create (or modify) the following registry value:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Setup\LogLevel  

By setting this value developers can choose the level of errors that are logged, modify the verbosity of logging, or turn off logging. Information can be logged to a debugger as well as to the log file.

For more information, see "Using SetupAPI Logging" in the Windows DDK documentation.

 Top of page

Important Windows XP DDK Topics

This section describes significant topics related to Plug and Play in the Windows XP DDK documentation.

Custom Setup Applications

Device Installation > Design Guide > Writing a Device Installation Application

In order to provide the best possible experience for their users, many vendors provide a setup application for installing device drivers and value-add software. The DDK topic entitled "Writing a Device Installation Application" provides guidance for developing device setup applications, including handling different usage scenarios properly and using the appropriate APIs to integrate the installation with Windows Plug and Play. The Toaster Package sample described earlier in this article provides a sample custom setup application.

Co-installers

Device Installation > Design Guide > Writing a Co-Installer

A co-installer is a DLL that assists in device installation. Co-installers are called by SetupAPI as "helpers" for class installers. For example, a vendor can provide a co-installer to write device-specific information that cannot be handled by the INF file to the registry. The DDK Topic "Writing a Co-installer" discusses co-installer functionality, operation, and interfaces. In addition, co-installer registration and the proper handling of DIF codes by co-installers are discussed.

Troubleshooting

Device Installation > Design Guide > Troubleshooting Device Installation

The topic entitled "Troubleshooting Device Installation" provides information for troubleshooting driver installation issues. In addition to discussing SetupAPI logging as described earlier in this article, this topic describes how to leverage Device Manager to the driver developers best advantage. The Device Manager Details Tab is discussed, as well as instructions for viewing hidden or non-present devices. A full list of Device Managers problem codes is also included.

INF Reference

Device Installation > Reference > INF File Sections and Directives

The Windows XP DDK documentation includes a full reference for INF file syntax. The reference includes a discussion of the general syntax rules for INF files, summaries of INF file sections and directives, and detailed information on each individual section and directive.

 Top of page