在 INF 文件中指定 WDF 指令

  • 项目

安装 WDF 驱动程序的 INF 文件必须包含两个特定于 WDF 的部分：

  • 每个 [DDInstall] 节的 [DDInstall.wdf] 节
  • [wdf-service-install] 节，在 [DDInstall.wdf] 中的 KmdfService 或 UmdfService 指令中指定了节名称

这些部分包含特定于 WDF 的指令。 特定于 UMDF 的指令以 UMDF 前缀开头，特定于 KMDF 的指令以 KMDF 前缀开头。

下面的代码示例演示特定于 UMDF 的指令：

[ECHO_Device.NT.Wdf]
UmdfService = Echo, Echo_service_wdfsect
UmdfServiceOrder = Echo

[Echo_service_wdfsect]
UmdfLibraryVersion = $UMDFVERSION$
ServiceBinary = %13%\echo.dll

下面的代码示例显示了特定于 KMDF 的指令：

[ECHO_Device.NT.Wdf]
KmdfService = Echo, Echo_service_wdfsect

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

[DDInstall.WDF 节的 UMDF 指令]

下面是一个代码示例。 下面介绍了 DDInstall.WDF 部分中每个特定于 UMDF 的指令。

[ECHO_Device.NT.Wdf]
UmdfService = Echo, Echo_service_wdfsect
UmdfServiceOrder = Echo

UmdfService

