Registry Trees and Keys for Devices and Drivers

The operating system, drivers, and device installation components store information about drivers and devices in the registry. In general, drivers and device installation components should use the registry to store data that must be maintained across restarts of the system. For information about how a driver accesses registry information, see Using the Registry in a Driver.

Registry contents should always be treated as untrusted, modifiable information. If one of your driver components writes information to the registry and another component reads it later, do not assume that the information has not been modified in the meantime. After reading information from the registry, your driver components should always validate the information before using it.

For more information about the registry in general, see the Microsoft Windows SDK documentation.

This section contains the following topics which describe the use of registry keys to store information about drivers and devices:

Drivers must access Plug and Play (PnP) keys in the registry using system routines such as IoGetDeviceProperty or IoOpenDeviceRegistryKey. User-mode setup components should use device installation functions such as SetupDiGetDeviceRegistryProperty or SetupDiOpenDevRegKey. The registry can be accessed from INF files by using INF AddReg directives.

ImportantВ В Drivers must not access these registry trees and keys directly. This discussion of registry information in this section is solely for debugging a device installation or configuration problem.

WinUSB Device

In this topic, you will learn about how a WinUSB device is recognized in WindowsВ 8.

The information in this topic applies to you if you are an OEM or independent hardware vendor (IHV) developing a device for which you want to use Winusb.sys as the function driver and want to load the driver automatically without having to provide a custom INF.

What is a WinUSB device

A WinUSB device is a Universal Serial Bus (USB) device whose firmware defines certain Microsoft operating system (OS) feature descriptors that report the compatible ID as «WINUSB».

The purpose of a WinUSB device is to enable Windows to load Winusb.sys as the device’s function driver without a custom INF file. For a WinUSB device, you are not required to distribute INF files for your device, making the driver installation process simple for end users. Conversely, if you need to provide a custom INF, you should not define your device as a WinUSB device and specify the hardware ID of the device in the INF.

Microsoft provides Winusb.inf that contains information required by to install Winusb.sys as the device driver for a USB device.

Before WindowsВ 8, to load Winusb.sys as the function driver, you needed to provide a custom INF. The custom INF specifies the device-specific hardware ID and also includes sections from the in-box Winusb.inf. Those sections are required for instantiating the service, copying inbox binaries, and registering a device interface GUID that applications required to find the device and talk to it. For information about writing a custom INF, see WinUSB (Winusb.sys) Installation.

In WindowsВ 8, the in-box Winusb.inf file has been updated to enable Windows to automatically match the INF with a WinUSB device.

WinUSB device installation by using the in-box Winusb.inf

In WindowsВ 8, the in-box Winusb.inf file has been updated. The INF includes an install section that references a compatible ID called «USB\MS_COMP_WINUSB».

The updated INF also includes a new setup class called «USBDevice».

The «USBDevice» setup class is available for those devices for which Microsoft does not provide an in-box driver. Typically, such devices do not belong to well-defined USB classes such as Audio, Bluetooth, and so on, and require a custom driver. If your device is a WinUSB device, most likely, the device does not belong to a USB class. Therefore, your device must be installed under «USBDevice» setup class. The updated Winusb.inf facilitates that requirement.

About using the USBDevice class:

Do not use the «USB» setup class for unclassified devices. That class is reserved for installing controllers, hubs, and composite devices. Misusing the «USB» class can lead to significant reliability and performance issues. For unclassified devices, use «USBDevice».

In Windows 8, to use «USBDevice» device class, simply add this to your INF:

In Device Manager you will see a new node USB Universal Serial Bus devices and your device appears under that node.

In Windows 7, in addition to the preceding lines, you need to create these registry settings in the INF:

In Device Manager, you will see your device appear under USB Universal Serial Bus devices. However, the device class description is derived from the registry setting specified in your INF.

Note that the «USBDevice» class is not limited to WinUSB. If you have a custom driver for your device, you can use the «USBDevice» setup class in the custom INF.

