Device Driver INF Guidelines for Windows XP
Device Driver INF Guidelines for Windows XP
June 30, 2006 - ARCHIVE
Abstract
This paper collects articles about creation and management of INF files for device driver installation for the Microsoft® Windows® XP and Microsoft Windows Server® 2003 family of operating systems. This paper provides an archive of information published in 2001–2003 and has not been updated or corrected.
For current information for Microsoft Windows Vista™ and later versions of Windows operating systems, refer to the Windows Driver Kit.
The current version of this paper is maintained on the Web at:
Contents
ChkINF Enhancements for Windows XP 3
Introduction to INF File Syntax Checker 3
ChkINF Enhancements 3
Device Class-Specific Modules for ChkINF 4
ChkINF Support for Include and Needs Directives 6
Running the ChkINF Tool 6
ChkINF Output 7
ChkINF Limitations 7
ChkINF and the Windows Logo Program 7
Resources for ChkINF 7
INF Platform Extension for 64-bit Versions of Windows XP 8
Introduction to INF Platform Extensions 8
Using the .ntia64 Platform Extension 8
Backward Compatibility 9
Resources for INF Files for 64-bit Windows XP 9
Operating-System Versioning for Drivers under Windows XP 9
Background for Operating-System Versioning 10
Windows XP Changes to the INF [Manufacturer] Section 10
About the [Manufacturer] Section 11
About the TargetOSVersion 11
About the [Models] Sections 12
Using Operating System-Versioning Decorations 12
Excluding a Specific Operating System Version 12
Selecting the Most Appropriate TargetOSVersion 12
Windows XP Driver Ranking and Operating System-Version Decorations 13
Examples of Decorated [Models] Sections 14
Example 1: 15
Example 2: 15
Resources for Driver Versioning 15
Multifunction Device Installation and Windows XP 16
Background for Multifunction Device Installation 16
INF CopyINF Directive 16
Copying INFs 17
Sample Co-installer for Copying INF Files 18
Resources for Multifunction Devices 18
Disclaimer
This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.
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.
© 2001–2006 Microsoft Corporation. All rights reserved.
Microsoft, MS-DOS, Win32, Windows, Windows NT, Windows Server, and Windows Vista 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.
ChkINF Enhancements for Windows XP
For Microsoft® Windows® XP, the ChkINF tool has been enhanced to support additional device classes and to handle new platform extensions, INF sections, and directives. This article describes these capabilities.
This article was previously published at this URL:
Introduction to INF File Syntax Checker
ChkINF is a Perl script that checks the structure and syntax of Windows 2000 and Windows XP 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.
This article describes the capabilities of ChkINF, emphasizing enhancements provided under Windows XP. ChkINF is provided in the Windows DDK.
ChkINF Enhancements
For Windows XP, ChkINF provides new support, including:
• Handling new INF sections and directives related to new Windows XP features, including:
• ChkINF support for specific directives, as summarized later in this section.
• New platform extension for Intel-Itanium-based system: .ntIA64.
• Operating-system versioning for drivers through decorated [Models] sections.
• Multifunction device installation improvements through the new CopyINF directive.
• Complete information for these changes is provided in the Windows DDK and in the following sections:
Multifunction Device Installation and Windows XP
Operating-System Versioning for Drivers under Windows XP
INF Platform Extension for 64-bit Versions of Windows XP
• Providing device class-specific support for all device classes except Printers, as listed in the following table. Highlighted device classes indicate the classes for which device class-specific support was provided under Windows 2000.
Device Classes Supported in ChkINF under Windows XP
|Device |Class | |Device |Class |
|1394 Host Bus Controllers |1394 | |Monitors |Monitor |
|Battery Devices |Battery | |Multifunction Devices |Multifunction |
|CD-ROM Drivers |CDROM | |Multimedia |Media |
|Disk Drives |DiskDrive | |Multi-port Serial Adapters |MultiportSerial |
|Display Adapters |Display | |Network Adapters |Net |
|Dot4 Devices |Dot4 | |Network Clients |NetClient |
|Floppy Disk Controllers |FDC | |Network Service |NetService |
|Floppy Disk Drives |FloppyDisk | |Network Transport |NetTrans |
|Hard Disk Controllers |HDC | |PCMCIA Adapters |PCMCIA |
|Human Input Devices |HIDClass | |Ports - COM & LPT ports |Ports |
|Imaging Devices |Image | |SCSI and RAID Controllers |SCSIAdapter |
|IrDA Devices |Infrared | |Smart Card Readers |SmartCardReader |
|Keyboards |Keyboard | |Storage Volumes |Volume |
|Medium Changers |MediumChanger | |System Devices |System |
|Memory Technology Drivers |MTD | |Tape Drives |TapeDrive |
|Mice |Mouse | |USB |USB |
|Modems |Modem | | | |
Filesystem filter modules are also supported in ChkINF for the following classes:
ActivityMonitor, AntiVirus, CFSMetaDataServer, Compression, ContentScreener, ContinuousBackup, CopyProtection, Encryption, FSFilterSystem, HSM, Infrastructure, OpenFileBackup, QuotaManagement, Replication, SecurityEnhancer, Undelete.
ChkINF does not check device-specific INF extensions for Printer INF files (class = Printer). See the discussion on printers in the Device Classes with INF Extensions later in this paper.
Note: ChkINF does not support Windows 98 or Windows Millennium Edition (Windows Me) INF files.
Device Class-Specific Modules for ChkINF
ChkINF handles device class-specific modules as follows:
1. Examines the [Version] section (specifically the ClassGUID value) and determines the device setup class.
2. If a class-specific module for that device class exists, loads it to handle device class-specific sections and directives.
Otherwise, the generic module is loaded.
The generic module, first provided with the Windows 2000 version of ChkINF, has no knowledge of device class-specific information in the INF file. Therefore, it logs more generic error messages, such as Warning Error 2202 Unrecognized directive: %s (may be device class specific).
In the version provided for use with Windows XP, ChkINF includes a basic module for each system-defined device class (except for Printers). These modules do the following:
• Check usage for new INF extensions and sections defined in Windows XP.
• Allow ChkINF to provide a specific "unrecognized directive" error for each device class.
The existing generic device-class module will only detect that the directive is not a general directive common across all device classes.
Each basic class-specific module is named "%Class%.pm" and includes class-specific versions of the generic error and warning messages. The generic module has been retained for nonsystem-defined device classes, such as device classes defined by vendors.
Device Classes without INF Extensions The following device classes have no device-specific extensions to the INF definition, but are supported using basic modules:
|Battery |Hard Disk Controllers |Ports |
|CD-ROM |HID |SCSI/RAID |
|Disk Drivers |IEEE 1394 |Smart Card Readers |
|Dot4 |Memory Technology Drivers |Storage Volumes |
|Floppy Disk Controllers |Multifunction |System Devices |
|Floppy Disk Drives |Multi-port Serial Adapters |USB |
| |PCMCIA | |
Device Classes with INF Extensions The following device classes have device class-specific extensions to the INF definition.
Multimedia Multimedia includes the Audio, GamePort, Motion Video, and Video Capture technology areas. Complete information about these extensions is provided in the Windows DDK.
The AddInterface directive for audio adapter interfaces is used to assign a unique reference string to each interface, which the adapter driver can use to distinguish between instances of each interface class.
Keyboard and Mouse The INF extensions for each of these classes are limited to the following extensions, which apply to both the Keyboard and Mouse class installers, except as noted.
• MigrateToDevnode
This is intended for legacy (Microsoft Windows NT® 4.0) drivers that are now Plug and Play and power-aware drivers. The format is as follows:
ServiceName = value-name[,value-name] ...
The class installer will open the following key: HKLM\ System\ CurrentControlSet\ Services\ ServiceName\ Parameters
Then the class installer will copy each value-name specified in the list to the device node of the device being installed before the device stack is started. The type and data of each value-name can be any valid registry type. The value-names listed will not be deleted from the Parameters key upon completion.
• SharedDriver
This is used for PS/2-compatible keyboards and mouse devices only. The format is as follows:
[ControlFlags] SharedDriver=%DDInstall Section%,%Warning Text String%
• PS2_Inst.NoInterruptInit.Bioses
This is intended for use only with PS/2-compatible mouse devices. If the PS/2 controller on the system cannot handle the initialization of the PS/2-compatible mouse by using the device interrupt, enter the name of the machine BIOS. The mouse class installer retrieves the name of the machine BIOS that the value named "SystemBiosVersion" under the key HKLM\Hardware\Description\System. If a match is found, the INF commands specified in the section [PS2_Inst.NoInterruptInit] are executed.
Printer
The extensive INF extensions for printers are documented in the
Windows DDK.
ChkINF checks any INF syntax in Printer INF files that is common to all INF files.
Medium Changers
The INF extensions for medium changers are limited to MC_EventLog_Inst.
This is an AddReg section that defines the entries for event logging. For a sample usage, see Mchgr.inf in Windows XP.
Network Client
Network Service
Network Transport
The extensive INF extensions for these classes are documented in the Windows DDK.
Tape Drives
The INF extensions for tape drives are limited to USEINFDEVICEDESC.
This directive is TapeDrive class-specific and directs the tape class installer to not apply its default behavior of storing the enumerator-reported device description into the FriendlyName property. This causes Windows 2000 and Windows XP to display the tape drive with its INF-specific device description instead of the description retrieved from the hardware. For example, CompanyA can use this in an INF file to cause its tape drive to be displayed as "CompanyA Tape Drive" instead of the SCSI inquiry data-based "IHV Tape Drive" description.
ChkINF Support for Include and Needs Directives
For accurate checking of sections included from other INF files by way of the Include and Needs directives, ChkINF must be run on the target platform, including:
• Windows 2000
• Windows 2000 Datacenter Server
• All versions of Windows XP and Microsoft Windows Server® 2003
This limitation is a direct result of the state of the INF files in each platform. For example, many INF files have been modified or removed for the Windows 2000 Datacenter release. Accurate parsing and verification of included INF files is only feasible when ChkINF is run on the target platform.
Running the ChkINF Tool
Note: Because ChkINF is a Perl script, to use the tool you must obtain a Perl interpreter. ChkINF requires a Perl interpreter that is Version 5.003_07 or later. ChkINF should work with Perl 5.0 or any later version, but has not been tested with versions earlier than 5.003_07.
ChkINF is located in the \Tools\Chkinf subdirectory and should be run from the command prompt. A batch file, ChkINF.bat, is provided for smooth execution. ChkINF takes the following arguments:
ChkInf[.bat] /L [/B] [/DC ]
|Switch |Description |
| |FileName | Wildcard List | DirectoryName where: |
| |"FileName" is the name of a single INF file. |
| |"Wildcard List" is any Microsoft MS-DOS® wildcards, as in "net*.inf". ChkINF automatically |
| |expands wildcards and checks all applicable INF files. |
| |"DirectoryName" subdirectory is the name of a subdirectory. ChkINF checks all INF files in |
| |the DirectoryName subdirectoy. |
|/L |Write a Windows NT log file named . |
|/B |Launch default browser and display results. |
|/LO |Verify files copied (CopyFiles) against Layout.inf. |
|/DC |Use device class when checking INFs. The only Device Class option currently |
| |supported by the /DC argument is the NOFAX option. |
|/DC NOFAX |Do not check any Fax keys present in Modem INF files only. |
ChkINF Output
Under Windows XP, there are no changes to the ChkINF logging functionality, which is independent of the Windows system Event Logger.
At the end of the checking process, ChkINF produces three types of files that are saved into the subdirectory \Htm, located off the directory from which ChkINF is invoked:
• Summary.htm: A single HTML file that lists all of the INF files that were checked and displays the number of errors and warnings detected in each INF file. The name of each INF file is linked to the respective .htm file.
• An optional Windows NT Log file.
• .htm: A results file produced for each checked INF file, showing the following:
• Errors: A list of the errors found in the INF file, along with the error message and the line in the INF file where it was detected. Each error includes a link to its location in the Annotated INF (described later in this list).
• Warnings: A list of the warnings detected in the INF file, along with the warning message and the line in the INF file where it was detected. Each warning includes a link to its location in the Annotated INF.
• Annotated INF: The complete source for the INF file, with the warning and error messages displayed adjacent to the line where the warning or error was detected.
ChkINF Limitations
In addition to the information provided earlier in this paper, the following limitations apply for ChkINF:
• ChkINF does not check the registry keys set by an INF file. There is no guarantee that an INF file that passes ChkINF with no errors will function correctly.
• ChkINF warns for any sections that are not referenced by a directive elsewhere in the INF file. This is a change from previous versions of the tool, which reported errors for unreferenced sections.
• ChkINF does not support Windows 98 or Windows Me INF files. ChkINF will not accurately check INF structure and syntax that is specific to Windows 98/Me INF files.
• ChkINF does not support Unicode. To run ChkINF on a Unicode INF file, first save the file as an ASCII text file.
Microsoft neither endorses nor recommends any specific Perl interpreters. ChkINF has been tested with the following Perl interpreters:
• GNU Perl 5.005_02 compiled for Microsoft Win32®
• GNU Perl 5.6.0 compiled for Win32
• Perl for Win32 5.003_07 from ActiveState Tool Corp
ChkINF and the Windows Logo Program
The Hardware Compatibility Tests (HCTs) for Windows 2000 and Windows XP include ChkINF as a required test.
The inclusion of the ChkINF tool is intended to help IHVs and OEMs develop device installations that adhere more closely to the Windows Plug and Play definition and provide a seamless experience for users.
Resources for ChkINF
Driver developers should test INFs with the ChkINF functionality in the Windows XP operating system.
All aspects of driver installation, including using the ChkINF tool for testing, are documented in the Windows DDK, together with sample INF files. ChkINF is located in the \Tools\Chkinf subdirectory and should be run from the command prompt. A batch file, ChkINF.bat, is provided for smooth execution.
For additional information about specific implementations of INF files and the ChkINF tool, see:
INF Platform Extension for 64-bit Versions of Windows XP
Multifunction Device Installation and Windows XP
INF Platform Extension for 64-bit Versions of Windows XP
Windows XP includes versions that run on Intel Itanium-based servers and workstations. To support the installation of device drivers on both 32-bit and 64-bit systems, the SetupAPI component and the INF file definition in Windows XP have been modified to handle a new platform extension in INF files.
This article describes the INF file changes that are required to support the installation of device drivers on Itanium-based systems.
This article was previously published at this URL:
Introduction to INF Platform Extensions
To support installation of device drivers on both 32-bit and 64-bit systems, modifications have been made in the Windows XP operating system. Specifically, the SetupAPI component and the INF file definition have been modified to handle a new platform extension in INF files.
These modifications allow for the installation of 64-bit and 32-bit drivers from the same INF file; they also prevent users from installing the wrong driver on the wrong platform.
For developers who are creating drivers and installation routines to support the installation of drivers on Itanium-based systems, only minimal changes are required to the INF file definition, as described in this article.
Using the .ntia64 Platform Extension
On Itanium-based platforms, Windows XP will install only 64-bit kernel-mode drivers; 32-bit kernel-mode drivers are not allowed. Also, only 64-bit class installers and co-installers can be used; 32-bit class installers and co-installers will not run.
To support this, SetupAPI has been updated to recognize [SourceDisksNames] and [SourceDisksFiles] sections in INF files that include the new .ia64 decoration. The [SourceDisksNames] and [SourceDisksFiles] sections decorated with .ia64 are used for installing the driver packages on Itanium-based platforms only.
All other standard INF sections and directives that can take a platform extension can be decorated with the .ntia64 platform extension. The functionality of this new platform extension is equivalent to the functionality of the .ntx86 and .nt platform extensions supported in Windows 2000.
The platform-extension search order that SetupAPI follows for Itanium-based systems is as follows:
1. Check for install sections with the .ntia64 platform extension. If one is present, SetupAPI uses it for installation. SetupAPI checks for platform-specific install sections in the INF being processed and in any included INF files (that is, in any INFs included with Include entries).
2. If no .ntia64 platform extensions are present, check for an install-section-name.nt section in the INF or any included INFs. If one is present, SetupAPI processes the install-section-name.nt section.
3. If no .nt platform extensions are present, SetupAPI uses the undecorated sections.
If an INF that supports driver installation for more than one operating system contains decorated install-section-name.ntia64 sections, it must also have additional parallel decorated and undecorated per-device sections. That is, if the INF has both install-section-name and install-section-name.ntia64 sections and it has a DDInstall.HW section, it also must have a parallel install-section-name.ntia64.HW section if the device or driver requires an .HW section for the 64-bit version of Windows XP.
Backward Compatibility
Previous versions of Windows will treat the new platform extension as unknown and will ignore any INF file entries and sections that contain .ntia64. Therefore, a Windows XP INF file that contains .ntia64 entries can be used to install a driver on a 32-bit platform. An unaltered Windows 2000 INF can be used to install 32-bit drivers on x86-based systems running Windows XP.
When installing drivers on an Itanium-based system, SetupAPI will not install drivers from INFs that have only .ntx86 install sections. SetupAPI will also halt the driver installation if it discovers that it is installing an x86 driver on an Itanium-based system, or vice-versa. However, the developer should not rely on this behavior; instead, implement the correct decorations in the INF to ensure proper installation behavior.
Note also the 64-bit version of UpdateDriverForPlugAndPlayDevices and the 64-bit version of SetupAPI must be used. The 32-bit version of these APIs cannot be used with the 64-bit version of Windows XP.
Note: To prevent any Windows XP-specific information from being mistakenly used under Windows Millennium Edition or Windows 98/95, the developer should decorate any Windows NT 4.0-, Windows 2000-, Windows XP-specific DDInstall and related sections with the appropriate .ntx86, .ntia64, or .nt extensions.
The ChkINF tool has been updated to recognize and validate the proper usage of the .ntia64 platform extension in INF files.
Resources for INF Files for 64-bit Windows XP
• All aspects of driver support for Itanium-based systems are documented in the Windows DDK, together with sample INF files.
• Use the ChkINF tool available in the Windows DDK to validate proper use of the .ntia64 platform extension in INF files. ChkINF is located in the \Tools\Chkinf subdirectory and should be run from the command prompt. A batch file, ChkINF.bat, is provided for smooth execution.
• Ensure that drivers and installation routines developed for Itanium-based systems include 64-bit kernel-mode drivers, and 64-bit class installers and co-installers as described in this paper and in the Windows DDK.
• Use the .ntia64 platform extension and the new .ia64 decoration so SetupAPI recognizes your INF entries.
• More information about the ChkINF tool is available in ChkINF Enhancements for Windows XP.
Operating-System Versioning for Drivers under Windows XP
The Windows XP operating system includes new capabilities that allow driver developers to specify different device INF file behavior based on the operating system version, including product type and product suite.
This article describes these capabilities and provides details about how developers can implement such support in device INF files. This article was previously published at this URL:
Background for Operating-System Versioning
For Windows 2000, there is no mechanism that can be used to ensure an INF file behaves differently on different versions of Windows NT-based operating systems, in the same way that decorations such as .NT, .NTx86 and .Ntia64 can be used to define architecture-specific behavior.
Because it was not previously possible to construct a device INF file for a newer operating system such that the INF would not be treated as valid under earlier releases, some vendors experienced problems with Windows 2000 when they needed to provide a different INF file for Windows NT 4.0. To work around these problems, vendors have created separate "NT4" directories to help stop users from inadvertently selecting the Windows 2000 INF when installing drivers on Windows NT 4.0.
In addition, when Windows 2000 ranks INF files, no preference is given to drivers that explicitly use NT-decorated DDInstall sections in the INF. So, an INF file that has no .NT platform extensions and is intended only for Windows 98 might be chosen in preference to a lower ranked INF file that includes NT-decorated sections. This problem is typically presented to the user with the following cryptic message:
The installation failed because a function driver was not specified for this device instance.
Under Windows XP, an enhancement to the device INF file format resolves problems related to differentiating operating system versions. By adding decorated [Models] sections to the INF, a vendor can create a single INF to install different drivers on Windows 2000 and Windows XP. With this enhancement, the vendor can completely differentiate among the following when designing their driver installation solutions:
Architecture Operating system major version
Operating system minor version
Product type (workstation, server, and domain controller)
Product suite (Enterprise, Datacenter, Small Business Server, and so on)
Vendors who do not need to differentiate between the two versions of Windows can provide customers with their existing, unchanged Windows 2000 INF files to install drivers on 32-bit versions of Windows XP.
Vendors who want to provide a single INF for installing drivers under both 32-bit and 64-bit versions of Windows XP must use .ntia64, the new decoration defined for 64-bit drivers. For information about this new decoration and related topics, see "Creating INF Files for Multiple Platforms and Operating Systems" in the Windows DDK. See also INF Platform Extension for 64-bit Versions of Windows XP.
Windows XP Changes to the INF [Manufacturer] Section
The [Manufacturer] section in an INF identifies the manufacturer of one or more devices that can be installed by using that INF file. To address the issues described in the previous section, the format of entries in the [Manufacturer] section of device INF files has been enhanced for Windows XP as follows:
[Manufacturer]
%strkey%=models-section-name [,TargetOSVersion] [,TargetOSVersion] ...
Where:
|strkey |Specifies a token, unique within the INF, representing the name of a |
| |manufacturer. Each such %strkey% token must be defined in a Strings section |
| |of the INF file. |
|models-section-name |Specifies an INF-writer-defined name for the per-manufacturer INF [Models] |
| |section within the INF file. This value must be unique within the INF and |
| |must follow the general rules for defining section names defined in "General|
| |Syntax Rules for INF Files" in the Windows DDK. |
|TargetOSVersion |For Windows XP and later versions, this specifies one or more operating |
| |system versions with which the specified INF [Models] section can be used. |
Details about using TargetOSVersionare are provided later in this article.
About the [Manufacturer] Section
Any INF that installs drivers for one or more devices must have a [Manufacturer] section. An IHV- or OEM-supplied INF typically specifies only a single entry in this section. If multiple entries are specified, each entry must be on a separate line of the INF.
The [Manufacturer] section of a system-supplied INF for a device setup class is sometimes called a Table of Contents because this section sets up the installation of every manufacturer's device models for that class. Each entry in an INF's [Manufacturer] section specifies both an easily localizable %strkey% token for the name of a manufacturer and a unique-to-the-INF per-manufacturer [Models] section name.
Using a %strkey%=models-section-name entry simplifies the localization of the INF for the international market, as described in "Creating International INF Files" in the Windows DDK. An alternate format for entries in the [Manufacturer] section can be used that simply identifies the device manufacturer, but which cannot be localized and which does not take the TargetOSVersiondecoration.
For more details, see "INF Manufacturer Section" in the Windows DDK.
About the TargetOSVersion
Decorations
For Windows XP and later versions of Windows, entries in the [Manufacturer] section can be decorated to specify operating system versions. The specified versions indicate with which operating system versions the specified INF [Models] sections will be used. If no versions are specified, Setup uses the specified [Models] section for all versions of all operating systems.
The format of TargetOSVersion,the version decoration, is as follows:
NT[Architecture][.[OSMajorVersion][.[OSMinorVersion][.[ProductType][.SuiteMask]]]]
Where:
|NT |Operating system version recognition is supported for Windows XP and later versions. |
|Architecture |Identifies the hardware platform. This must be x86 or ia64. |
|OSMajorVersion |A number representing the operating system's major version number. For Windows XP, |
| |this number is 5. |
|OSMinorVersion |A number representing the operating system's minor version number. For Windows XP, |
| |this number is 1. |
|ProductType |A number representing one of the VER_NT_xxxx flags defined in Winnt.h, such as: |
| |0x0000001 (VER_NT_WORKSTATION) |
| |0x0000002 (VER_NT_DOMAIN_CONTROLLER) |
| |0x0000003 (VER_NT_SERVER) |
| |When this information is included, the INF will be used only if the operating system |
| |matches the specified product type. If the INF supports multiple product types for a |
| |single operating system version, multiple TargetOSVersion entries are required. |
|SuiteMask |A number representing a combination of one or more of the VER_SUITE_xxxx flags |
| |defined in Winnt.H. These flags include: |
| |0x00000001 (VER_SUITE_SMALLBUSINESS) |
| |0x00000002 (VER_SUITE_ENTERPRISE) |
| |0x00000004 (VER_SUITE_BACKOFFICE) |
| |0x00000008 (VER_SUITE_COMMUNICATIONS) |
| |0x00000010 (VER_SUITE_TERMINAL) |
| |0x00000020 (VER_SUITE_SMALLBUSINESS_RESTRICTED) |
| |0x00000040 (VER_SUITE_EMBEDDEDNT) |
| |0x00000080 (VER_SUITE_DATACENTER) |
| |0x00000100 (VER_SUITE_SINGLEUSERTS) |
| |0x00000200 (VER_SUITE_PERSONAL) |
| |0x00000400 (VER_SUITE_SERVERAPPLIANCE) |
| |When this information is included, the INF will be used only if the operating system |
| |matches all of the specified product suites. If the INF supports multiple product |
| |suite combinations for a single operating system version, multiple TargetOSVersion |
| |entries are required. |
For more information, see the discussion on the OSVERSIONINFOEX structure in the Microsoft Platform SDK.
IMPORTANT: If an INF supports multiple manufacturers, the rules described for TargetOSVersion and the [Models] sections must be followed for each manufacturer.
About the [Models] Sections
If your INF contains [Manufacturer] section entries with decorations, it must also include [Models] sections with names that match the operating system-version decorations. For example, if an INF contains the following [Manufacturer] section:
%FooCorp%=FooMfg, NT....0x80, NT
Then the INF must also contain [Models] sections with the following names:
[FooMfg.NT....0x08] ;Valid for XP and later, Datacenter only
[FooMfg.NT] ;Valid for XP and later, all product types and suites
For this example, Setup will use the [FooMfg.NT....0x08] [Models] section during installation if it is running on a version of Windows Server 2003, Datacenter Edition or later version. If it is running on a version of Windows Server 2003 or later that is not Datacenter Edition, then Setup will use the [FooMfg.NT] [Models] section.
If the INF is intended for use with Windows 2000, Windows NT 4.0, and Windows 98/Windows Millennium Edition (Windows Me) operating systems, it must also contain an undecorated [Models] section named [FooMfg].
Using Operating System-Versioning Decorations
This section provides supporting information for implementing the new TargetOSVersion decorations and related [Models] sections in device INF files.
Excluding a Specific Operating System Version
If you want the INF to explicitly exclude a specific operating system version, product type, or suite, then create an empty [Models] section. For example, to create an INF that is intended for use only on Windows XP, the INF file could contain the following:
[Manufacturer]
"Foo Corp." = FooMfg, NT.5.1, NT.5.2
[FooMfg.NT.5.1]
"Foo Device" = FooDev, *FOO1234
Note the omission of the undecorated [FooMfg] section, as well as the omission of the [FooMfg.NT.5.2] section. This INF file would appear to be "empty" on any operating system other than Windows XP.
Selecting the Most Appropriate TargetOSVersion
The information provided in a TargetOSVersion entry is used as input to the VerifyVersionInfo API added for Windows 2000. (For complete details, see the kernel-mode API RtlVerifyVersionInfo in the Windows DDK, and see the user-mode API VerifyVersionInfo in the Microsoft Platform SDK.)
This API eliminates inapplicable entries based on the decorations, and then SetupAPI chooses the most specific entry from the remaining entries. If multiple entries have identical versions, then the selection is made based on which entry is "most specific" by using the following criteria, sorted in order of priority:
1. Processor architecture
2. Product type
3. Suite mask
In the following example, the resultant [Models] section name is [FooMfg.NTx86] and is applicable for any x86 version of Windows XP or later:
"Foo Corp." = FooMfg, NTx86
In the following example, for versions later than Windows XP, the resultant [Models] section name is [FooMfg.NT.5.5]. For earlier versions, including Windows XP and Windows 2000, [FooMfg] will be used.
"Foo Corp." = FooMfg, NT.5.5
Setup selects the [ Models] section to use based on the following rules:
• If the INF contains [Models] sections for several major or minor operating system version numbers, Setup uses the section with the highest version numbers that are not higher than the operating system version on which the installation is taking place.
• If the INF [Models] sections that match the operating system version also include product type decorations, product suite decorations, or both, then Setup selects the section that most closely matches the running operating system.
Suppose, for example, Setup is running on Windows XP Professional (which is operating system version 5.1), and it finds the following entry in a [Manufacturer] section:
%FooCorp%=FooMfg, NT, NT.5, NT.5.5, NT....0x80
In this case, Setup will look for a [Models] section named [FooMfg.NT.5]. Setup will also use the [FooMfg.NT.5] section if it is running on Windows Server 2003, Datacenter Edition, because a specific major/minor version takes precedence over the product type and suite mask.
Windows XP Driver Ranking and Operating System-Version Decorations
When ranking driver packages, Windows 2000 does not pay attention to any "hints" (that is, platform extensions such as .nt) in determining whether an INF supports Windows NT-based operating systems. Consider the following example where Setup encounters three INF files during driver searching:
|A.INF |B.INF |C.INF |
|"Foo Corp" = FooMfg, NT |"Foo Corp" = FooMfg |"Foo Corp" = FooMfg |
|INF is unsigned |INF is signed |INF is unsigned |
|Rank = 1 |Rank = 1 |Rank = 0 |
The Windows 2000 driver selection criteria will pick C.INF because it is the lowest rank. However, this might be a Windows 95-only INF file, and Setup might get partway through device installation only to discover it fails with ERROR_NO_ASSOCIATED_SERVICE (the cryptic error mentioned earlier).
Note that both A.INF and B.INF provide indications that the INF file is intended for use on a Windows NT-based operating system. In the first case, this is indicated because the INF file uses decoration. In the second, it is indicated because the INF file is signed. Therefore, it is preferable to favor these two INFs and to fall back to the last one only if no other options are available.
For selecting between A.INF and B.INF, the existing logic is employed. Because B.INF is signed, its DriverVer date would make it appear newer, and it would be picked, assuming there is no co-installer/class-installer involvement to the contrary.
Under Windows XP, the driver ranking strategy has been modified as follows:
• If an INF file is unsigned, and if neither the [Models] section nor the [DDInstall] section is decorated with an NT-specific extension, the INF file is considered "suspect" and its rank is shifted into a higher range (that is, worse) than all hardware and compatible rank matches of INF files for which one (or both) of those criteria are met.
• The new ranking ranges will now be:
0 0xFFF (DRIVER_HARDWAREID_RANK) : "trusted" hardware-ID match 0x1000 0x3FFF : "trusted" compatible-ID match
0x8000 0x8FFF : "untrusted" hardware-ID match
0x9000 0xBFFF : "untrusted" compatible-ID match
0xC000 - 0xCFFF : "untrusted" undecorated hardware-ID match (possibly a Windows 9x-only driver)
0xD000 - 0xFFFF : "untrusted" undecorated compatible-ID match (possibly a Windows 9x-only driver)
In Windows 2000, drivers are moved from one of the top two groups to the appropriate bottom group if the driver is unsigned or if the INF file is "undecorated" (has no NT-decorated sections). This implies that an unsigned driver package that is decorated (that is, the INF has .NT platform extensions) will be considered a "trusted" driver package, even though the driver is unsigned. However, for Windows XP, the consideration of decorations for unsigned drivers has been changed: All unsigned drivers will be considered "untrusted," regardless of the existence of platform extensions in the INF.
More Notes on Operating System Versioning
• Service pack major and minor version (if any) is not incorporated into this decoration mechanism. This is because service packs do not introduce different behaviors for drivers, and driver developers should not rely on the behavior introduced in a service pack or hot fix.
• Users must still have administrative rights to install drivers, except in those cases where a server-side installation can be performed. For information about server-side installations, see "Device Installation Components" in the Windows DDK.
• The ChkINF tool has been updated to recognize XP-decorated [Models] sections and validate their proper usage in INF files.
For more information, see ChkINF Enhancements for Windows XP.
Examples of Decorated [Models] Sections
This example shows a [Manufacturer] section typical to an INF for a single vendor.
[Manufacturer]
%FooMfg%=FooMfg ; Models section == FooMfg
; ...
[Strings]
FooMfg = "Foo Corporation"
The following example shows a [Manufacturer] section that is specific to x86-based platforms, Windows XP and later:
[Manufacturer]
%foo%=foosec,NTx86.5.1
[foosec.NTx86.5.1]
The following two examples show skeletal INFs with a variety of operating system-specific Models sections.
Example 1:
[Manufacturer]
%MyName% = MyName,NTx86.5.1
.
.
[MyName]
%MyDevice% = InstallA,hwid
.
.
[MyName.NTx86.5.1]
%MyDevice% = InstallB,hwid
.
.
.
[InstallA.ntx86] ; Windows 2000 (NT4-x86 will also try
. ; to parse this section)
.
.
[InstallA] ; Win98/WinME (Win95 will also try
. ; to parse this section)
. ; NT4-Alpha will also try to parse this section
. ; unless INF has an [InstallA.ntalpha] section.
.
.
[InstallB] ; XP and later, x86 only
.
.
Example 2:
[Manufacturer]
%MyName% = MyName,NT.6.0,NTx86.5.1
.
.
[MyName.NT.6.0] ; Empty section, so this INF does not support
. ; NT 6.0 and later.
.
.
[MyName.NTx86.5.1] ; Used for NT 5.1 and later
. ; (but not NT 6.0 due to the NT.6.0 entry)
%MyDevice% = InstallB,hwid
.
.
[MyName] ; Empty section, so this INF does not support
. ; Win2000/nt4/Win9x/WinME
Resources for Driver Versioning
Driver developers can implement and test this new versioning capability in INF files in conjunction with the beta releases of the Windows XP operating system.
All aspects of driver installation are documented in the Windows DDK, together with sample INF files, and will be provided in future releases of the Windows DDK. See these topics:
• "Creating INF Files for Multiple Platforms and Operating Systems"
• "INF Manufacturer Section"
For information about the OSVERSIONINFOEX structure, see the Microsoft Platform SDK.
Multifunction Device Installation and Windows XP
For Microsoft Windows XP, changes were made to device driver INF definitions to support multifunction device installation. This article describes the use of the CopyINF directive. This article provides preliminary information; complete documentation of these capabilities is provided in the Windows DDK.
This information was previously published at this URL:
Background for Multifunction Device Installation
Under Windows 2000, a user who installs a multifunction device is presented with multiple "New Hardware Found" pop-up messages if the device is not supported by a driver provided with the operating system. Individual messages for each function on the device appear, as well as an individual message for the base device, if applicable.
Under Windows XP, improvements to multifunction device installation prevent the iterative "New Hardware Found" pop-up messages. Windows XP prompts the user only once to supply the distribution media for the driver.
This feature can also be used by device and system manufacturers to benefit customers who install various types of multifunction devices, such as Modem/Network Adapter devices or USB devices that expose multiple device IDs (for example, a USB printer that is also a USB hub).
To take full advantage of this new capability, driver developers must use the new CopyINF entry described in this article. If the CopyINF entry does not appear in the INF, multifunction device installation will function under Windows XP as it does under Windows 2000.
The following changes were made to INF definition under Windows XP to support multifunction device installation:
• The CopyINF directive was added to the INF definition.
• SetupAPI was modified to handle the CopyINF directive. The INF files will not be copied if the INF is installed from a directory on the INF search path.
• The ChkINF tool, which is distributed in the Windows DDK, has been updated to check for proper usage of the new CopyINF directive.
INF CopyINF Directive
CopyINF directives are specified in one or more DDInstall sections using the following syntax:
[DDInstall]
CopyINF = INFname[,INFname...]
where each named INF file must not be compressed and must reside on the source media relative to the INF from which they are referenced.
A CopyINF directive causes specified INF files to be copied to the target system. For example:
[MyMfDevice.NTx86]
CopyINF = Sound.INF
This directive is typically used when installing multifunction devices. In some cases, the installation of a multifunction device requires multiple INF files to support multiple functions belonging to multiple setup classes. In such cases, using the CopyINF directive ensures that Setup will find the INF files when installing the functions, without presenting the user with multiple prompts.
The following rules apply:
• If the functions supplied by a multifunction device are enumerated as children of a parent device (such as an IEEE 1284.4 device), then the INF file for the parent device should contain a CopyINF directive to copy the INF files for the device's individual functions.
• If all functions supplied by a multifunction device (such as a PCI card) are enumerated as peers of each other, then the INF for each function should contain a CopyINF directive to copy the INF files for all peer functions.
If you follow these rules, Setup can install drivers for each function without prompting the user for an installation disk for each function.
Setup copies the specified INF files as part of the default processing for DIF_INSTALLDEVICE after the device has been successfully installed. For information, see SetupDiInstallDevice in the Windows DDK documentation.
The locations of INF files specified in the CopyINF directive are relative to the source location of the INF file containing the CopyINF directive. Setup copies the specified INF files into a system directory path that will be searched when it installs devices.
You must include all INF files on each disk of a multi-disk installation.
System support for the CopyINF directive is available in Windows XP and later operating system versions. You can also use the directive with Windows 2000 if you install and register the CoCpyINF co-installer, as described later in this paper.
Copying INFs
It is sometimes necessary to copy INF files during device installation so that Setup can find them without repetitively displaying user prompts. For example, the base INF file for a multifunction device might copy the INF files for the device's individual functions, so that Setup can find these INF files without prompting the user each time it installs one of the device's functions.
To copy INF files, you can use either of the following techniques:
• A co-installer or setup application can call SetupCopyOEMInf, which is described in the Platform SDK documentation.
As described in the following section, the Windows DDK includes source code for a co-installer, Cocpyinf.dll, which uses this technique. The source code and related documentation can be found under the %WINDDK%\src\general\cocpyinf directory.
• An INF file can include the INF CopyINF directive.
As described in the following section, you can use the compiled (binary) version of Cocpyinf.dll provided with the Windows DDK. If you use this co-installer for your device, the CopyINF directive can be used on Windows 2000. The redistributable version of Copyinf.dll and related documentation can be found under the %WINDDK%\tools\coinstallers directory.
Support for the INF CopyINF directive is built into Windows XP. No co-installer is required to include the CopyINF directive in INF files.
Both of these methods will do the following:
• Install the appropriate catalog file, if it exists, along with the INF file.
• Give the INF file a unique name so that it does not overwrite any other INF files and will not be overwritten by other INF files.
• Retain the path to the source medium from which the rest of the files in the driver package are to be copied.
• Ensure compatibility with future versions of Windows.
Although no co-installer is required to use CopyINF directive, using this directive will ensure correct behavior if the INF is expected to work on both Windows 2000 and Windows XP.
IMPORTANT: On Windows 2000 and later versions, installation software must never copy INF files directly into a system's %windir%/inf directory. Copying INF files by using any techniques not described in the "Copying INFs" section of the DDK will invalidate a driver's digital signature. Driver packages that copy INF files directly will fail "Designed for Windows" Logo testing.
Sample Co-installer for Copying INF Files
The Windows DDK includes a sample co-installer that can be used to build and install additional device INF files on the target system during a device installation. The instructions provided in this article apply only for Windows 2000.
This sample is provided in the Windows DDK. The source code, samples, and related documentation can be found under the %WINDDK%\src\general\cocpyinf directory. The redistributable version of Copyinf.dll and related documentation can be found under the %WINDDK%\tools\coinstallers directory.
This sample co-installer interprets CopyINF directives in a [DDInstall] section in an INF file. Using CopyINF with the redistributable co-installer allows one INF file to copy multiple INF files to the target system.
To use the co-installer for driver installation and registration:
1. Copy Cocpyinf.dll from the redistributable binaries directory to the directory where you are assembling your driver package.
2. To use this co-installer, add the following sections to every INF file for your drivers. If the multifunction device is a single parent that enumerates multiple children, then only the parents INF needs to install or use the co-installer.
• Add a [DDInstall.CoInstallers] section for each device specified in the INF. For example:
[InstallA.NT.CoInstallers]
AddReg = CoCopyINF.AddReg
CopyFiles= CoCopyINF.CopyFiles
• Add an [AddReg] section to register the co-installer. For example:
[CoCopyINF.AddReg]
HKR,,CoInstallers32,0x10008,"cocpyinf.DLL,CoCopyINF"
• Add a [CopyFiles] section to copy the co-installer binary. For example:
[CoCopyINF.CopyFiles]
cocpyinf.dll,,,0x10
• Add references to all the other INF files in the package in the [DDInstall] section. For example:
[InstallA.NT]
CopyInf = B.INF
• Add sections to install the drivers.
For more information, see the sample INF files that are provided at %WINDDK%\tools\coinstallers\ in the Windows DDK.
See also "Writing a Coinstaller" under "Supporting Device Installation" in the Windows DDK.
Resources for Multifunction Devices
• Driver developers should use the CopyINF entry in their device INF files in order to provide customers with the improved user experience for multifunction device installation under Windows XP.
• Driver developers should test INFs with CopyINF entries provided in Windows.
• All aspects of driver installation, including the CopyINF entry for INFs together with sample INF files, are provided in the Windows DDK. See these topics:
• "Creating an INF" (including "INF CopyINF Directive" and "Copying INFs") in the "Device Installation" section.
• "Supporting Multifunction Devices" in the Plug and Play section, plus the related section for Multifunction Print Devices.
ChkINF is located in the \Tools\Chkinf subdirectory and should be run from the command prompt. A batch file, ChkINF.bat, is provided for smooth execution.
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.