Specifying WDF Directives in INF Files

This topic applies to both User-Mode Driver Framework (UMDF) versions 1 and 2.

An INF file that installs a UMDF driver must contain a Microsoft Windows Driver Frameworks (WDF)-specific DDInstall section. The INF file can contain more than one WDF-specific DDInstall section if the INF file installs more than one WDF driver. Each WDF-specific DDInstall section:

  • Corresponds to the DDInstall and DDInstall.Services sections that are associated with a particular WDF driver.

  • Is processed by all the loaded WDF co-installers, which run in arbitrary order.

  • Contains WDF installation directives for a device. UMDF-specific directives begin with the UMDF prefix, and KMDF-specific directives begin with the KMDF prefix.

The following code example shows UMDF-specific directives in a WDF-specific DDInstall section.


[Skeleton_Install.Wdf]
UmdfService=UMDFSkeleton,UMDFSkeleton_Install
UmdfServiceOrder=UMDFSkeleton

Each UMDF-specific directive in the WDF-specific DDInstall section is described in the following list:

UmdfService = <serviceName>, <sectionName>

Associates a UMDF driver with a UMDF-service-install section that contains information that is required to install the UMDF driver. The serviceName parameter specifies the UMDF driver. The sectionName parameter references the UMDF-service-install section. A valid INF file typically requires at least one UmdfService directive. However, if a UMDF driver is part of the operating system, a UmdfService directive for the UMDF driver is not required. Therefore, a valid INF file might not have any UmdfService directives, although most INF files have one UmdfService directive for each UMDF driver.

UmdfHostProcessSharing = <ProcessSharingDisabled | ProcessSharingEnabled>

Determines whether a device stack is placed into a shared process pool (ProcessSharingEnabled) or its own individual process (ProcessSharingDisabled). The default is ProcessSharingEnabled. This directive is device-specific rather than driver-specific.

For more information about device pooling, see Using Device Pooling in UMDF Drivers.

UMDF versions 1.11 and later support the UmdfHostProcessSharing directive.

UmdfDirectHardwareAccess = <AllowDirectHardwareAccess | RejectDirectHardwareAccess>

Indicates whether the framework should allow the driver to use any of the direct hardware access features, such as accessing device registers and ports, scanning hardware resources assigned to the device, handling hardware interrupts, or acquiring connection resources.

If UmdfDirectHardwareAccess is set to AllowDirectHardwareAccess, the framework allows the driver to use UMDF interfaces that perform direct hardware access.

You must specify AllowDirectHardwareAccess if your UMDF driver accesses hardware resources such as registers or ports, interrupts, general-purpose I/O (GPIO) pins, or serial bus connections such as I2C, SPI, and serial port. Your driver receives all of these resources through the ResourcesRaw and ResourcesTranslated parameters of its EvtDevicePrepareHardware callback function.

For information about connecting a UMDF driver to particular types of resources, see:

If UmdfDirectHardwareAccess is set to RejectDirectHardwareAccess, the framework does not allow drivers to use any direct hardware access features. The default value is RejectDirectHardwareAccess.

For information about how a UMDF driver accesses hardware resources, see Finding and Mapping Hardware Resources.

UMDF versions 1.11 and later support the UmdfDirectHardwareAccess directive.

UmdfRegisterAccessMode = <RegisterAccessUsingSystemCall | RegisterAccessUsingUserModeMapping>

Indicates whether the framework should map the registers into user-mode address space (so that a system call is not involved in accessing registers), or use a system call to access registers.

If UmdfRegisterAccessMode is set to RegisterAccessUsingSystemCall, the framework uses a system call to access registers.

If UmdfRegisterAccessMode is set to RegisterAccessUsingUserModeMapping, the framework maps the registers into user-mode address space so that a system call is not needed to access registers. The default value is RegisterAccessUsingSystemCall.

UMDF versions 1.11 and later support the UmdfRegisterAccessMode directive.

UmdfServiceOrder = <serviceName1> [, <serviceName2> ...]

Lists the order that the co-installer installs the UMDF drivers on the device stack. Even if the co-installer installs only one UMDF driver on the device stack, the INF file must contain this directive. The serviceNameXx parameters correspond to the serviceName parameters for each UmdfService directive. Because the UMDF drivers are added to the device stack in the order that they are listed, the first parameter specifies the lowest UMDF driver in the device stack.

To ensure that a UMDF co-installer installs the device, only one UmdfServiceOrder directive must be present in any given WDF-specific DDInstall section. That is, the UmdfServiceOrder directive cannot be imported by using the Include and Needs directives.

UmdfImpersonationLevel = <level>

Informs the framework about the maximum impersonation level that the UMDF driver can have. A UmdfImpersonationLevel directive is optional; if an impersonation level is not specified, the default is Identification. When an application opens a file handle, the application can grant a greater impersonation level to the driver. However, the driver cannot call the IWDFIoRequest::Impersonate method to request an impersonation level that is greater than the level that UmdfImpersonationLevel specifies. The possible values for this directive are:

  • Anonymous

  • Identification

  • Impersonation

  • Delegation

These values correspond to the values that are specified in the SECURITY_IMPERSONATION_LEVEL enumeration.

UmdfMethodNeitherAction = <Copy | Reject>

Indicates whether the framework will accept (Copy) or reject (Reject) a device's I/O requests, if the request objects contain I/O control codes that specify the METHOD_NEITHER buffer access method. A UmdfMethodNeitherAction directive is optional. If the directive is not specified, the default value is Reject.

