Building an INF File for a Windows SideShow-Compatible Device

An INF file is a text file that contains all the information necessary to install a device, such as driver names and locations, registry information, version information, and other data that is used by the setup components during driver installation. To install any Microsoft Windows driver, it must have an accompanying INF file. If you have not yet installed drivers, you may want to refer to Device Installation Overview for an introduction to driver installation.

The Windows SideShow sample driver in the Windows Driver Kit (WDK) contains an associated INF file that shows the minimum sections that are required to install a user-mode driver that does not use any additional kernel or user-mode transport drivers. This section describes the INF file for a USB-connected device that uses the Windows USB (WinUSB) transport driver.

Sample INF File for a USB-Connected Device

An INF file contains many different sections that may or may not be necessary for your particular driver. This example describes an INF file for a USB-connected device that uses WinUSB as the kernel-mode USB driver. The full sample INF is located in Sample INF File.

Note   The INF file described in this section includes the sections that must be included for a device that uses the WinUSB driver.

Identifying Version Information

Information about the driver is contained in the Version section of the INF file. One of the more important entries is the ClassGuid directive, which should always have a value of {997B5D8D-C442-4F2E-BAF3-9C8E671E9E21}. This GUID is the device class GUID for Windows SideShow-compatible devices, and it is defined in devguid.h. For more information about the Version section, see INF File Sections and Directives. The Version section is required. By convention, it appears first in the INF file.

Version SectionDirective Description

Signature = "$Windows NT$"

Required. Contains information about the driver package.

ClassGuid = {997B5D8D-C442-4F2E-BAF3-9C8E671E9E21}

Contains the device class GUID for Windows SideShow-compatible devices.

Provider = %MyProvider%

Contains the name of the provider. This is a reference to a string in the Strings section.

DriverVer = MM/DD/YYYY,n.n.n.n

Contains the date when the driver was last compiled, and the version number.

CatalogFile = <MyDriver>.cat

States the name of the catalog file for the driver. This is required for drivers that are to be signed, and is not required for unsigned drivers.

 

Mapping the Manufacturer to a Device Model

Each directive in the Manufacturer section maps a manufacturer's name to the name of a Models section. The Manufacturer section identifies the manufacturer of one or more devices that are installed by the INF file. Additionally, the directive indicates which architectures the driver installs on. For more information about the Manufacturer section, see INF Manufacturer Section.

Note   This sample INF file installs on x86, x64, and ia64 architectures.

Manufacturer SectionDirective Description

%MyProvider% = <MyDeviceSection>,NTx86,NTia64,NTamd64

The provider supports the Microsoft Windows operating systems (OS) on x86, x64, and ia64 platforms.

 

The Models section determines how your INF file is associated with your hardware. The following directive describes a typical USB port device connection:


%USB\MyDevice.DeviceDesc% = USB_Install,USB\VID_xxxx&PID_xxxx

The first part of the string, enclosed in % operators, is the friendly name of the device. This value is later set in the Strings section of the INF file. The USB_Install value corresponds to the name of the DDInstall section that will be executed when the device is installed. For more information about the Models section, see INF Models Section.

Models SectionDirective Description

[<MyDeviceSection>.NTx86]

%USB\MyDevice.DeviceDesc% =USB_Install,USB\VID_xxxx&PID_xxxx

This section is used when installing a USB device with a hardware ID of USB\VID_xxxx&PID_xxxx on an x86 machine.

<MyDeviceSection>.NTia64]

%USB\MyDevice.DeviceDesc% =USB_Install,USB\VID_xxxx&PID_xxx

This section is used when installing a USB device with a hardware ID of USB\VID_xxxx&PID_xxxx on an ia64 machine.

[<MyDeviceSection>.NTamd64]

%USB\MyDevice.DeviceDesc% =USB_Install,USB\VID_xxxx&PID_xxxx

This section is used when installing a USB device with a hardware ID of USB\VID_xxxx&PID_xxxx on an x64 machine.

 

Device-Specific DDInstall Sections

The USB_Install section is the [DDInstall] section for a device. The CopyFiles directive specifies a list of files that must be copied to properly install the driver for the device.

The DDInstall.CoInstallers section contains directives that instruct the system to use the User-Mode Driver Framework (UMDF) co-installer when installing a device. This ensures that the driver framework is properly installed for your driver. The co-installer DLL is installed with Windows Vista by default and does not need to be distributed by your driver. Additional device co-installers, for example one to provide device configuration property pages, may also be specified by this section.

USB_Install SectionDirective Description

Include = winusb.inf

Needs = WINUSB.NT

The first two directives tell the installer to include the INF file for WinUSB (winusb.inf) and to execute the WINUSB.NT install section to ensure that WinUSB is properly installed for use by this device.