During device enumeration, the USB driver stack reads the compatible ID from the device. If the compatible ID is «WINUSB», Windows uses it as the device identifier and finds a match in the updated in-box Winusb.inf, and then loads Winusb.sys as the device’s function driver.

This image is for a single interface MUTT device that is defined as a WinUSB device and as a result Winusb.sys gets loaded as the function driver for the device.

For versions of Windows earlier than WindowsВ 8, the updated Winusb.inf is available through Windows Update. If your computer is configured to get driver update automatically, WinUSB driver will get installed without any user intervention by using the new INF package.

How to change the device description for a WinUSB device

For a WinUSB device, Device Manager shows «WinUsb Device» as the device description. That string is derived from Winusb.inf. If there are multiple WinUSB devices, all devices get the same device description.

To uniquely identify and differentiate the device in Device Manager, WindowsВ 8 provides a new property on a device class that instructs the system to give precedence to the device description reported by the device (in its iProduct string descriptor) over the description in the INF. The «USBDevice» class defined in Windows 8 sets this property. In other words, when a device is installed under «USBDevice» class, system queries the device for a device description and sets the Device Manager string to whatever is retrieved in the query. In that case, the device description provided in the INF is ignored. Notice the device description strings: «MUTT» in the preceding image. The string is provided by the USB device in its product string descriptor.

The new class property is not supported on earlier versions of Windows. To have a customized device description on an earlier version of Windows, you have to write your own custom INF.

How to configure a WinUSB device

To identify a USB device as a WinUSB device, the device firmware must have Microsoft OS Descriptors. For information about the descriptors, see the specifications described here: Microsoft OS Descriptors.

Supporting extended feature descriptors

In order for the USB driver stack to know that the device supports extended feature descriptors, the device must define an OS string descriptor that is stored at string index 0xEE. During enumeration, the driver stack queries for the string descriptor. If the descriptor is present, the driver stack assumes that the device contains one or more OS feature descriptors and the data that is required to retrieve those feature descriptors.

The retrieved string descriptor has a bMS_VendorCode field value. The value indicates the vendor code that the USB driver stack must use to retrieve the extended feature descriptor.

For information about how to define an OS string descriptor, see «The OS String Descriptor» in the specifications described here: Microsoft OS Descriptors.

Setting the compatible ID

An extended compat ID OS feature descriptor that is required to match the in-box Winusb.inf and load the WinUSB driver module.

The extended compat ID OS feature descriptor includes a header section followed by one or more function sections depending on whether the device is a composite or non-composite device. The header section specifies the length of the entire descriptor, number of function sections, and version number. For a non-composite device, the header is followed by one function section associated with the device’s only interface. The compatibleID field of that section must specify «WINUSB» as the field value. For a composite device, there are multiple function sections. The compatibleID field of each function section must specify «WINUSB».

Registering a device interface GUID

An extended properties OS feature descriptor that is required to register its device interface GUID. The GUID is required to find the device from an application or service, configure the device, and perform I/O operations.

In previous versions of Windows, device interface GUID registration is done through the custom INF. Starting in Windows 8, your device should report the interface GUID by using extended properties OS feature descriptor.

The extended properties OS feature descriptor includes a header section that is followed by one or more custom property sections. The header section describes the entire extended properties descriptor, including its total length, the version number, and the number of custom property sections. To register the device interface GUID, add a custom property section that sets the bPropertyName field to «DeviceInterfaceGUID» and wPropertyNameLength to 40 bytes. Generate a unique device interface GUID by using a GUID generator and set the bPropertyData field to that GUID, such as «<8fe6d4d7-49dd-41e7-9486-49afc6bfe475>«. Note that the GUID is specified as a Unicode string and the length of the string is 78 bytes (including the null terminator).

7B 00 38 00 46 00 45 00 36 00 44 00 34 00 44 00 37 00 2D 00 34 00 39 00 00 44 00 2D 00 34 00 31 00 45 00 37 00 2D 00 39 00 34 00 38 00 36 00 2D 00 34 00 39 00 41 00 46 00 43 00 36 00 42 00 46 00 45 00 34 00 37 00 35 00 7D 00 00 00

