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

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

• Раздел [DDInstall.wdf] для каждого раздела [DDInstall]
• Раздел [wdf-service-install] с именем раздела, указанным в директиве 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 = <ОтключеноОбщиеПроцессы | ВключеноОбщиеПроцессы>

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

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

UmdfDirectHardwareAccess

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

UmdfDirectHardwareAccess = <РазрешитьПрямойДоступКОборудованию | ОтклонитьПрямойДоступКОборудованию>

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

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

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

Сведения о подключении драйвера UMDF к определенным типам ресурсов см. в следующих статье:

• аппаратные ресурсы для User-Mode периферийных драйверов SPB
• Идентификаторы подключений для SPB-Connected периферийных устройств
• подключение периферийного драйвера 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 установит устройство, в любом заданном WDF-специфическом разделе DDInstall должна присутствовать только одна директива UmdfServiceOrder. То есть директива UmdfServiceOrder невозможно импортировать с помощью директив Include и Needs.

UmdfImpersonationLevel

UmdfImpersonationLevel = <level>

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

• Anonymous

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

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

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

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

UmdfMethodNeitherAction

UmdfMethodNeitherAction = <копировать | отклонить>

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

Дополнительные сведения о поддержке метода доступа к буферу 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 в разделе, специфическом для WDF, DDInstall.

[Xxx_Install.Wdf]
UmdfDispatcher=NativeUSB

UmdfKernelModeClientPolicy

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

UmdfKernelModeClientPolicy = <РазрешитьКлиентовРежимаЯдра | ОтклонитьКлиентовРежимаЯдра>

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

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

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

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

UmdfFileObjectPolicy

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

UmdfFileObjectPolicy = <ОтклонитьNullИНеизвестныеФайловыеОбъекты | РазрешитьNullИНеизвестныеФайловыеОбъекты>

Указывает, должна ли платформа разрешать обработку запросов ввода-вывода (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 = <версия>

Сообщает совместному установщику о номере версии платформы, которую будет использовать драйвер UMDF. Формат строки версии - <основной>.<незначительный>.<сервисный>. Если драйверы в стеке устройств используют более одной версии фреймворка, 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 заменит его правильным номером версии.