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

Статья
08/14/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 для остановки системы и создания дампа памяти с подробными сведениями при возникновении нарушения. Вы можете начать разработку драйверов с первого и второго методов, а затем перейти на второй, когда драйвер приближается к завершению.

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

verifier /rc 33 36 /driver myDriver.sys [myDriver2.sys ...]

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

verifier /onecheck /rc 33 36 /driver myDriver1.sys [myDriver2.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 для устранения нарушений изоляции драйверов на ранних этапах.

Примечание.

DV не хочет наводнения пользователей с потоплением сообщений о том же нарушении, поэтому он имеет механизм регулирования, где он может регулировать отчеты о каждой уникальной ошибке. Начиная с Windows 11 24H2, чтобы убедиться, что вы видите полный набор нарушений изоляции драйверов для любого запуска теста или ряда тестов, вы можете запросить регулирование нарушений изоляции драйверов, которые необходимо сбросить с помощью:

средство проверки /dif 33 /action 1

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

Соответствие WHCP

В настоящее время программа совместимости оборудования Windows (WHCP) не требует полной изоляции пакета драйверов. Однако начиная с Windows 11 24H2 программа WHCP начинает включать требования к изоляции драйверов. Чтобы включить тот же уровень проверки изоляции пакета драйверов, что и набор аппаратных лабораторий (HLK) в рамках применения требований WHCP, используйте следующий синтаксис:

Verifier /dif 33 /33 whcp /driver myDriver.sys [myDriver2.sys ...]

При использовании этого синтаксиса все нарушения изоляции драйверов по-прежнему будут сообщаться, но те, которые в настоящее время не применяются для HLK, будут сообщаться как предупреждения вместо ошибок. Те, которые перечислены как предупреждения, не вызывают сбои HLK и не вызывают проверку ошибок системы, если включить проверки изоляции драйверов с помощью /onecheck, чтобы создать ошибку при возникновении нарушения.

При просмотре событий с отладчиком ядра те, которые считаются ошибками, будут префиксированы, DRIVER_ISOLATION_VIOLATION в то время как те, которые являются предупреждениями, будут префиксированы с DRIVER_ISOLATION_WARNINGпрефиксом.

При просмотре событий в журнале событий системы события с атрибутом ErrorLevel 0 считаются ошибками и событиями с другим ErrorLevel значением, не считаются ошибками. Дополнительные сведения см. в разделе "Просмотр нарушений в журнале событий системы".

Просмотр нарушений в журнале событий системы

Нарушения проверяющего драйвера сообщаются в журнале событий системы от поставщика Microsoft-Windows-Kernel-XDV и с идентификатором события "4". В Windows 11 24H2 и более поздних версиях события будут содержать ErrorLevel значение. События со ErrorLevel значением 0 считаются ошибками в соответствии с активным режимом изоляции драйвера (полное соответствие требованиям к изоляции драйвера и соответствием изоляции WHCP) при создании нарушения. События с другими ErrorLevel значениями не считаются ошибками. Например, событие с этими атрибутами будет считаться ошибкой:

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should not use absolute paths. Detected opening of unisolated registry key \Registry\Machine\System\CurrentControlSet\Services\ExampleDriver\Parameters
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0x0

Хотя событие с этими атрибутами не считается ошибкой:

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should only use key handles returned from WDF or WDM APIs. Detected querying of value under unisolated registry key \REGISTRY\MACHINE\SYSTEM\ControlSet001\Control
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0xf4240

Если вы используете приложение Просмотр событий для просмотра журнала событий системы, вы можете отфильтровать представление журнала с помощью меню справа от приложения, щелкнув "Фильтр текущего журнала". Во всплывающем диалоговом окне, если перейти на вкладку XML и изменить запрос вручную, этот запрос можно использовать для фильтрации журнала событий системы только для нарушений DV, которые должны рассматриваться как ошибка:

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

Если вы хотите отфильтровать представление журнала событий до всех нарушений DV, которые должны считаться ошибкой после определенного времени (например, после начала тестового прохождения), можно сделать следующее:

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime&gt;='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

Или если вы предпочитаете XML-файл, который можно загрузить для просмотра, можно использовать wevtutil для создания такого XML-файла на основе одних и того же запроса:

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime>='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

Драйверы 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.

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