bPropertyData

78 bytes

Property value is <8fe6d4d7-49dd-41e7-9486-49afc6bfe475>.

During device enumeration, The USB driver stack then retrieves the DeviceInterfaceGUID value from the extended properties OS feature descriptor and registers the device in the device’s hardware key. An application can retrieve the value by using SetupDiXxx APIs (See SetupDiOpenDevRegKey). For more information, see How to Access a USB Device by Using WinUSB Functions.

Enabling or disabling WinUSB power management features

Before WindowsВ 8, to configure power management features of WinUSB, you had to write registry entry values in the HW.AddReg section of your custom INF.

In WindowsВ 8, you can specify power settings in device. You can report values through the extended properties OS feature descriptor that enable or disable features in WinUSB for that device. There are two features that we can be configured: selective suspend and system wake. Selective suspend allows the device to enter low-power state when it is idle. System wake refers to the ability to a device to wake up a system when the system is in low-power state.

For information about power management features of WinUSB, see WinUSB Power Management.

Property name	Description
DeviceIdleEnabled	This value is set to 1 to indicate that the device can power down when idle (selective suspend).
DefaultIdleState	This value is set to 1 to indicate that the device can be suspended when idle by default.
DefaultIdleTimeout	This value is set to 5000 in milliseconds to indicate the amount of time in milliseconds to wait before determining that a device is idle.
UserSetDeviceIdleEnabled	This value is set to 1 to allow the user to control the ability of the device to enable or disable USB selective suspend. A check box Allow the computer to turn off this device to save power on the device Power Management property page and the user can check or uncheck the box to enable or disable USB selective suspend.
SystemWakeEnabled	This value is set to 1 to allow the user to control the ability of the device to wake the system from a low-power state. When enabled, the Allow this device to wake the computer check box appears in the device power management property page. The user can check or uncheck the box to enable or disable USB system wake.

For example, to enable selective suspend on the device, add a custom property section that sets the bPropertyName field to a Unicode string, «DeviceIdleEnabled» and wPropertyNameLength to 36 bytes. Set the bPropertyData field to «0x00000001». The property values are stored as little-endian 32-bit integers.

During enumeration, the USB driver stack reads the extended properties feature descriptors and creates registry entries under this key:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Enum\USB\ \ \Device Parameters

This image shows sample settings for a WinUSB device.

For additional examples, see the specifications on Microsoft OS Descriptors.

USB registry settings for a function controller driver

Summary

• Registry keys that must be set by OEMs to define USB descriptors.

Applies to:

Last updated:

OEMs must set several registry values to make sure that their device enumerates with the correct metadata when connected to a computer. These values specify device and configuration descriptors for the USB device-side drivers in Windows. OEMs that create and include their own interfaces must set additional registry values in order for their interfaces to be loaded and used.

Registry keys related to the device-side USB drivers are under:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN

This topic describes settings for the preceding key and subkeys that define the device, configuration, and interface descriptors for the device.

USBFN registry key

Configuration information for the USB device are under:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN

This table describes its subkeys. Some of them can be modified by OEMs. More information about the supported values for each subkey is provided in sections below.

Subkey	Description
Alternates	This subkey contains additional subkeys that describe an interface that has one or more alternate settings.
Associations	This subkey defines Interface Association Descriptors (IADs). Each IAD allows multiple interfaces to be grouped into a single function. Each subkey represents a different IAD and OEMs can modify the values for those subkeys.
Default	This subkey contains default values that are used to describe device-specific settings such as the VID and PID. This is a Microsoft-owned subkey whose values are overridden by those in the parent key.
Configurations	This subkey contains additional subkeys that contain configuration descriptor values that are used during USB enumeration. For example, the standard test configuration might exist under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Configurations\TestConfig.
Configurations\Default	This is a Microsoft-owned subkey. It contains values for the default configuration. The interfaces in the default configuration are added before the current configuration present when the IncludeDefaultCfg value is set to 1 under the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN key.
Interfaces	This subkey contains additional subkeys that describe specific interface descriptors. For example, the IP over USB interface may reside under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Interfaces\IpOverUsb. The name of the interface subkey is also used as the hardware ID of the USBFN child device for loading the USBFn class driver. In the IP over USB example, the hardware ID of the USBFN child device will be USBFN\IpOverUsb.

