Указание директив WDF в INF-файлах

  • Статья

INF-файл, устанавливающий драйвер WDF, должен содержать два раздела, относящиеся к WDF:

  • Раздел [DDInstall.wdf] для каждого раздела [DDInstall]
  • [wdf-service-install] section, с именем раздела, указанным в kmdfService или директиве UmdfService в [DDInstall.wdf]

Эти разделы содержат директивы 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$

[Директивы UMDF для разделов DDInstall.WDF]

Ниже приведен пример кода. Каждая директива UMDF в разделе DDInstall.WDF описана ниже.

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

UmdfService

`UmdfService = <serviceName>, <sectionName>

Связывает драйвер UMDF с разделом [wdf-service-install], который содержит сведения, необходимые для установки драйвера UMDF. Параметр serviceName указывает драйвер UMDF и ограничен длиной не более 31 символа. Параметр sectionName ссылается на раздел [wdf-service-install]. Для допустимого INF-файла обычно требуется по крайней мере одна директива UmdfService . Однако если драйвер UMDF является частью операционной системы, директива UmdfService для драйвера UMDF не требуется. Таким образом, допустимый INF-файл может не содержать директивы UmdfService , хотя большинство INF-файлов имеют одну директиву UmdfService для каждого драйвера UMDF.

UmdfHostProcessSharing

Эта директива поддерживается в UMDF версии 1.11 и более поздних.

UmdfHostProcessSharing = <ProcessSharingDisabled | ProcessSharingEnabled>

Определяет, помещается ли стек устройств в общий пул процессов (ProcessSharingEnabled) или в отдельный процесс (ProcessSharingDisabled). Значение по умолчанию — ProcessSharingEnabled. Эта директива зависит от устройства, а не от драйвера.

Дополнительные сведения о пуле устройств см. в статье Использование пулов устройств в драйверах UMDF.

UmdfDirectHardwareAccess

Эта директива поддерживается в UMDF версии 1.11 и более поздних.

UmdfDirectHardwareAccess = <AllowDirectHardwareAccess | RejectDirectHardwareAccess>

Указывает, должна ли платформа разрешать драйверу использовать какие-либо функции прямого доступа к оборудованию, такие как доступ к регистрам устройств и портам, сканирование аппаратных ресурсов, назначенных устройству, обработка аппаратных прерываний или получение ресурсов подключения.

Если для параметра UmdfDirectHardwareAccess задано значение AllowDirectHardwareAccess, платформа позволяет драйверу использовать интерфейсы UMDF, которые выполняют прямой доступ к оборудованию.

Необходимо указать AllowDirectHardwareAccess , если драйвер UMDF обращается к аппаратным ресурсам, таким как регистры или порты, прерывания, контакты ввода-вывода общего назначения (GPIO) или последовательные подключения к шине, такие как I2C, SPI и последовательный порт. Драйвер получает все эти ресурсы с помощью параметров ResourcesRaw и ResourcesTranslated функции обратного вызова EvtDevicePrepareHardware .

Примечание

Начиная с UMDF версии 2.15 драйверу UMDF не нужно указывать AllowDirectHardwareAccess для получения списков аппаратных ресурсов в подпрограмме обратного вызова EvtDevicePrepareHardware . Если вы не укажете его, драйвер не имеет прав доступа для использования этих ресурсов, за одним исключением: если устройству назначен один или несколько ресурсов подключения (CmResourceTypeConnection) и один или несколько ресурсов прерываний (CmResourceTypeInterrupt), драйвер может вызвать WdfInterruptCreate из своей подпрограммы обратного вызова EvtDevicePrepareHardware (но не из EvtDriverDeviceAdd).

Сведения о подключении драйвера 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 соответствуют параметрам serviceName для каждой директивы UmdfService . Так как драйверы UMDF добавляются в стек устройств в порядке их перечисления, первый параметр указывает самый низкий драйвер UMDF в стеке устройств.

Чтобы обеспечить установку устройства с помощью совместного установщика UMDF, в любом разделе DDInstall для WDF должна присутствовать только одна директива UmdfServiceOrder. То есть директиву UmdfServiceOrder нельзя импортировать с помощью директив Include и Needs .

UmdfImpersonationLevel

UmdfImpersonationLevel = <level>

Информирует платформу о максимальном уровне олицетворения, который может иметь драйвер UMDF. Директива UmdfImpersonationLevel является необязательной; Если уровень олицетворения не указан, значение по умолчанию — Идентификация. Когда приложение открывает дескриптор файла, приложение может предоставить драйверу более широкий уровень олицетворения. Однако драйвер не может вызвать метод IWDFIoRequest::Impersonate для запроса уровня олицетворения, превышающего уровень, задающий UmdfImpersonationLevel . Возможные значения для этой директивы:

  • Анонимный

  • Идентификация

  • Олицетворение

  • Делегирование

Эти значения соответствуют значениям, указанным в перечислении SECURITY_IMPERSONATION_LEVEL .

UmdfMethodNeitherAction

UmdfMethodNeitherAction = <Copy | Reject>

Указывает, будет ли платформа принимать (копировать) или отклонять (отклонять) запросы ввода-вывода устройства, если объекты запроса содержат управляющие коды ввода-вывода, определяющие метод доступа к буферу METHOD_NEITHER . Директива UmdfMethodNeitherAction является необязательной. Если директива не указана, значение по умолчанию — Reject.

Дополнительные сведения о поддержке метода доступа к буферу METHOD_NEITHER в драйверах на основе UMDF см. в разделе Использование буферизованного ввода-вывода и прямого ввода-вывода в драйверах UMDF.

UmdfDispatcher

UmdfDispatcher = <FileHandle | WinUsb | NativeUSB>

Сообщает платформе, куда следует отправлять ввод-вывод после того, как ввод-вывод проходит через часть стека устройств в пользовательском режиме. По умолчанию ввод-вывод отправляется в отражатель (WUDFRd.sys). Задав для UmdfDispatcher значение WinUsb, драйвер указывает UMDF отправлять ввод-вывод в архитектуру WinUsb. Начиная с UMDF 2.15, при указании NativeUSB отражатель будет обрабатывать USB-ввод-вывод.

  • Если какой-либо драйвер в стеке использует целевой объект на основе дескриптора файлов, задайте для этой директивы значение FileHandle.
  • Если драйвер использует UMDF 2.15 или более поздней версии и использует целевые объекты ввода-вывода USB, задайте для этой директивы значение NativeUSB.
  • Если драйвер используется до UMDF 2.15 и использует целевые объекты ввода-вывода USB, задайте для этой директивы значение WinUsb.

Директива UmdfDispatcher является необязательной.

В следующем примере кода показана директива UmdfDispatcher в разделе DDInstall для WDF.

[Xxx_Install.Wdf]
UmdfDispatcher=NativeUSB

UmdfKernelModeClientPolicy

Эта директива поддерживается в UMDF версии 1.9 и более поздних.

UmdfKernelModeClientPolicy = <AllowKernelModeClients | RejectKernelModeClients>

Чтобы разрешить загрузку драйверов в режиме ядра выше драйвера пользовательского режима в более ранних версиях UMDF, см . раздел Поддержка клиентов в режиме ядра в более ранних версиях UMDF.

Указывает, должна ли платформа разрешать драйверу получать запросы ввода-вывода от драйверов режима ядра.

Если для параметра UmdfKernelModeClientPolicy задано значение AllowKernelModeClients, платформа позволяет драйверам в режиме ядра загружаться выше драйвера пользовательского режима и доставляет запросы ввода-вывода от драйверов режима ядра в драйвер пользовательского режима.

Если для параметра UmdfKernelModeClientPolicy задано значение RejectKernelModeClients, платформа не позволяет драйверам в режиме ядра загружаться выше драйвера пользовательского режима и не доставляет запросы ввода-вывода от любых драйверов в режиме ядра драйверу пользовательского режима. Если INF-файл драйвера не содержит эту директиву, значение по умолчанию — RejectKernelModeClients. Дополнительные сведения см. в разделе Поддержка клиентов в режиме ядра.

UmdfFileObjectPolicy

Эта директива поддерживается в UMDF версии 1.11 и более поздних.

UmdfFileObjectPolicy = <RejectNullAndUnknownFileObjects | AllowNullAndUnknownFileObjects>

Указывает, должна ли платформа разрешать обработку запросов ввода-вывода (IWDFIoRequest), которые либо не связаны с объектом файла (IWDFFile), либо связаны с неизвестным объектом файла (файловый объект, для которого драйвер ранее не видел запрос на создание).

Если для параметра UmdfFileObjectPolicy задано значение RejectNullAndUnknownFileObjects, платформа не разрешает обработку запросов, связанных с объектом NULL или неизвестным файлом.

Если для параметра UmdfFileObjectPolicy задано значение AllowNullAndUnknownFileObjects, платформа позволяет обрабатывать запросы, связанные с объектом NULL или неизвестным объектом файла.

Значение по умолчанию — RejectNullAndUnknownFileObjects.

UmdfFsContextUsePolicy

Эта директива поддерживается в UMDF версии 1.11 и более поздних.

UmdfFsContextUsePolicy = <CanUseFsContext | CanUseFsContext2 | CannotUseFsContexts>

Указывает, может ли платформа хранить внутреннюю информацию в определенных членах контекста объекта файла WDM. Если драйвер режима ядра в том же стеке использует определенный член объекта файла, можно использовать эту директиву, чтобы запросить использование платформой того же расположения.

Если для параметра UmdfFsContextUsePolicy задано значение CanUseFsContext, платформа сохраняет сведения в элементе FsContext объекта WDM-файла.

Если для параметра UmdfFsContextUsePolicy задано значение CanUseFsContext2, платформа сохраняет сведения в элементе FsContext2 объекта WDM-файла.

Если для параметра UmdfFsContextUsePolicy задано значение CannotUseFsContexts, платформа не использует FsContext или FsContext2.

Значение по умолчанию — CanUseFsContext.

[Директивы UMDF для раздела wdf-service-install]

Ниже приведен пример кода. Ниже описана каждая директива UMDF в разделе [wdf-service-install]. Имя раздела указывается в директиве UmdfService в разделе [DDInstall.wdf].

[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 об идентификаторе класса (CLSID) драйвера UMDF. Когда UMDF загружает драйвер UMDF, узел UMDF использует CLSID драйвера UMDF для создания экземпляра интерфейса IDriverEntry драйвера UMDF.

UmdfExtensions

UmdfExtensions = <cxServiceName>

Требуется для драйверов, взаимодействующих с драйверами расширения класса, предоставляемыми корпорацией Майкрософт. Параметр cxServiceName соответствует службе, связанной с двоичным файлом драйвера расширения класса.

Имена служб для драйверов расширения класса могут находиться в виде подраздела в следующем разделе реестра: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services

[Директивы KMDF для разделов DDInstall.WDF]

Ниже приведен пример кода. Каждая директива KMDF в разделе DDInstall.WDF описана ниже.

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

KmdfService

KmdfService = <serviceName>, <sectionName>

Связывает драйвер KMDF с разделом [wdf-service-install], который содержит сведения, необходимые для установки драйвера KMDF. Параметр serviceName указывает драйвер KMDF и ограничен длиной не более 31 символа. Параметр sectionName ссылается на раздел [wdf-service-install]. Для допустимого INF-файла обычно требуется по крайней мере одна директива KmdfService . Однако если драйвер KMDF является частью операционной системы, директива KmdfService для драйвера KMDF не требуется. Таким образом, допустимый INF-файл может не иметь директив KmdfService , хотя большинство INF-файлов имеют одну директиву KmdfService для каждого драйвера KMDF.

[Директивы KMDF для раздела wdf-service-install]

Ниже приведен пример кода. Ниже описана каждая директива KMDF в разделе [wdf-service-install]. Имя раздела происходит из директивы KmdfService в разделе DDInstall.wdf.

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

KmdfLibraryVersion

KmdfLibraryVersion = <version>

Формат строки версии — major.minor. Как правило, следует указать $KMDFVERSION$ , и в этом случае процесс сборки WDK заменит его правильным номером версии.