`UmdfService = <serviceName>， <sectionName>

将 UMDF 驱动程序与包含安装 UMDF 驱动程序所需的信息的 [wdf-service-install] 部分相关联。 serviceName 参数指定 UMDF 驱动程序，长度限制为最多 31 个字符。 sectionName 参数引用 [wdf-service-install] 节。 有效的 INF 文件通常需要至少一个 UmdfService 指令。 但是，如果 UMDF 驱动程序是操作系统的一部分，则不需要 UMDF 驱动程序的 UmdfService 指令。 因此，尽管大多数 INF 文件为每个 UMDF 驱动程序都有一个 UmdfService 指令，但有效的 INF 文件可能没有任何 UmdfService 指令。

UmdfHostProcessSharing

UMDF 版本 1.11 及更高版本中支持此指令。

UmdfHostProcessSharing = <ProcessSharingDisabled | ProcessSharingEnabled>

确定设备堆栈是放置在共享进程池 (ProcessSharingEnabled) 还是将其自己的单个进程 (ProcessSharingDisabled) 。 默认值为 ProcessSharingEnabled。 此指令特定于设备，而不是特定于驱动程序。

有关设备池的详细信息，请参阅 在 UMDF 驱动程序中使用设备池。

UmdfDirectHardwareAccess

UMDF 版本 1.11 及更高版本中支持此指令。

UmdfDirectHardwareAccess = <AllowDirectHardwareAccess | RejectDirectHardwareAccess>

指示框架是否应允许驱动程序使用任何直接硬件访问功能，例如访问设备寄存器和端口、扫描分配给设备的硬件资源、处理硬件中断或获取连接资源。

如果 UmdfDirectHardwareAccess 设置为 AllowDirectHardwareAccess，则框架允许驱动程序使用执行直接硬件访问的 UMDF 接口。

如果 UMDF 驱动程序访问硬件资源（例如寄存器或端口、中断、常规用途 I/O (GPIO) 引脚）或串行总线连接（如 I2C、SPI 和串行端口），则必须指定 AllowDirectHardwareAccess。 驱动程序通过其 EvtDevicePrepareHardware 回调函数的 ResourcesRaw 和 ResourcesTranslated 参数接收所有这些资源。

注意

从 UMDF 版本 2.15 开始，UMDF 驱动程序不需要指定 AllowDirectHardwareAccess 即可在其 EvtDevicePrepareHardware 回调例程中接收硬件资源列表。 如果未指定，则驱动程序没有使用这些资源的访问权限， 但有一个例外：如果为设备分配了一个或多个连接资源 (CmResourceTypeConnection) ， (CmResourceTypeInterrupt) ，驱动程序可以从其 EvtDevicePrepareHardware 回调例程 (调用 WdfInterruptCreate，但不能从 EvtDriverDeviceAdd) 调用 WdfInterruptCreate。

有关将 UMDF 驱动程序连接到特定类型的资源的信息，请参阅：

如果 UmdfDirectHardwareAccess 设置为 RejectDirectHardwareAccess，则框架不允许驱动程序使用任何直接硬件访问功能。 默认值为 RejectDirectHardwareAccess。

有关 UMDF 驱动程序如何访问硬件资源的信息，请参阅 查找和映射硬件资源。

UmdfHostPriority

UMDF 版本 2.15 及更高版本中支持此指令。

UmdfHostPriority = <PriorityHigh>

UMDF HID 客户端驱动程序可以将 UmdfHostPriority 设置为 PriorityHigh 以增加其线程优先级。 此指令应仅用于对用户响应时间敏感的触摸或输入驱动程序。 当驱动程序指定 PriorityHigh 时，系统会将其与其他具有类似优先级的驱动程序一起放入单独的设备池中。 由于其他设备池使用更多内存，因此应谨慎使用此设置。 有关设备池的详细信息，请参阅 在 UMDF 驱动程序中使用设备池。

UmdfRegisterAccessMode

UMDF 版本 1.11 及更高版本中支持此指令。

UmdfRegisterAccessMode = <RegisterAccessUsingSystemCall | RegisterAccessUsingUserModeMapping>

指示框架是否应将寄存器映射到用户模式地址空间 (以便系统调用不涉及访问寄存器) ，或使用系统调用访问寄存器。

如果 UmdfRegisterAccessMode 设置为 RegisterAccessUsingSystemCall，框架将使用系统调用来访问寄存器。

如果 UmdfRegisterAccessMode 设置为 RegisterAccessUsingUserModeMapping，则框架会将寄存器映射到用户模式地址空间，以便无需系统调用即可访问寄存器。 默认值为 RegisterAccessUsingSystemCall。

UmdfServiceOrder

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

列出共同安装程序在设备堆栈上安装 UMDF 驱动程序的顺序。 即使辅助安装程序在设备堆栈上只安装一个 UMDF 驱动程序，INF 文件也必须包含此指令。 serviceNameXx 参数对应于每个 UmdfService 指令的 serviceName 参数。 由于 UMDF 驱动程序按其列出顺序添加到设备堆栈，因此第一个参数指定设备堆栈中最低的 UMDF 驱动程序。

为了确保 UMDF 协同安装程序安装设备，任何给定的特定于 WDF 的 DDInstall 节中都必须存在一个 UmdfServiceOrder 指令。 也就是说，无法使用 Include 和 Needs 指令导入 UmdfServiceOrder 指令。

UmdfImpersonationLevel

UmdfImpersonationLevel = <level>

通知框架 UMDF 驱动程序可以具有的最大模拟级别。 UmdfImpersonationLevel 指令是可选的;如果未指定模拟级别，则默认值为 Identification。 当应用程序打开文件句柄时，应用程序可以向驱动程序授予更高的模拟级别。 但是，驱动程序无法调用 IWDFIoRequest：：Impersonate 方法来请求大于 UmdfImpersonationLevel 指定的级别的模拟级别。 此指令的可能值为：

  • 匿名

  • 标识

  • 模拟

  • 委托

这些值对应于 SECURITY_IMPERSONATION_LEVEL 枚举中指定的值。

UmdfMethodNeitherAction

UmdfMethodNeitherAction = <复制 | 拒绝>

指示如果请求对象包含指定METHOD_NEITHER缓冲区访问方法的 I/O 控制代码，框架是接受 (复制) 还是拒绝 (拒绝) 设备的 I/O 请求。 UmdfMethodNeitherAction 指令是可选的。 如果未指定 指令，则默认值为 Reject。

有关在基于 UMDF 的驱动程序中支持METHOD_NEITHER缓冲区访问方法的详细信息，请参阅 在 UMDF 驱动程序中使用非缓冲 I/O 和直接 I/O。

UmdfDispatcher

UmdfDispatcher = <FileHandle | WinUsb | NativeUSB>

在 I/O 通过设备堆栈的用户模式部分后，通知框架发送 I/O 的位置。 默认情况下，I/O 发送到反射器 (WUDFRd.sys) 。 通过将 UmdfDispatcher 设置为 WinUsb，驱动程序指示 UMDF 将 I/O 发送到 WinUsb 体系结构。 从 UMDF 2.15 开始，指定 NativeUSB 会使反射器处理 USB I/O。

  • 如果堆栈中的任何驱动程序使用基于文件句柄的目标，请将此指令设置为 FileHandle。
  • 如果驱动程序使用 UMDF 2.15 或更高版本并使用 USB I/O 目标，请将此指令设置为 NativeUSB。
  • 如果驱动程序是 UMDF 2.15 之前的并且使用 USB I/O 目标，请将此指令设置为 WinUsb。

UmdfDispatcher 指令是可选的。

下面的代码示例演示特定于 WDF 的 DDInstall 节中的 UmdfDispatcher 指令。

[Xxx_Install.Wdf]
UmdfDispatcher=NativeUSB

UmdfKernelModeClientPolicy

UMDF 版本 1.9 及更高版本中支持此指令。

UmdfKernelModeClientPolicy = <AllowKernelModeClients | RejectKernelModeClients>

若要允许内核模式驱动程序在早期 UMDF 版本中的用户模式驱动程序之上加载，请参阅 早期 UMDF 版本中的内核模式客户端支持。

指示框架是否应允许驱动程序从内核模式驱动程序接收 I/O 请求。

如果 UmdfKernelModeClientPolicy 设置为 AllowKernelModeClients，则框架允许内核模式驱动程序加载到用户模式驱动程序之上，并将 I/O 请求从内核模式驱动程序传递到用户模式驱动程序。

如果 UmdfKernelModeClientPolicy 设置为 RejectKernelModeClients，则框架不允许内核模式驱动程序加载到用户模式驱动程序上方，并且不会将 I/O 请求从任何内核模式驱动程序传递到用户模式驱动程序。 如果驱动程序的 INF 文件不包含此指令，则默认值为 RejectKernelModeClients。 有关详细信息，请参阅 支持内核模式客户端。

UmdfFileObjectPolicy

UMDF 版本 1.11 及更高版本中支持此指令。

UmdfFileObjectPolicy = <RejectNullAndUnknownFileObjects | AllowNullAndUnknownFileObjects>

指示框架是否应允许处理 IWDFIoRequest) (IWDFIoRequest) ，这些请求 (IWDFFile) 未与文件对象关联，或与未知文件对象关联， (驱动程序以前未看到创建请求) 的文件对象。

如果 UmdfFileObjectPolicy 设置为 RejectNullAndUnknownFileObjects，则框架不允许处理与 NULL 或未知文件对象关联的请求。

如果 UmdfFileObjectPolicy 设置为 AllowNullAndUnknownFileObjects，则框架允许处理与 NULL 或未知文件对象关联的请求。

默认值为 RejectNullAndUnknownFileObjects。

UmdfFsContextUsePolicy

UMDF 版本 1.11 及更高版本中支持此指令。

UmdfFsContextUsePolicy = <CanUseFsContext | CanUseFsContext2 | CannotUseFsContexts>

指示框架是否可以将内部信息存储在 WDM 文件对象的特定上下文成员中。 如果同一堆栈中的内核模式驱动程序使用文件对象的特定成员，则可以使用此指令请求框架不使用相同的位置。

如果 UmdfFsContextUsePolicy 设置为 CanUseFsContext，框架会将信息存储在 WDM 文件对象的 FsContext 成员中。

如果 UmdfFsContextUsePolicy 设置为 CanUseFsContext2，框架会将信息存储在 WDM 文件对象的 FsContext2 成员中。

如果 UmdfFsContextUsePolicy 设置为 CannotUseFsContexts，则框架不使用 FsContext 或 FsContext2。

默认值为 CanUseFsContext。

[wdf-service-install 部分的 UMDF 指令]

下面是一个代码示例。 [wdf-service-install] 部分中每个特定于 UMDF 的指令如下所述。 节名称在 [DDInstall.wdf] 节的 UmdfService 指令中指定。

[Echo_service_wdfsect]
UmdfLibraryVersion = $UMDFVERSION$
ServiceBinary = %13%\echo.dll

UmdfLibraryVersion

UmdfLibraryVersion = <version>

通知共同安装程序 UMDF 驱动程序将使用的框架的版本号。 版本字符串的格式是<主要>格式。<minor>。<service>。 当设备堆栈上的驱动程序使用框架的多个版本时，INF 文件会将多个共同安装程序（每个框架版本各有一个）复制到硬盘驱动器上的同一位置。 但是，INF 文件仅将最高版本的共同安装程序添加到 CoInstallers32 注册表值。 有关复制共同安装程序的详细信息，请参阅 使用 UMDF 共同安装程序。

共同安装程序验证版本字符串，并使用它来查找 UMDF 驱动程序的特定于版本的共同安装程序。 然后，共同安装程序从特定于版本的共同安装程序中提取框架。

ServiceBinary

ServiceBinary = <binarypath>

通知 UMDF 在硬盘驱动器上放置 UMDF 驱动程序二进制文件的位置。

UMDF 驱动程序应复制到目录并从中 Windows\System32\Drivers\UMDF 运行。

DriverCLSID

注意 此指令仅在已弃用的 UMDF 1.x 中受支持。 有关详细信息，请参阅 UMDF 1.x 设计指南。

DriverCLSID = <{CLSID}>

通知 UMDF 有关 UMDF 驱动程序的类标识符 (CLSID) 。 当 UMDF 加载 UMDF 驱动程序时，UMDF 主机使用 UMDF 驱动程序的 CLSID 创建 UMDF 驱动程序的 IDriverEntry 接口的实例。

UmdfExtensions

UmdfExtensions = <cxServiceName>

对于与 Microsoft 提供的类扩展驱动程序通信的驱动程序是必需的。 cxServiceName 参数对应于与类扩展驱动程序二进制文件关联的服务。

类扩展驱动程序的服务名称可以作为子项位于以下注册表项下： HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services

[DDInstall.WDF 节的 KMDF 指令]

下面是一个代码示例。 下面介绍了 DDInstall.WDF 部分中每个特定于 KMDF 的指令。

[ECHO_Device.NT.Wdf]
KmdfService = Echo, Echo_service_wdfsect

KmdfService

KmdfService = <serviceName>， <sectionName>

将 KMDF 驱动程序与包含安装 KMDF 驱动程序所需的信息的 [wdf-service-install] 部分相关联。 serviceName 参数指定 KMDF 驱动程序，长度限制为最多 31 个字符。 sectionName 参数引用 [wdf-service-install] 部分。 有效的 INF 文件通常需要至少一个 KmdfService 指令。 但是，如果 KMDF 驱动程序是操作系统的一部分，则不需要 KMDF 驱动程序的 KmdfService 指令。 因此，尽管大多数 INF 文件为每个 KMDF 驱动程序提供一个 KmdfService 指令，但有效的 INF 文件可能没有任何 KmdfService 指令。

[wdf-service-install 部分的 KMDF 指令]

下面是一个代码示例。 [wdf-service-install] 部分中每个特定于 KMDF 的指令如下所述。 节名称来自 DDInstall.wdf 节中的 KmdfService 指令。

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

KmdfLibraryVersion

KmdfLibraryVersion = <version>

版本字符串的格式为 major.minor。 通常应指定 $KMDFVERSION$ ，然后 WDK 生成过程会将它替换为正确的版本号。