Проверка драйверов Windows

Статья
04/05/2024

Используйте средства InfVerif, проверки изоляции драйверов проверки драйвера и ApiValidator для тестирования пакета драйверов для соответствия требованиям драйверов Windows, описанным в статье "Начало работы с драйверами Windows".

InfVerif

InfVerif — это средство, которое проверяет синтаксис INF и проверка, что INF соответствует требованиям и ограничениям.

Используйте InfVerif, /w чтобы убедиться, что драйвер Windows:

Соответствует декларативному принципу (D) принципов проектирования DCH
Соответствует требованиям к изоляции пакета драйвера для начала работы с драйверами Windows

Дополнительные сведения см. в разделе "Запуск InfVerif" из командной строки.

InfVerif проверяет требования к изоляции драйверов с аргументом "/w", как показано ниже:

infverif.exe /w <INF file> [<INF file>]

Если InfVerif не сообщает об ошибках при проверке с помощью /w, INF-файл соответствует требованию изоляции пакетов драйверов для драйверов Windows.

Назначение текущих и более ранних версий Windows

Если inf содержит синтаксис, представленный в последней версии Windows, например директиву INF AddEventProvider, доступную начиная с Windows 10 версии 1809, и вы также хотите нацелиться на предыдущие версии Windows, используйте декоры INF для маркировки записей INF для конкретной версии. Пример кода, показывающий, как использовать украшения версий ОС, см. в разделе "Объединение расширений платформы с версиями операционной системы".

INF-файлы, использующие украшения версий ОС, могут завершиться ошибкой InfVerif, так как требования к изоляции драйверов могут не поддерживаться в предыдущих версиях Windows. Для проверки такого INF можно указать минимальную версию Windows, в которой должны применяться проверка изоляции драйверов, с помощью аргумента "/wbuild". Например, INF-файл, использующий директиву AddEventProvider, может использовать следующее, чтобы применить только проверка изоляции драйверов к Windows 10 версии 1809 и более поздних версий:

infverif.exe /w /wbuild NTAMD64.10.0.0.17763 <INF file> [<INF file>]

Проверки изоляции драйверов проверяющего драйвера

Чтобы квалифицироваться как драйвер Windows, пакет драйвера должен соответствовать требованиям к изоляции пакетов драйверов. Начиная с Windows 11 средство проверки драйверов (DV) может отслеживать двоичные файлы ядра для операций чтения и записи реестра, которые не допускаются для изолированных пакетов драйверов.

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

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

Чтобы включить проверка изоляции драйверов для одного драйвера:

verifier /rc 33 36 /driver myDriver.sys

Чтобы проверка более одного драйвера, разделите каждое имя драйвера пробелом:

verifier /rc 33 36 /driver myDriver1.sys myDriver2.sys

Чтобы настроить DV для ошибки проверка при возникновении нарушения используйте следующий синтаксис:

verifier /onecheck /rc 33 36 /driver myDriver1.sys

Чтобы включить параметры проверки, необходимо перезагрузить. Для этого в командной строке укажите:

shutdown /r /t 0

Ниже приведены несколько примеров сообщений об ошибках:

Пример: ZwCreateKey предоставляет полный абсолютный путь:

DRIVER_ISOLATION_VIOLATION: <driver name>: Registry operations should not use absolute paths. Detected creation of unisolated registry key \Registry\Machine\SYSTEM

Пример: ZwCreateKey предоставляет путь относительно дескриптора, который не является утвержденным API:

DRIVER_ISOLATION_VIOLATION: <driver name>: Registry operations should only use key handles returned from WDF or WDM APIs. Detected creation of unisolated registry key \REGISTRY\MACHINE\SYSTEM\SomeKeyThatShouldNotExist

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

Драйверы KMDF

Если драйверы KMDF используют API WDF для доступа к реестру, например WdfRegistryCreateKey, WdfRegistryOpenKey или WdfRegistryQueryQueryValue, доступ к реестру выполняется через wdf01000.sys вместо двоичного файла драйвера KMDF напрямую. Чтобы просмотреть нарушения, вызванные двоичным файлом драйвера KMDF, включите проверка изоляции драйверов на wdf01000.sys в дополнение к двоичному файлу драйвера KMDF. Обратите внимание, что при этом вы увидите нарушения всех драйверов KMDF в системе, использующих WDF для доступа к реестру.

ApiValidator

Средство ApiValidator проверяет, являются ли api-интерфейсы, которые вызываются двоичными файлами для драйвера Windows. Средство возвращает ошибку, если двоичные файлы вызывают API, который находится за пределами набора допустимых API для драйверов Windows. Это средство входит в состав WDK для Windows 10.

ApiValidator проверяет, поддерживает ли драйвер уровень API, один из требований для драйверов Windows. Полный список требований см. в статье "Начало работы с драйверами Windows".

Запуск ApiValidator в Visual Studio

Если для целевой платформы проекта драйвера задано значение Windows Driver, Visual Studio автоматически запускает ApiValidator в качестве шага после сборки.

Чтобы просмотреть все сообщения, отображаемые ApiValidator, перейдите к разделу Tools-Options-Projects>> и Solutions-Build> и Run, а затем задайте выходные данные сборки проекта MSBuild для подробных сведений. При сборке из командной строки добавьте параметр /v:detailed или /v:diag в команду сборки, чтобы увеличить детализацию.