CopyFiles = UMDriverCopy

Copies installation files from a list of filenames that are specified in the UMDriverCopy section.

AddProperty = DriverProperties

Specifies the section containing additional device properties to be associated with this device.

USB_Install.CoInstallers SectionDirective Description

AddReg = WUDF_CoInstallers_AddReg

Registers one or more device-specific co-installers that are supplied on the distribution media (or part of the OS), to supplement the operations of existing device class installers. The referenced WUDF_CoInstallers_AddReg section is shown below.

USB_Install.Wdf SectionDirective Description

The DDInstall.Wdf section is parsed by the UMDF co-installer to determine how to configure your user-mode driver. Documentation for this section is available in the WDK. The following four directives are required for a user-mode driver that uses WinUSB:

  • UmdfService

  • UmdfServiceOrder

  • UmdfImpersonationLevel

  • UmdfDispatcher

UmdfService = <MyDriverServiceName>, <MyDriverServiceName>_Install

Specifies the name of the driver service to load. The first part contains a unique name associated with your driver, and the second part specifies the section containing information about your driver binary (DLL).

UmdfServiceOrder = <MyDriverServiceName>

Typically, your user-mode driver is the only user-mode driver in the stack. This directive allows you to specify the order of the user-mode drivers in the stack, should there be more than one. In the standard case, you just list the name of your driver service that was used in the previous UmdfService directive.

UmdfImpersonationLevel = Impersonation

Specifies that the user-mode driver is allowed to perform impersonation for certain security checks. The Windows SideShow class extension requires this setting, and the driver will not function properly without it.

UmdfDispatcher = WinUsb

Informs UMDF where to send I/O after the I/O goes through the user-mode portion of the device stack. By default, I/O is sent to the reflector (WUDFRd.sys). By setting UmdfDispatcher to WinUsb, the driver instructs UMDF to send I/O to the WinUsb architecture. For more information about the UmdfDispatcher directive, see Specifying the UmdfDispatcher INF Directive.

USB_Install.HW SectionDirective Description

AddReg = WINUSBTransport_AddReg

Installs the WinUSB kernel-mode driver as a lower filter driver for your device. If your driver uses WinUSB to communicate with your device, you should include this setting. The relevant WINUSBTransport_AddReg section is shown below. For more information about the HW section, see INF DDInstall.HW Section.

USB_Install.Services SectionDirective Description

Contains all of the kernel-mode filter drivers that are associated with this device. In the INF file sample, there are two entries--one for WUDFRd (the UMDF redirector driver), and one for WinUSB. The former is required for all user-mode drivers. The latter is required only if using WinUSB.

Note   The difference in the flags is that the WUDFRd is specified as the associate service, while WinUSB is specified as a filter driver.

AddService = WUDFRd, 0x000001fa, WUDFRD_ServiceInstall

Required. Adds the WUDFRd service.

Include = winusb.inf

AddService = WinUsb, 0x000001f8, WINUSB.AddService

Adds the WinUSB service. Note the Include directive, which tells the installer to include the WinUSB.inf file and reference the WINUSB.AddService section from that INF.

WINUSBTransport_AddReg SectionDirective Description

HKR,,"LowerFilters",0x00010008,"WinUsb" ; FLG_ADDREG_TYPE_MULTI_SZ | FLG_ADDREG_APPEND

Adds a registry key to indicate that WinUSB is a lower filter driver for this driver stack.

 

Driver Properties Section

This section contains additional device properties that configure various extensibility aspects of the driver. In this section, you can specify a custom device icon to be used for the device, as well as the commands to invoke custom device configuration UI. The name of this section can be determined by the INF writer, as long as the name is referenced by an appropriate AddProperty directive.

DriverProperty sectionDirective Description

This section is referenced by the AddProperty directive in the USB_Install section.

DeviceIcon,,,,"%1%\<MyDriverDLLName>.dll,-<resource id>"

Specifies the custom device icon to be used to represent the device in Windows SideShow in Control Panel and Device Manager. It should be a pointer to a resource ID in an existing module.

{BA554A34-3371-45b5-8DE9-B45E2A33D7DC},1,18,,"%systemroot%\system32\rundll32.exe devmgr.dll,DeviceProperties_RunDLL /DeviceID %DeviceID%"

Specifies the GUID and PID for the value that the Windows SideShow platform uses to invoke custom device configuration UI. In this particular example, the platform invokes the standard Device Manager properties page for the device. For more information, see Device Driver Extensibility.

{BA554A34-3371-45b5-8DE9-B45E2A33D7DC},2,18,,"Additional Options"

Specifies the GUID and PID for the string or resource that is used as the text for the extensibility command above. This link is displayed on the device configuration page in Windows SideShow in Control Panel.

 