This table describes the values that OEMs can define in the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN key. Values that are not defined in this key assume the default values defined by Microsoft under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Default.

All OEMs must set the idVendor, idProduct, ManufacturerString, and ProductString values. OEMs that create and add their own interfaces must also set CurrentConfiguration to the name of the subkey under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Configurations that includes their interfaces in the InterfaceList.

Value	Type	Owner	Description
IncludeDefaultCfg	REG_DWORD	OEM	Set to 1 when OEMs want to include the interfaces of the Default configuration such as IpOverUsb or MTP.
idVendor	REG_DWORD	OEM	The vendor identifier for the device descriptor that is sent to the host during enumeration.
idProduct	REG_DWORD	OEM	The product identifier for the device descriptor that is sent to the host during enumeration.
ManufacturerString	REG_SZ	OEM	The manufacturer string that is sent to the host to identify the manufacturer of the device.
ProductString	REG_SZ	OEM	A string that describes the device as a product. The default value is WindowsВ 10 Mobile Device. This value is used as the display name of the device in the connected computer’s user interface. OEMs should make sure that this value matches the value of the PhoneModelName value under the DeviceTargetingInfo subkey.
iSerialNumber	REG_DWORD	OEM	If this value is set to 0, then the device does not have a serial number. If this value is non-zero or does not exist, then the serial number is generated uniquely per device.
CurrentConfiguration	REG_SZ	OEM	This string must correspond to the name of a configuration subkey. This string determines which configuration to use to build a configuration descriptor for USB device enumeration.

USBFN\Configurations registry key

This table describes the values that OEMs can define for subkeys under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Configurations. Each subkey represents a different USB configuration. If the OEM wants to create their own interface, the OEM must define a new configuration which contains the interfaces to be used. To do this, create a subkey under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Configurations that uses the name of the configuration and populate the subkey with the values in this table. Additionally, for the USB driver to use the new configuration, the CurrentConfiguration value (described in the preceding table) must be set to the name of the configuration subkey.

Contains a list of interface names that correspond to interface subkeys under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Interfaces, the IAD associations defined under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Associations, and the alternate interfaces defined under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Alternates. Those keys determine the interfaces that are used to describe the composite configuration descriptor.

If the IncludeDefaultCfg value under the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN key is set to 1, this list is appended to the Microsoft-owned default interface list to create the complete interface list that the device will use to enumerate.

Optional. Defines an Extended Compat ID OS Feature Descriptor for the configuration. If the IncludeDefaultCfg value under the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN key is set to 1, the functions in this descriptor are appended to the functions and interfaces in the default configuration.

USBFN\Interfaces registry key

This table describes the values that OEMs can modify for subkeys under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Interfaces.

Each subkey represents a different USB interface. To define an interface, create a subkey under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Interfaces using the name of the interface, and populate it with the values in the table below. Additionally, an interface will only be included if the interface is part of the InterfaceList of the CurrentConfiguration.

Value	Type	Owner	Description
InterfaceList	REG_MULTI_SZ	OEM or Microsoft
MSOSCompatIdDescriptor	REG_BINARY	OEM or Microsoft

