Device Driver inf guidelines for Windows xp june 30, 2006 archive


Using Operating System-Versioning Decorations



Download 107.39 Kb.
Page5/5
Date31.07.2017
Size107.39 Kb.
#25735
1   2   3   4   5

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: http://www.microsoft.com/whdc/device/mf/CopyINF-MF.mspx


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 <DDKRoot>\Tools\Chkinf subdirectory and should be run from the command prompt. A batch file, ChkINF.bat, is provided for smooth execution.



Download 107.39 Kb.

Share with your friends:
1   2   3   4   5



The database is protected by copyright ©ininet.org 2024
send message
    Main page
information contained
current version
current view
issues discussed as
express written permission