Device Installation Rules and Guidelines For Windows Vista
Device Installation Rules and Guidelines For Windows Vista
Device Installation Rules and Guidelines For Windows Vista
Abstract
This paper provides preview information about device installation for Microsoft®
Windows Vista™. Manufacturers can use the information in this paper to anticipate
changes and to design driver installation programs for the release of Windows
Vista.
The rules that driver packages must follow to be installed successfully in Windows
Vista represent best practices for Microsoft Windows Server™ 2003, Microsoft
Windows XP, and earlier versions of Microsoft Windows®. Existing driver packages
that implement these best practices should require few if any changes to work for
Windows Vista. The guidelines in this paper for Windows Vista may become rules in
later Windows operating systems.
This information applies for the following operating systems:
Microsoft Windows 2000
Microsoft Windows XP
Microsoft Windows Server 2003
Microsoft Windows Vista
Future versions of this preview information will be provided in the Windows Driver
Kit.
The current version of this paper is maintained on the Web at:
http://www.microsoft.com/whdc/driver/install/default.mspx
Contents
Introduction.............................................................................................................................. 3
Device Installation in Windows Vista.......................................................................................4
Driver Store User Interface: Validating Trust and Licensing...............................................5
Driver Store: Placing Packages on the Local System.........................................................6
Update Install User Interface...............................................................................................7
Core Device Installation: Copying Files and Modifying the Registry...................................7
Finish-Install User Interface: Offering Optional User Interaction.........................................7
Device Installation Rules and Guidelines for Windows Vista...................................................8
Accessing and Modifying Registry Values..........................................................................9
Accessing and Modifying Device Properties.....................................................................15
Accessing and Modifying Files..........................................................................................16
Rules for Device Driver Information (.inf) Files.................................................................16
Calling Device Installation Functions................................................................................17
Software-First Installations................................................................................................18
General Rules for Class Installers and Co-Installers........................................................19
Checklist: Summary Actions for Driver Developers...............................................................21
Resources.............................................................................................................................. 21
Glossary............................................................................................................................ 21
References........................................................................................................................ 22
Device Installation Rules and Guidelines for Windows Vista - 2
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.
Microsoft, Authenticode, Windows, 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.
Introduction
Microsoft® Windows Vista™ introduces an improved device installation architecture
that is more simple, user friendly, flexible, and secure than device installation for
earlier versions of Microsoft Windows®.
This paper provides preview information about device installation for Windows
Vista, including rules and guidelines for driver packages. Driver packages that do
not follow these rules and guidelines might not be installable on later versions of
Windows, beginning with Windows Vista.
For definitions of terms in this paper, see "Resources" at the end of this paper.
Solutions to problems with existing device installation. The Windows Vista
device installation architecture solves problems with existing device installation on
Windows XP and earlier versions of Windows. Issues addressed include:
Server-side versus client-side installation. For current versions of
Windows, class installers and co-installers must follow different rules, including
different security rules, depending on whether installation occurred in the
context of the user (client-side installation) or in the context of the system
(server-side installation). In addition, presenting a user interface during server-
side installation can hang Plug and Play.
The Windows Vista device installation architecture eliminates client-side
installation. The same rules apply to class installers and co-installers at all
times, without exception.
Files copied from the CD only when needed. Users of current versions of
Windows are prompted to insert product CDs to provide extra files that are
required after installation, which causes problems if the user cannot find the
CD.
For Windows Vista, all files in a driver package are copied into a driver store
and then loaded as they are required. To add functionality after initial
installation, the user does not need the CD.
Digital signature issues. For current versions of Windows, the system
displays warnings for every unsigned driver installation, which troubles users
and causes them to unnecessarily lose confidence in drivers. Windows Vista
moves away from this user experience, although unsigned drivers still require
administrator authorization and display a warning.
For Windows Vista, all driver packages must be trusted to be installed. They
can be signed either by Microsoft through the Windows Logo Program or by
another trusted entity through Microsoft Authenticode® technology. On x86 and
IA64 versions of Windows Vista, unsigned drivers still cause user prompts.
However, administrators can trust unsigned drivers and stage them in the driver
store on users' local machines. This eliminates the need for users to elevate to
administrator privileges to install the driver and is useful in enterprise scenarios.
After a driver has been added to the store, it is considered to be trusted and can
be installed without prompts or administrator credentials.
On X64 versions of Windows, drivers must be signed and administrators cannot
install unsigned drivers. This ensures a more secure platform for X64 versions
of Windows.
For more information about the driver signing for x64 versions of Windows, see
the papers listed in "Resources" at the end of this paper.
User rights. For current versions of Windows, the file system and registry
are protected with access control lists (ACLs). During client-side installation,
installation is subject to the ACLs of the file system, registry, and Plug and Play.
The user must be logged in as an administrator to install drivers.
For Windows Vista, the user is not required to be an administrator to install
drivers; instead, the installation rules engine checks the user's driver installation
policy to determine whether to permit installation. Domain administrators can
push drivers to many client systems at one time.
Rules that promote system reliability and stability. Under the Windows Vista
device installation architecture, devices and kernel-mode device drivers can be
installed only through approved device installation functions. These functions
restrict an external component's ability to access or modify the internal resources of
the device—the registry settings and files that the device installation architecture
uses—through unsupported means.
Using these device installation functions ensures that driver packages cannot take
actions that might conflict with other device installations, applications, or Windows
components and that, in the event of problems, that any installed driver can be
rolled back cleanly or uninstalled.
Driver packages that are designed to the Windows Vista device installation
architecture help to ensure that drivers and associated applications are removed
cleanly, without leaving files, state, or registry settings on the system that might
cause instability or loss of functionality. Such driver packages also help preserve
the stability and functionality of the system over time, as more devices are installed
and uninstalled. These benefits should help to reduce support costs for hardware
manufacturers and generate more device sales as consumers become more
confident in the installation experience.
The rest of this section explains the stages of driver installation on a computer that
is running Windows Vista.
To ensure the integrity of all software that is running in kernel mode on x64 versions
of Windows, Windows Vista goes further and loads only signed kernel-mode
components.
Additional documentation on driver package integrity for third-party developers can
be found in the white paper titled Driver Package Integrity during Plug and Play
Device Installs in Windows Vista and in the Windows Driver Kit (WDK), under
sections titled "How Setup Selects Drivers" and "Signing Drivers for Development
and Test." Additional x64 information can be found in the white paper titled Digital
Signatures for Kernel Modules on x64-based Systems Running Windows Vista.
More information about the driver store architecture will be released on the WHDC
Web site.
The following DIF codes might also be sent during core device installation:
DIF_SELECTBESTCOMPATDRV
DIF_NEWDEVICEWIZARD_FINISHINSTALL
Core device installation always runs in the system context (noninteractive, server-
side installation). Interactive (client-side) installation is not supported in Windows
Vista. Installation fails if the installer prompts for a file. Installation hangs if a class
installer or co-installer attempts to display user interface (UI).
Core device installation always runs in a separate process. A new process is
created for each device installation. If the process does not finish in a prescribed
amount of time (the default is 5 minutes), the device installation engine proceeds as
if the process has stopped responding and ends it, so it is not possible for a bad
driver package or installer to hang the Plug and Play process.
After core device installation finishes, the device installation engine does the
following in the system context (that is, noninteractive):
Sends the class installer or co-installer a
DIF_NEWDEVICEWIZARD_FINISHINSTALL request.
The class installer or co-installer should create any property pages to appear to
the user.
Detects whether the class installer or co-installer provided any pages and
marks the device with CONFIGFLAG_FINISHINSTALL_UI.
This flag causes the device installation scheduler to launch this installer in the
user’s interactive process so it can display the finish-install property pages.
Destroys the pages. (These resources must be released before changing to
user context, to prevent a memory leak.)
For best results, do not allow the user to continue the dialog procedure until the
separate installation process is finished because Windows may reboot after it thinks
all finish-install pages are complete.
To enable domain administrators to push installation of the driver package without
user interaction, design the class installer or co-installer so that it can be run by
using a script or unattended file and use the settings in this file instead of prompting
the user. Process these script files in the
DIF_NEWDEVICEWIZARD_FINISHINSTALL handler because that handler runs in
the system context.
For an example of using finish-install user interface in a driver package, see the
Toastpkg sample in the WDK.
For more information about the device finish-install action, see the paper
titled Device Finish-Install Actions in Windows Vista, which is listed in
"Resources" at the end of this paper
Driver packages that do not follow these rules may not be installable on later
versions of Windows, beginning with Windows Vista. A subset of these rules and
guidelines are expected to become Windows Logo Program requirements.
Many of the rules that driver packages must follow to be installed successfully in
Windows Vista represent best practices for Windows Server 2003, Windows XP,
and earlier versions of Windows. Existing driver packages that implement these
best practices should require few if any changes to work for Windows Vista.
These rules can be summarized by the following general guidelines:
Always use .inf files for device installation and make sure that all .inf files
are well formed.
Use custom code (co-installers or class installers) only when absolutely
necessary.
If you do use custom code, use only SetupAPI functions to access Plug and
Play structures.
If you must interact with the user, use only finish-install actions or pages to
display user interface.
Use the new driver install frameworks tools whenever possible.
Do not make assumptions about the location, format, or meaning of registry
keys or values.
Do not directly access or modify internal device settings.
Do not access or change any protected data.
Applications must not use internal device state to discover and install devices, to
store and retrieve device properties, or to store and retrieve device settings.
Do not depend directly on the absence of these keys. When the device is
uninstalled, the system automatically deletes all DIREG_DEV and DIREG_DRV
keys.
Subkeys under DIREG_DEV and DIREG_DRV keys can be safely created and
deleted by using standard registry functions. This helps avoid naming collisions
between the system and other components. Subkeys should inherit default
permissions of parent keys.
Rule #6 Do not enumerate the device setup class keys to discover installed setup
classes
Do not enumerate the device setup class keys under
HKLM\SYSTEM\CurrentControlSet\Control\Class\… to discover installed setup
classes. As with any registry key, the location and format of device setup class keys
might change. In addition, the list of available classes might be generated in the
future from sources other than the registry.
Rule #9 Do not enumerate device setup class subkeys to open the software keys
for all devices in a setup class
Do not enumerate device setup class subkeys under
HKLM\SYSTEM\CurrentControlSet\Control\Class\{GUID}\… to open the software
keys for all devices in a setup class. As with any registry key, the location, name, or
format of the key might change. In addition, keys should be opened only after the
corresponding device is located.
To enumerate device setup class subkeys safely:
Use SetupDiGetClassDevs to retrieve all devices for a specified device
setup class.
Use SetupDiEnumDeviceInfo to enumerate all devices in the set.
Use SetupDiOpenDevRegKey with DIREG_DRV KeyType to open this
key for each device.
Some devices might not have DIREG_DRV keys (if not installed).
Rule #10 Do not enumerate device interface subkeys to discover device interfaces
on the system
Do not enumerate device interface subkeys under
HKLM\SYSTEM\CurrentControlSet\Control\DeviceClasses\{GUID}\… to discover
device interfaces on the system. As with any registry key, the location, name, or
format of the key might change. In addition, keys should be opened only after the
corresponding device interface is located.
To enumerate device interface subkeys safely:
Use SetupDiGetClassDevs with the DIGCF_DEVICEINTERFACE flag set.
Set the DIGCF_PRESENT flag to include only enabled device interfaces.
Enumerator includes only device interfaces that are registered for a specific
device instance identifier.
Use SetupDiEnumDeviceInterfaces to enumerate interfaces that are
registered for specified device interface class.
Use IoGetDeviceInterfaces for kernel-mode callers.
Rule #11 Do not open, read, or write device interface subkeys to discover
attributes of device interfaces that are registered on the system
Do not open, read, or write device interface subkeys under
HKLM\SYSTEM\CurrentControlSet\Control\DeviceClasses\{GUID}\ … to discover
attributes of device interfaces that are registered on the system. As with any registry
key, the location, name, or format of the key might change. In addition, keys should
be opened only after the corresponding device interface is located.
To safetly discover attributes of device interfaces:
Use SetupDiOpenDeviceInterface to locate a device interface and add it
to a set from its name.
Use SetupDiGetDeviceInterfaceDetail to retrieve details for the device
interface.
The optional DeviceInfoData parameter retrieves the SP_DEVINFO_DATA
element for the device for which the interface is registered.
Use persistent registry storage for custom device interface settings:
SetupDiCreateDeviceInterfaceRegKey to create a storage key.
SetupDiOpenDeviceInterfaceRegKey to open the storage key.
Use IoOpenDeviceInterfaceRegistryKey for kernel-mode callers.
Rule #12 Do not require KEY_ALL_ACCESS or change default access rights that
were granted to any SetupDi-managed keys
Customer problems have been traced to critical keys that were deleted by external
components or access rights of critical keys that were modified by external
components. In Windows Server 2003, SetupDiCreateDevRegKey grants only
KEY_READ and KEY_WRITE access, not KEY_ALL_ACCESS. Additional
KEY_ALL_ACCESS restrictions are enforced in Windows Vista.
To access keys safely:
Use only supported functions to open SetupDi-managed keys.
These functions can be used to address common problems that result from
access rights restrictions.
Request only the minimal access rights that are required for each task. For
example:
KEY_SET_VALUE
KEY_QUERY_VALUE
KEY_CREATE_SUB_KEY
KEY_ENUMERATE_SUB_KEYS
Rule #13 Use only .inf directives to modify protected registry keys
Class installers and co-installers may not call registry functions to create, change,
or delete registry keys, except under specified conditions. Registry keys should be
modified by using directives that are placed in .inf files.
Also, class installers and co-installers may not use SetupDiCreateDevRegKey,
SetupDiOpenDevRegKey, or SetupDIDeleteDevRegKey to add, delete, or
change the content of the software keys in the registry
(HKLM\SYSTEM\CurrentControlSet\Control\Class). Software keys should be
modified by using SetupAPI functions.
Exceptions. The following are exceptions to this rule that apply to more than one
function:
Class installers and co-installers may, if necessary, use registry functions to
modify registry keys in the HKLM\Software subtree. Although this action is
permitted, it is not recommended and it might not be permitted in the future.
Alternate means of modifying the keys in this subtree, including SetupAPI
functions and directives placed in .inf files, should be used.
Class installers and co-installers are permitted to modify registry keys in the
HKLM\System\CurrentControlSet\Control\CoDeviceInstallers key.
Rule #17 Do not set read-only properties or properties that the device installation
engine has reserved for use
Many properties have complex dependencies on other properties or device state.
For example, the values of SPDRP_CLASS, SPDRP_CLASSGUID, and
SPDRP_DRIVER must be consistent with each other.
Direct modification of reserved properties could invalidate device installation state.
For example, changing SPDRP_DEVICEDESC breaks backup, driver rollback, and
Windows Update.
In Windows Vista, installation-time-only restrictions will be implemented for reserved
properties.
The following properties are read only and can never be set with
SetupDiSetDeviceRegistryProperty:
SPDRP_ADDRESS
SPDRP_BUSNUMBER
SPDRP_BUSTYPEGUID
SPDRP_CAPABILITIES
SPDRP_DEVICE_POWER_DATA
SPDRP_ENUMERATOR_NAME
SPDRP_LEGACYBUSTYPE
SPDRP_PHYSICAL_DEVICE_OBJECT_NAME
SPDRP_REMOVAL_POLICY
SPDRP_REMOVAL_POLICY_HW_DEFAULT
SPDRP_UI_NUMBER
The following properties are writeable, but they are reserved for use by the device
installation engine and must not be set directly:
SPDRP_CLASS
SPDRP_CLASSGUID
SPDRP_DRIVER
SPDRP_DEVICEDESC
SPDRP_MFG
Rule #20 Do not copy files that have been deleted or renamed
Files that appear in a CopyFiles directive in the .inf file should not also appear in a
DelFiles or RenFiles directive in the .inf file. Class installers and co-installers that
use this method to copy or load a file that has been removed or deleted cause the
driver installation to fail.
Rule #23 Use the CopyInf directive to stage additional .inf files during installation
If you want to stage other .inf files during an installation that is driven by an .inf file,
use the CopyInf directive rather than the CopyFile directive.
Rule #24 Do not directly copy device driver .inf files to or delete files from
%SystemRoot%\INF
Copying or deleting .inf files from %SystemRoot%\INF invalidates the files' digital
signature and can cause file name collisions, which might invalidate existing
installed devices. In addition, .inf file store location, format, and protection might
change.
To copy or delete device driver .inf files safely:
Use SetupCopyOEMInf to install device .inf files.
Save DestinationInfFileName for uninstall.
Use SP_COPY_NOOVERWRITE and SP_COPY_REPLACEONLY CopyStyle
to customize installation.
SetupCopyOEMInf provides automatic driver store functionality in
Windows Vista.
Use SetupUninstallOEMInf to remove device INF files.
Uninstall all devices by using the corresponding driver package first, including
present and nonpresent devices.
Do not use SUOI_FORCEDELETE to delete .inf files; default usage
provides safe default behavior.
Default handlers may be called only by class installers while handling the
corresponding DIF code and only if not returning ERROR_DI_DO_DEFAULT.
Direct calls to default installation handler routines bypass all co-installers and class
installers and could invalidate the internal state of devices that installers store.
To call device installation routines safely:
Use SetupDiCallClassInstaller where possible.
Use UpdateDriverForPlugAndPlayDevices for installation.
Software-First Installations
In a software-first installation, device driver files are staged on the system before
the device is plugged in. After the device is plugged in, the driver is installed from
the device.
Software-first installations should follow all rules for class installers and co-installers
that are described elsewhere in this paper, especially those that apply to accessing
and modifying Plug and Play resources. Existing software-first installation packages
may require changes to be compatible with the new Windows Vista device
installation architecture.
For more information about the DIFx tools, see the papers listed in "Resources" at
the end of this paper.
Rule #31 Do not show user interface in the class installer or co-installer while
processing core device installation DIF codes
Core device installation runs in a system (noninteractive) service, so a user cannot
see or respond to any user interface that appears in this context. Any dialog box
that is provided in a class installer or co-installer during processing of a core device
installation DIF code causes the device installation to hang.
In general, class installers and co-installers that are running in server-side
installations should not interact with the user. As such, they must not display dialog
boxes except in the finish-install user interface.
To show user interface during installation:
Process DIF_NEWDEVICEWIZARD_FINISHINSTALL and add some
property pages. The class installer can show UI in the dialog procedure for
these finish-install pages.
Show user interface only in the dialog procedure, not when
DIF_NEWDEVICEWIZARD_FINISHINSTALL is received because this DIF code
is sent in the system context (that is, noninteractive).
For more information about the device finish-install a, see the paper titled
Device Finish-Install Actions in Windows Vista," which is listed in "Resources"
at the end of this paper.
Rule #32 Do not store state in the class installer or co-installer DLL
The DLL is very likely unloaded between any given DIF codes, so state does not
persist.
To preserve state in a class installer or co-installer DLL:
Store state in the device’s driver key.
Use SetupDiOpenDevRegKey with the DIREG_DRV flag to get a registry
handle to the device’s driver key.
Use the new device property functions SetupDiSetDeviceProperty and
SetupDiGetDeviceProperty.
Rule #34 Do not load any unsigned code on X64 versions of Windows Vista
If you attempt to load an unsigned executable file or DLL, the X64 CI component
prevents it from being loaded in this secure environment.
If you must load a DLL in the class installer or co-installer, it is recommended that it
be included in your driver package.
Rule #35 Do not call CreateProcess except from within a finish-install dialog
procedure
The device installation engine cannot track additional processes and has no way to
determine what they are doing or when they are finished. For example, the device
installation engine could start or stop the device or initiate a system restart while the
process is performing a critical action.
To launch other processes safely, launch them in a finish-install dialog procedure.
Do not allow the user to continue in the dialog procedure until the separate
installation process is finished.
Rule #36 Do not rename or delete protected system files unless allowed
Class installers and co-installers may not rename or delete protected system files,
and they may replace them only in rare cases.
See also "Accessing and Modifying Files," earlier in this paper.
Rule #37 Do not load modules by explicit function calls or by creating link
dependencies
Class installers and co-installers may not load modules by explicit function calls
(LoadLibrary) or by creating link dependencies. Required modules should be
copied by using a CopyFiles directive in the .inf file.
Resources
Glossary
client-side installation
Device installation that occurs in the interactive context of the logged-on user.
Client-side installation is no longer supported in Windows Vista.
device driver
A function driver for a hardware device that has a Plug and Play identifier.
device management and installation
The discovery and installation of available devices, storage and retrieval of
device properties, and storage and retrieval of device settings. Only supported
mechanisms should be used to perform these tasks.
Devnode
A data structure that is created and managed by the Windows Plug and Play
manager to store information about a device.
driver assembly
The group of files and registry actions that are required to install drivers and
settings on a specific Plug and Play identifier. A driver assembly is sometimes
called a driver node.
driver package
A collection of all of the files that are required to successfully load the driver.
This includes the device information (.inf) file, the catalog file, and all of the
binaries that are copied by the .inf file, including the class installer DLL, co-
installer DLL, function driver, branding icons or bitmaps, and property page
provider DLL.
hardware-first installation
The installation of device drivers that is triggered by plugging in the hardware.
internal resources
The undocumented internal state that the Plug and Play manager and device
installation architecture use, including registry keys and values and files that are
used by the device installation architecture.
nondevice driver
Any kernel-mode driver that is not a device driver, such as a filter driver, a
kernel-mode service, or a kernel-mode DLL.
phantom devnode
A devnode for a device that is not plugged in.
server-side installation
Device installation that occurs in the system context, which is noninteractive. No
user interface can appear in this context because the user cannot see it.
software-first installation
The staging of device driver files on the system before the hardware is plugged
in. After the hardware is plugged in, the driver is installed.
References
For further information, send e-mail to [email protected] with "Device
installation rules for Windows Vista" in the subject line.
Windows Driver Kit:
http://www.microsoft.com/whdc/driver/WDK/aboutWDK.mspx
Newsgroups:
microsoft.public.development.device.drivers