Value	Type	Owner	Description
InterfaceDescriptor	REG_BINARY	OEM or Microsoft	A binary representation of an interface descriptor to send to the host during USB enumeration. The bInterfaceNumber and iInterface values are automatically populated by the USB function stack after compiling a full configuration descriptor to avoid conflicts with other interface descriptors.
InterfaceGUID	REG_SZ	OEM or Microsoft	A GUID that uniquely identifies an interface on the bus.
InterfaceNumber	REG_DWORD	OEM or Microsoft	Optional. This value is used to assign a fixed interface number to a function. Interface numbers 0-1F are reserved for legacy functions, 20-3F are reserved for Microsoft, and 40-5F are reserved for use by OEMs.
MSOSExtendedPropertyDescriptor	REG_BINARY	OEM or Microsoft	Optional. Defines an Extended Property OS Feature Descriptor for the interface.

USBFN\Alternates registry key

The alternates subkey is used to define a single interface that has one or more alternate interfaces. This table describes the values that OEMs can modify for subkeys under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Alternates.

Each subkey represents a different interface. To define an interface with alternate settings, create a subkey under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Alternates by using the name of the interface, and populate it with the values in the table below.

Value	Type	Owner	Description
InterfaceList	REG_MULTI_SZ	OEM or Microsoft	A list of two of more interface names that correspond to interfaces defined under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Interfaces. That key collectively defines an interface with alternate settings. The first interface corresponds to alternate setting 0, the second interface corresponds to alternate setting 1, and so on.
InterfaceNumber	REG_DWORD	OEM or Microsoft	Optional. This value is used to assign a fixed interface number to a function. Interface numbers 0-1F are reserved for legacy functions, 20-3F are reserved for Microsoft, and 40-5F are reserved for use by OEMs.
MSOSExtendedPropertyDescriptor	REG_BINARY	OEM or Microsoft	Optional. Defines an Extended Property OS Feature Descriptor for the interface.

USBFN\Associations registry key

OEMs can specify associations by defining Interface Association Descriptors (IADs). Each IAD allows multiple interfaces to be grouped into a single function. This table describes the values that OEMs can modify for subkeys under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Associations.

Each subkey represents a different IAD. To define an association, create a subkey under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\USBFN\Associations by using the name of the IAD, and populate it with the values in the table below.

Value	Type	Owner	Description
InterfaceList	REG_MULTI_SZ	OEM or Microsoft	A list of interfaces or alternate interfaces that are associated with a USB function. If the size of the list is less than 2, then the function driver stack fails to load. Other functions or interfaces continue to load.
bFunctionClass	REG_DWORD	OEM or Microsoft	The class code of the function, set to 02.
bFunctionSubClass	REG_DWORD	OEM or Microsoft	The subclass code of the function, set to 0d.
bFunctionProtocol	REG_DWORD	The protocol code of the function, set to 01.
MSOSExtendedPropertyDescriptor	REG_BINARY	OEM or Microsoft	Optional. Defines an Extended Property OS Feature Descriptor for the interface.

Use case: Enabling MirrorLink

MirrorLink is an interoperability standard that allows integration between mobile devices and car infotainment systems. The device must expose a USB CDC NCM interface to the MirrorLink client. As a Communications Device Class (CDC) device, it is required to describe the data interfaces by using either an Interface Association Descriptor (IAD) and/or a CDC Function Union Descriptor.

To enable MirrorLink connectivity on WindowsВ 10 Mobile Device, OEM must make these changes to expose an IAD.

Create an association for the communication and data interfaces by using an Interface Association Descriptor (IAD) by setting registry values shown in the preceding table.

In addition to the registry settings, set this registry value to a non-zero value.

Value	Type	Owner	Description
MirrorLink	REG_DWORD	OEM or Microsoft	A non-zero value indicates the interface supports MirrorLink. The USB function stack does not stall the MirrorLink USB command.

Class-specific descriptors can be included in the interface descriptor set that is defined in the registry. The size field must be set in those descriptors so that USB function driver stack can parse them accurately.

Alternatively, a CDC Function Union Descriptor can also be defined as a Class-Specific Interface Descriptor; however, the interface numbers specified by the Union descriptor are static and are not be assigned by the USB function driver stack, and the presence of a Union descriptor does not cause the interfaces described by it to be associated with a single child PDO. An IAD is required for that association.