Для примера драйвера umdf2_fx2 ошибки проверки API выглядят следующим образом:

Warning  1   warning : API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 2   warning : API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 3   warning : API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 4   warning : API GetCurrentProcessId in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 5   warning : API GetCurrentThreadId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.  C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 6   warning : API GetSystemTimeAsFileTime in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 7   warning : API IsDebuggerPresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 8   warning : API IsProcessorFeaturePresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 9   warning : API QueryPerformanceCounter in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Error   10  error MSB3721: The command ""C:\Program Files (x86)\Windows Kits\10\bin\x64\ApiValidator.exe" -DriverPackagePath:"C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\Debug\\" -SupportedApiXmlFiles:"C:\Program Files (x86)\Windows Kits\10\build\universalDDIs\x86\UniversalDDIs.xml" -ApiExtractorExePath:"C:\Program Files (x86)\Windows Kits\10\bin\x64"" exited with code -1.    C:\Program Files (x86)\Windows Kits\10\build\WindowsDriver.common.targets   1531    5   osrusbfx2um

Устранение ошибок проверки

Если вы переключили устаревший проект драйвера UMDF на драйвер Windows, убедитесь, что вы включаете правильные библиотеки при создании двоичных файлов. Выберите и удерживайте проект (или щелкните правой кнопкой мыши) и выберите свойства. Перейдите к компоновщику-входным >данным. Дополнительные зависимости должны содержать:
```
%AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib
```
Чтобы просмотреть другие параметры компоновщика для целевых номеров SKU OneCore, см. статью "Сборка для OneCore".
Удалите или замените вызовы API, которые не разрешены один раз и повторно запустите средство до тех пор, пока нет ошибок.
В некоторых случаях эти вызовы можно заменить альтернативными DDIS, перечисленными на справочных страницах для DDI только для настольных компьютеров. Возможно, вам придется закодировать обходное решение, если не существует подходящей замены. Если вам нужно, напишите новый драйвер Windows, начиная с шаблонов драйверов в WDK.

Если вы видите ошибки, как показано ниже, обратитесь к руководству по созданию oneCore.

ApiValidation: Error: FlexLinkTest.exe has a dependency on 'wtsapi32.dll!WTSEnumerateSessionsW' but is missing: IsApiSetImplemented("ext-ms-win-session-wtsapi32-l1-1-0")
ApiValidation: Error: FlexLinkTest.exe has a dependency on 'wtsapi32.dll!WTSFreeMemory' but is missing: IsApiSetImplemented("ext-ms-win-session-wtsapi32-l1-1-0")
ApiValidation: NOT all binaries are Universal

Запуск ApiValidator из командной строки

Вы также можете запустить Apivalidator.exe из командной строки. В установке WDK перейдите в папку C:\Program Files (x86)\Windows Kits\10\bin<arch> и C:\Program Files (x86)\Windows Kits\10\build\universalDDIs<arch>.

Важные примечания.

ApiValidator требует следующих файлов: ApiValidator.exe, Aitstatic.exe, Microsoft.Kits.Drivers.ApiValidator.dll и UniversalDDIs.xml.
UniversalDDIs.xml должен соответствовать проверенной двоичной архитектуре, например для драйвера x64 с помощью UniversalDDI.xml x64
ApiValidator проверяет только одну архитектуру за раз
Дополнительные сведения см. в разделе "Известные проблемы ApiValidator" ниже

Используйте следующий синтаксис:

Apivalidator.exe -DriverPackagePath: <driver folder path> -SupportedApiXmlFiles: (path to XML files containing supported APIs for Windows drivers)

Например, чтобы проверить API, вызываемые примером действия в WDK, сначала создайте пример в Visual Studio. Затем откройте командную строку и перейдите в каталог, содержащий инструмент, например C:\Program Files (x86\Windows Kits\10\bin\x64. Введите следующую команду:

apivalidator.exe -DriverPackagePath:"C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2\_fx2\Debug" -SupportedApiXmlFiles:"c:\Program Files (x86)\Windows Kits\10\build\universalDDIs\x64\UniversalDDIs.xml"

Команда выдает следующие выходные данные:

ApiValidator.exe: Warning: API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetCurrentProcessId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetCurrentThreadId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetSystemTimeAsFileTime in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API IsDebuggerPresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API IsProcessorFeaturePresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API QueryPerformanceCounter in kernel32.dll is not supported. osrusbfx2um.dll calls this API.

ApiValidator.exe Driver located at C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\Debug is NOT a Universal Driver

Устранение неполадок ApiValidator

Если ApiValidator.exe выводит ошибку неправильного формата, например следующую:

Error      1              error : AitStatic output file has incorrect format or analysis run on incorrect file types.     C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe            osrusbfx2um

Используйте это обходное решение:

Откройте свойства Project, перейдите в раздел "Общие" и переименуйте выходной каталог следующим образом:
```
$(SolutionDir)$(Platform)\$(ConfigurationName)\
```
Заново постройте решение.

Известные проблемы ApiValidator

ApiValidator не работает в Arm64, так как AitStatic не работает на Arm64.
Двоичные файлы Arm64 можно протестировать на компьютерах x64, но не на компьютере x86.
ApiValidator может работать в x86 для тестирования двоичных файлов x86 и двоичных файлов Arm.
ApiValidator может работать на x64 для тестирования двоичных файлов x86, x64, Arm и Arm64.

Поделиться через