UMDF Directives

The next sections specify information about the user-mode driver that is required by the User-Mode Driver Framework (UMDF).

WUDF_CoInstallers_AddReg SectionDirective Description

HKR,,CoInstallers32,0x00010000,"WUDFCoInstaller.dll"

Installs the registry key that points to the UMDF co-installer. This is referenced from the USB_Install.CoInstallers section.

<MyDriverServiceName>_Install SectionDirective Description

This section specifies the required UMDF directives for installing a user-mode driver.

UmdfLibraryVersion = 1.0.0

Informs the co-installer about the version number of the framework that the UMDF driver will use.

ServiceBinary = "%12%\umdf\<MyDriverDLLName>.dll"

Informs UMDF about where to place the UMDF driver binary on the hard disk drive. All user-mode drivers should be installed to the \windows\system32\drivers\umdf directory (%12% refers to \windows\system32\drivers\).

DriverCLSID = <CLSID of class that implements IDriverEntry>

Informs UMDF about the CLSID of the UMDF driver. UMDF uses the CLSID to create an instance of the driver's IDriverEntry interface.

 

DestinationDirs and CopyFiles Sections

The DestinationDirs directive specifies the target destination directory for your driver binary. User-mode drivers should be located in %windir%\system32\drivers\umdf, which corresponds to a dirid of 12 (%windir%\system32\drivers), and a subdir of UMDF. For more information, see INF DestinationDirs Section.

DestinationDirs SectionDirective Description

UMDriverCopy=12,UMDF; copy to drivers\umdf

Required in any INF file that uses an or that references a file-list-section, whether with a CopyFiles, DelFiles, or RenFiles directive. Specifies the target destination directory or directories for all copy, delete, and/or rename operations on files referenced by name elsewhere in the INF file.

UMDriverCopy SectionDirective Description

<MyDriverDLLName>.dll

States the name of the UMDF driver to copy.

 

SourceDisksFiles Section

The SourceDisksFiles section contains a list of all associated files that can be installed with your driver, as well as which disk they live on. Typically all files are on the same media, and can specify the same disk ID ("1", in the sample).

Note   The UMDriverCopy section contains a list of the files that are copied during driver installation. All files listed in the SourceDisksFiles section should be referenced by one CopyFiles directive. For more information, see INF SourceDisksFiles Section.

SourceDisksFiles SectionDirective Description

<MyDriverDLLName>.dll=1

Names the source files used during installation, identifies the installation disks that contain those files, and provides the path to the subdirectories, if any, on the distribution disks containing individual files.

Do not use a SourceDisksFiles section to copy INF files.

 

SourceDisksNames Section

The SourceDisksNames section contains the name of the source disks specified in the SourceDisksFiles section. This should reference a string value from the Strings section. For more information, see INF SourceDisksNames Section.

SourceDisksNames SectionDirective Description

1 = %MediaDescription%

Identifies the distribution disks or CD-ROM discs that contain the source files to be transferred to the target machine during installation.

 

Installing the UMDF Service

The WUDFRd_ServiceInstall section specifies information about the kernel-mode service to be installed as a filter driver. It is required as-is. This section does require certain values, such as SERVICE_KERNEL_DRIVER, to be present in the Strings section of the INF file.

WUDFRd_ServiceInstall SectionDirective Description

ServiceType = %SERVICE_KERNEL_DRIVER%

States that the service type is a driver.

StartType = %SERVICE_DEMAND_START%

Starts the service by using the Service Control Manager when a process calls the StartService function.

ErrorControl = %SERVICE_ERROR_NORMAL%

Logs the error but continues the startup operation.

ServiceBinary = %12%\WUDFRd.sys

Provides the location of the binary service driver.

 

Installing the WinUSB Service

The WinUSB Service Install section is located in winusb.inf, the INF file for WinUSB, which is included in Windows Vista. The sample INF file should use the Include directive to include the additional INF file and reference the existing service install section.

Mapping String Tokens

An INF file must have at least one Strings section to define every %strkey% token specified elsewhere in that INF file. For more information about the String directive, see INF Strings Section.

Strings SectionDirective Description

Provider = "My Device Provider"

Provides the name of the device manufacturer.

MediaDescription = "My Device Installation Media"

Provides the name of the driver installation media.

USB\MyDevice.DeviceDesc = "My Device Description"

Contains a description of the device, which is shown as the device name in Device Manager.

SERVICE_DEMAND_START = 0x3

Starts a service on demand.

SERVICE_KERNEL_DRIVER = 0x1

Specifies that the type of service is a driver service.

SERVICE_ERROR_NORMAL = 0x1

Logs the error but continues the startup operation.

 

Please refer to the associated MSDN documentation for information on the standard directives and their meanings.

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft