Requirements for Driver Packages That Are Used with the Driver Install Framework (DIFx) Tools - 1
Requirements for Driver Packagesthat are Used with the Driver Install Framework (DIFx) Tools
WinHEC 2004 Version - April 14, 2004
Abstract
This paper defines requirements for driver packages that are used with Microsoft® Windows® Driver Install Frameworks (DIFx) version 1.0 tools. The DIFx tools are supported by Microsoft Windows2000 and later.
Contents
Introduction
Generic DIFx Driver Package Requirements
DIFx Driver Package Requirements for File System Drivers and File-System Filter Drivers
DIFx Driver Package Requirements for Class Filter Drivers
DIFx Driver Package Requirements for Plug and Play Device Drivers
DIFx Driver Package Requirements for Network Drivers
DIFx Driver Package Requirements for Kernel Service Drivers
DIFx Driver Package Requirements for Export Drivers
Call to Action and Resources
Disclaimer
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.
This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.
Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred.
© 2004 Microsoft Corporation. All rights reserved.
Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.
Introduction
Microsoft® Windows® Driver Install Frameworks (DIFx) is the latest technology under development to ease the creation of high-quality driver packages, customize the installation of driver packages, allow the installation of driver packages in combination with application software, and to use the standard Windows APIs and installation tools. This paper defines requirements for driver packages that are used with DIFx version 1.0 tools. The DIFx tools are supported by Microsoft Windows2000 and later versions.
DIFx tools support the following driver types:
- File system drivers and file-system filter drivers.
- Class filter drivers.
- Plug and Play device drivers.
- Network drivers for the following device setup classes: Net, NetClient, NetTrans, and NetService.
- Kernel service drivers that implement a kernel-mode service that is managed by the Service Control Manager (SCM), but the service is not associated with a device in the device tree.
- Export drivers that implement a kernel-mode module that is not associated with a SCM-managed service or a device in the device tree.
The DIFx tools require that all the supported driver types comply with the generic requirements listed in “Generic DIFx Driver Package Requirements” later in this paper. In addition, the DIFx tools require that each driver type comply with additional driver-type-specific requirements. For information about the requirements for a specific driver type, see the corresponding topic later in this paper. For example, for requirements that are specific to file system drivers and file-system filter drivers, see "DIFx Driver Package Requirements for File System Drivers and File-System Filter Drivers;" for requirements that are specific to class filter drivers, see "DIFx Driver Package Requirements for Class Filter Drivers," and so on.
For more information about Driver Install Frameworks, see "Driver Install Frameworks" in the Microsoft Windows Driver Development Kit (DDK) and “Driver Install Frameworks Tools” at
Generic DIFx Driver Package Requirements
The Microsoft® Windows® Driver Install Frameworks (DIFx) tools require that all supported driver packages comply with the following requirements:
- General driver package requirements. For information about general driver package requirements, see “Providing a Driver Package” and “Device Installation Overview” in the Microsoft Windows Driver Development Kit (DDK).
- Driver packages must be signed with a Windows Hardware Quality Labs (WHQL) signature, an Authenticode signature, or a test signature. For information about driver signing, see “Driver Signing” in the DDK. Additionally, see the “Using Authenticode to Digitally Sign Driver Packages” white paper at and “Driver Signing for Windows” at
- For all driver packages except Plug and Play device driver packages, the INF Version section of a driver package must include a DriverPackageType entry that specifies the driver package type. If a DriverPackageType entry is not present, the default driver package type is a Plug and Play device driver.
The DIFx tools do not require that a Plug and Play device driver package include a DriverPackageType entry to ensure that the tools support existing Plug and Play device driver packages. However, Microsoft recommends that the INF Version section of a new Plug and Play device driver package also include a DriverPackageType entry. If a DriverPackageType entry is present, but does not specify one of the supported driver package types listed below, the DIFx tools will not install the driver package.
A DriverPackageType entry has the following format in an INFVersion section (wherePackageTypeisone of the strings that is described in the following table):
[Version]
…
DriverPackageType=PackageType
PackageTypestring / Corresponding driver package typeClassFilter / Class filter driver
FileSystem / File system driver
FileSystemFilter / File-system filter driver
KernelModule / Export driver
KernelService / Kernel service driver
Network / Network driver
PlugAndPlay / Plug and Play device driver
The INF Version section of a driver package includes a CatalogFile entry that specifies the file name of the catalog file that is used as the digital signature for the driver package.
The following example shows a DriverPackageType entry and a CatalogFile entry for a fictitious Plug and Play toaster device:
[Version]
…
DriverPackageType=PlugAndPlay
CatalogFile=toaster.cat
…
For information about specific DIFx requirements for each supported driver package type, see the corresponding topic later in this paper.
For general information about INF files, see “General Guidelines for INF Files” in the DDK, and for information about specific INF file entries, see "INF File Sections and Directives" in the DDK.
Note
When the DIFx tools are used to install driver packages on a user's computer, they will only install signed driver packages. However, to test the installation of the driver packages you can configure the DIFx tools to install unsigned driver packages. To configure the DIFx tools to install unsigned driver packages, attach a kernel debugger to the system and set the environment variable _DFX_INSTALL_UNSIGNED_DRIVER to 1. In this test configuration, the DIFx tools do not verify that a package is signed and do not check for the presence of a catalog file for the package.
DIFx Driver Package Requirements for File System Drivers and File-System Filter Drivers
The Microsoft® Windows® Driver Install Frameworks (DIFx) tools require that the driver package for a file system driver or a file-system filter driver comply with the following requirements:
- The requirements listed in “Generic DIFx Driver Package Requirements” earlier in this paper.
- General requirements that apply to all file system driver packages and file-system filter driver packages. For general requirements that apply to all file system driver packages and file-system filter driver packages, see the Windows Installable File System Kit (IFS). For information about IFS, go to
- The driver package must support only one service.
In addition to the INF file requirements that are documented in the IFS, the DIFx tools require that you include the following entries in the INFVersion section of theINF file:
- A CatalogFile entry that specifies the name of the catalog file that is used as the digital signature for the driver package.
- For a file system driver, a DriverPackageType entry that specifies that the driver package type is FileSystem. For example:
[Version]
…
DriverPackageType=FileSystem
…
- For a file-system filter driver, a DriverPackageType entry that specifies that the driver package type is FileSystemFilter. For example:
[Version]
…
DriverPackageType=FileSystemFilter
…
Finally, the DIFx tools also require that you include an INF SourceDisksNamesand SourceDisksFiles section within the INF file that specify the source and destination of the files that must be copied to a computer.
DIFx Driver Package Requirements for Class Filter Drivers
The Microsoft® Windows® Driver Install Frameworks (DIFx) tools require that the driver package for a class filter driver comply with the following requirements:
- The requirements listed in “Generic DIFx Driver Package Requirements” earlier in this paper.
- General requirements that apply to all class filter drivers. For general information that applies all class filter drivers, see “Filter Drivers” and “Installing a Filter Driver” in the Microsoft Windows Driver Development Kit (DDK). For information about INF files that install class filter drivers, see the clasfilt sample located in the src\setup\infs\clasfilt directory of the DDK.
- The driver package must support only one service.
In addition to the requirements for class filter INF files that are documented in the clasfilt sample, DIFx requires that you include the following entries in the INF Version section of the INF file:
- A CatalogFile entry that specifies the catalog file that is used as the digital signature for the driver package.
- A DriverPackageType entry that specifies that the driver package type is ClassFilter. For example:
[Version]
…
DriverPackageType=ClassFilter
…
DIFx Driver Package Requirements for Plug and Play Device Drivers
The Microsoft® Windows® Driver Install Frameworks (DIFx) tools require that the driver package for a Plug and Play device driver comply with the following requirements:
- The requirements listed in “Generic DIFx Driver Package Requirements” earlier in this paper.
- General requirements that apply to all Plug and Play device drivers. For information that applies to Plug and Play device drivers, see “Device Installation Overview” in the Microsoft Windows Driver Development Kit (DDK).
In addition to the general INF file requirements for a Plug and Play device driver that are discussed in “Device Installation Overview” in the DDK, the DIFx tools require that you include a CatalogFile entry in the INF Version section of the INF file that specifies the catalog file that is used as the digital signature for the driver package.
Although the DIFx tools do not require it, Microsoft recommends that you also include a DriverPackageType entry that specifies that the driver package type is PlugAndPlay. For example:
[Version]
…
DriverPackageType=PlugAndPlay
…
DIFx Driver Package Requirements for Network Drivers
The Microsoft® Windows® Driver Install Frameworks (DIFx) tools require that the driver package for a network driver comply with the following requirements:
- The requirements listed in “Generic DIFx Driver Package Requirements” earlier in this paper.
- General requirements that apply to all network drivers. For information about requirements that apply to all network drivers, see “Using the Network Driver Design Guide” in the Microsoft Windows Driver Development Kit (DDK).
DIFx supports network drivers in the following device setup classes: Net, NetTrans, NetClient, and NetService. These classes include network drivers that support protocols, clients, and service providers. Examples of these types of drivers include Network Device Interface Specification (NDIS) Intermediate Miniport (IM) drivers, NDIS protocol drivers, and print server drivers.
For information about network INF files, see “Creating Network INF Files” in the DDK, as well as the following sample network drivers:
- The DDK passthru sample located within the src\network\ndis\passthru directory includes a sample INF file for an NDIS IM driver.
- The DDK ndisprot sample located within the src\network\ndis\ndisprot directory includes a sample INF for an NDIS protocol driver.
In addition to the general network driver INF file requirements that are discussed in “Using the Network Driver Design Guide” in the DDK, the DIFx tools require that you include the following entries in the INFVersion section of the INF file:
- A CatalogFile entry that specifies the catalog file that is used as the digital signature for the driver package.
- A DriverPackageType entry that specifies that the driver package type is Network. For example:
[Version]
…
DriverPackageType=Network
…
The DIFx tools also require that you include an INF SourceDisksNamesand SourcesDisksFiles section within the INF file that identify the location of the source files.
Finally, if a driver package is designed for an NDIS IM driver which includes a miniport driver INF file and a protocol INF file, the miniport driver INF file must be located in a different directory than the protocol INF file. For Microsoft Windows2000ServicePack2(SP2) and later versions, use anINF CopyINFdirective in the protocol INF file to copy the miniport driver INF file. The CopyINF directive must specify the directory and file name of the miniport driver INF file. For more information about copying the miniport driver INF file on Windows2000 and later versions, see “Installing Intermediate Drivers” in the DDK and the passthru sample located in the DDK within the src\network\ndis\passthru directory.
DIFx Driver Package Requirements for Kernel Service Drivers
The Microsoft® Windows® Driver Install Frameworks (DIFx) tools require that the driver package for a kernel service driver comply with the following requirements:
- The requirements listed in “Generic DIFx Driver Package Requirements” earlier in this paper.
- General requirements that apply to all kernel service drivers. For general information about kernel service drivers, see “INF DefaultInstall Section” in the Microsoft Windows Driver Development Kit (DDK) and “Service Control Manager” in the Microsoft Windows Platform SDK.
- The driver package must support only one service.
In addition to the general requirements for a kernel service driver INF file, the DIFx tools require that the INF Version section of the INF file include the following entries:
- A Signature entry that specifies $Windows NT$.
- A CatalogFile entry that specifies the catalog file that is used as the digital signature for the driver package.
- A DriverPackageType entry that specifies that the driver package type is KernelService. For example:
[Version]
…
DriverPackageType=KernelService
…
Finally, the DIFx tools also require that you include the following sections in the INF file:
- AnINF DefaultInstall and DefaultInstall.Services section to install the kernel service driver.
- An INFDestinationDirs, SourceDisksNames, and SourceDisksFiles section to specify the source and destination of the files that must be copied to a computer.
DIFx Driver Package Requirements for Export Drivers
The Microsoft® Windows® Driver Install Frameworks (DIFx) tools require that the driver package for an export driver comply with the following requirements:
- The requirements listed in “Generic DIFx Driver Package Requirements” earlier in this paper.
- General requirements that apply to all export drivers.For general information about export drivers, see “Creating Export Drivers” in the Microsoft Windows Driver Development Kit (DDK).
Installing an export driver typically involves copying files to the system, and in some cases, modifying registry keys or registry entry values.