For more information about supporting the METHOD_NEITHER buffer access method in UMDF-based drivers, see Using Neither Buffered I/O nor Direct I/O in UMDF Drivers.

UmdfDispatcher = <FileHandle | WinUsb>

Informs the framework 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. A UmdfDispatcher directive is optional. If any UMDF driver in the user-mode device stack uses USB I/O targets, set this directive to WinUsb. If any driver in the stack uses a file-handle-based target, set this directive to FileHandle.

The following code example shows the UmdfDispatcher directive in a WDF-specific DDInstall section.


[Xxx_Install.Wdf]
UmdfDispatcher=WinUsb

A UMDF driver calls the IWDFFileHandleTargetFactory::CreateFileHandleTarget method to create a file-handle-based target and the IWDFUsbTargetFactory::CreateUsbTargetDevice method to create a USB target. If a value for the UmdfDispatcher directive is not specified, the framework sends requests to the kernel stack (that is, the framework sends requests to the reflector).

UmdfKernelModeClientPolicy = <AllowKernelModeClients | RejectKernelModeClients>

Indicates whether the framework should allow the driver to receive I/O requests from kernel-mode drivers.

If UmdfKernelModeClientPolicy is set to AllowKernelModeClients, the framework allows kernel-mode drivers to load above a user-mode driver, and it delivers I/O requests from kernel-mode drivers to the user-mode driver.

If UmdfKernelModeClientPolicy is set to RejectKernelModeClients, the framework does not allow kernel-mode drivers to load above a user-mode driver, and it does not deliver I/O requests from any kernel-mode drivers to the user-mode driver. If a driver's INF file does not contain this directive, the default value is RejectKernelModeClients. For more information, see Supporting Kernel-mode Clients.

UMDF versions 1.9 and later support the UmdfKernelModeClientPolicy directive. To allow kernel-mode drivers to load above a user-mode driver in earlier UMDF versions, see Kernel-mode Client Support in Earlier UMDF Versions.

UmdfFileObjectPolicy = <RejectNullAndUnknownFileObjects | AllowNullAndUnknownFileObjects>

Indicates whether the framework should allow processing of I/O requests (IWDFIoRequest) that are either not associated with a file object (IWDFFile) or are associated with an unknown file object (a file object for which a driver has not previously seen a create request).

If UmdfFileObjectPolicy is set to RejectNullAndUnknownFileObjects, the framework does not allow processing of requests that are associated with a NULL or unknown file object.

If UmdfFileObjectPolicy is set to AllowNullAndUnknownFileObjects, the framework allows processing of requests that are associated with a NULL or unknown file object.

The default value is RejectNullAndUnknownFileObjects.

UMDF versions 1.11 and later support the UmdfFileObjectPolicy directive.

UmdfFsContextUsePolicy = <CanUseFsContext | CanUseFsContext2 | CannotUseFsContexts>

Indicates whether the framework can store internal information in specific context members of a WDM file object. If a kernel-mode driver in the same stack uses a particular member of the file object, you can use this directive to request that the framework not use the same location.

If UmdfFsContextUsePolicy is set to CanUseFsContext, the framework stores information in the FsContext member of the WDM file object.

If UmdfFsContextUsePolicy is set to CanUseFsContext2, the framework stores information in the FsContext2 member of the WDM file object.

If UmdfFsContextUsePolicy is set to CannotUseFsContexts, the framework does not use either FsContext or FsContext2.

The default value is CanUseFsContext.

UMDF versions 1.11 and later support the UmdfFsContextUsePolicy directive.

The following code example shows the required directives in a UMDF-service-install section.


[UMDFSkeleton_Install]
UmdfLibraryVersion=1.0.0
ServiceBinary=%12%\UMDF\UMDFSkeleton.dll
DriverCLSID={d4112073-d09b-458f-a5aa-35ef21eef5de}

Each directive in the UMDF-service-install section is described in the following list:

UmdfLibraryVersion = <version>

Informs the co-installer about the version number of the framework that the UMDF driver will use. The format of the version string is <major>.<minor>.<service>. When drivers on the device stack use more than one version of the framework, the INF file copies multiple co-installers--one for each framework version--to the same location on the hard disk drive. However, the INF file adds only the highest version co-installer to the CoInstallers32 registry value. For more information about copying co-installers, see Using the UMDF Co-installer.

The co-installer verifies the version string and uses it to locate the version-specific co-installer for the UMDF driver. The co-installer then extracts the framework from the version-specific co-installer.

ServiceBinary = <binarypath>

Informs UMDF about where to place the UMDF driver binary on the hard disk drive.

UMDF drivers should be copied to, and run from, the \Windows\System32\Drivers\UMDF directory.

DriverCLSID = <{CLSID}>

Note  This directive is available in UMDF versions 1.11 and earlier.

Informs UMDF about the class identifier (CLSID) of the UMDF driver. When UMDF loads the UMDF driver, the UMDF host uses the UMDF driver's CLSID to create an instance of the UMDF driver's IDriverEntry interface.

On Windows 8.1 and earlier, to avoid a required reboot when you update a UMDF driver, specify the COPYFLG_IN_USE_RENAME flag in the CopyFiles Directive in your driver's INF file, as shown in this example:


[VirtualSerial_Install.NT]
CopyFiles=UMDriverCopy
 
[UMDriverCopy]
Virtualserial.dll,,,0x00004000  ; COPYFLG_IN_USE_RENAME


 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft