Überprüfen von Windows-Treibern

Artikel
08/18/2024

Verwenden Sie die Tools InfVerif, Driver Verifier Driver Isolation Checks und ApiValidator, um Ihr Treiberpaket auf Compliance mit den Anforderungen für Windows-Treiber zu testen, die in Beginnen Sie mit der Entwicklung von Windows-Treibern beschrieben sind.

InfVerif

Das Tool InfVerif überprüft die INF-Syntax und ob die INF den Anforderungen und Einschränkungen entspricht.

Verwenden Sie InfVerif mit /w, um einen Windows-Treiber auf Folgendes zu überprüfen:

Der Treiber erfüllt das deklarative (D) Prinzip der DCH-Designprinzipien.
Erfüllt die Anforderung Isolierung von Treiberpaketen aus Starten Sie mit der Entwicklung von Windows-Treibern

Weitere Informationen finden Sie unter Ausführen von InfVerif über die Befehlszeile.

InfVerif überprüft die Treiberisolationsanforderungen mit dem Argument '/w', wie hier gezeigt:

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

Wenn InfVerif beim Überprüfen mit /w keine Fehler meldet, erfüllt die INF die Anforderung zur Treiberpaketisolation von Windows-Treibern.

Ausrichtung auf aktuelle und frühere Versionen von Windows

Wenn Ihr INF eine Syntax aufweist, die in einer aktuellen Version von Windows eingeführt wurde, z. B. die INF-AddEventProvider-Direktive, die ab Windows 10, Version 1809 verfügbar ist und Sie auch auf frühere Windows-Versionen abzielen möchten, verwenden Sie INF-Ergänzungen, um versionsspezifische INF-Einträge zu kennzeichnen. Beispielcode zur Verwendung von Betriebssystemversions-Ergänzungen finden Sie unter Kombinieren von Plattformerweiterungen mit Betriebssystemversionen.

Bei INF-Dateien, die Betriebssystemversions-Ergänzungen verwenden, kann InfVerif fehlschlagen, da die Treiberisolationsanforderungen in den vorherigen Windows-Versionen möglicherweise nicht unterstützt werden. Um eine solche INF zu überprüfen, können Sie die erforderliche Windows-Mindestversion angeben, in der Treiberisolationsprüfungen angewendet werden sollten, indem Sie das Argument '/wbuild' verwenden. Beispiel: Eine INF-Datei, die die AddEventProvider-Direktive verwendet, kann Folgendes verwenden, um nur Treiberisolationsprüfungen auf Windows 10, Version 1809 und höher anzuwenden:

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

Überprüfung der Treiberisolation des Treiberüberprüfungstreibers

Für eine Qualifizierung als Windows-Treiber muss ein Treiberpaket die Anforderungen für die Treiberpaketisolation erfüllen. Ab Windows 11 kann Driver Verifier (DV) Kernel-Binärdateien für Schreibvorgänge der Registrierung und des Dateisystems überwachen, die für isolierte Treiberpakete nicht zulässig sind.

Sie können Verstöße entweder in Echtzeit in einem Kerneldebugger anzeigen, Sie können die gemeldeten Verstöße im Systemereignisprotokoll überprüfen oder Sie können DV so konfigurieren, dass bei einem Verstoß das System angehalten und ein Speicherabbild mit Details generiert wird. Sie können die Treiberentwicklung mit der ersten Methode beginnen und zur zweiten Methode wechseln, wenn sich Ihr Treiber der Fertigstellung nähert.

So aktivieren Sie Treiberisolationsprüfungen so, dass sie über den Kerneldebugger und das Systemereignisprotokoll gemeldet werden, ohne dass das System auf Fehler überprüft wird:

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

Verwenden Sie die folgende Syntax, um DV so zu konfigurieren, dass bei einem Treiberisolationsverstoß eine Fehlerprüfung erfolgt:

verifier /onecheck /rc 33 36 /driver myDriver1.sys [myDriver2.sys ...]

Unabhängig davon, welche Überwachungsmethode Sie auswählen, müssen Sie den Computer zum Aktivieren der Überprüfungseinstellungen neu starten. Um dies von der Befehlszeile aus zu tun, geben Sie Folgendes an:

shutdown /r /t 0

Die folgenden Beispiele sind Fehlermeldungen, die vom Kerneldebugger angezeigt werden:

Beispiel: ZwCreateKey stellt einen vollständigen absoluten Pfad bereit:

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

Beispiel: ZwCreateKey stellt einen Pfad relativ zu einem Handle bereit, das nicht von einer genehmigten API stammt:

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

Erwägen Sie, Grundlagentests für Geräte mit für Ihren Treiber aktivierten DV-Treiberisolationsprüfungen auszuführen, um Treiberisolationsverstöße frühzeitig abzufangen.

Hinweis

DV soll Benutzer und Benutzerinnen nicht mit Berichten zum selben Verstoß überfluten. Daher gibt es einen Drosselungsmechanismus, mit dem die Berichterstattung zu jedem eindeutigen Fehler gedrosselt werden kann. Um sicherzustellen, dass alle Treiberisolationsverstöße für eine bestimmte Testausführung oder einer Reihe von Tests angezeigt werden, ist es ab Windows 11 24H2 möglich, eine Anforderung zum Zurücksetzen der Drosselung von Treiberisolationsverstößen zu senden:

verifier /dif 33 /action 1

Wenn Sie dies nicht tun, bevor Sie einen Test ausführen, werden beim Ausführen der Tests bestimmte Verstöße möglicherweise nicht angezeigt, wenn diese Verstöße bereits vor dem Starten des Tests aufgetreten sind.

WHCP-Einhaltung

Das Windows-Hardware-Kompatibilitätsprogramm (WHCP) schreibt derzeit keine vollständige Treiberpaketisolation vor. Ab Windows 11 24H2 enthält das WHCP-Programm jedoch erstmals Anforderungen zur Treiberisolation. Um die gleiche Prüfungsstufe für die Treiberpaketisolation zu erhalten wie das Hardware Lab Kit (HLK) beim Erzwingen der WHCP-Anforderungen, verwenden Sie die folgende Syntax:

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

Mit dieser Syntax werden weiterhin alle Treiberisolationsverstöße gemeldet, aber diejenigen, die derzeit nicht für das HLK erzwungen werden, werden als Warnungen anstelle von Fehlern gemeldet. Verstöße, die als Warnungen aufgeführt sind, verursachen keine HLK-Fehler. Sie führen auch nicht dazu, dass das System eine Fehlerprüfung vornimmt, wenn Sie die Treiberisolationsprüfungen mit /onecheck aktivieren, um bei Verstößen eine Fehlerprüfung zu generieren.

Beim Anzeigen von Ereignissen mit einem Kerneldebugger erhalten Ereignisse, die als Fehler betrachtet werden, das Präfix DRIVER_ISOLATION_VIOLATION. Ereignisse, die als Warnungen gelten, erhalten das Präfix DRIVER_ISOLATION_WARNING.

Beim Anzeigen von Ereignissen im Systemereignisprotokoll werden die Ereignisse mit einem ErrorLevel-Attribut von 0 als Fehler betrachtet, während Ereignisse mit einem anderen ErrorLevel-Wert nicht als Fehler gelten. Weitere Informationen finden Sie im Abschnitt „Anzeigen von Verstößen im Systemereignisprotokoll“.

Anzeigen von Verstößen im Systemereignisprotokoll

Treiberüberprüfungsverstöße werden im Systemereignisprotokoll des Anbieters Microsoft-Windows-Kernel-XDV und mit einer Ereignis-ID '4' gemeldet. Unter Windows 11 24H2 und höher enthalten die Ereignisse einen ErrorLevel-Wert. Ereignisse mit einem ErrorLevel Wert von 0 werden gemäß dem Treiberisolationsmodus (vollständige Treiberisolationscompliance oder WHCP-Isolationscompliance) als Fehler betrachtet, der beim Generieren des Verstoßes aktiv war. Ereignisse mit anderen ErrorLevel-Werten werden nicht als Fehler angesehen. Ein Ereignis mit diesen Attributen wird beispielsweise als Fehler betrachtet:

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

Ein Ereignis mit diesen Attributen gilt hingegen nicht als Fehler:

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

Wenn Sie sich das Systemereignisprotokoll mit der Anwendung Ereignisanzeige ansehen, können Sie die Ansicht des Protokolls mithilfe des Menüs auf der rechten Seite der Anwendung filtern, indem Sie auf „Aktuelles Protokoll filtern“ klicken. Wenn Sie im eingeblendeten Dialogfeld zur Registerkarte „XML“ wechseln und die Abfrage manuell bearbeiten, können Sie anhand dieser Abfrage das Systemereignisprotokoll so filtern, dass es nur DV-Verstöße enthält, die als Fehler zu betrachten sind:

<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>

Wenn Sie die Ansicht des Ereignisprotokolls nach allen DV-Verstößen filtern möchten, die nach einem bestimmten Zeitpunkt als Fehler betrachtet werden sollen (z. B. nach dem Start des Testdurchlaufs), gehen Sie so vor:

<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>

Oder wenn Sie eine XML-Datei bevorzugen, die Sie zum Anzeigen laden können, können Sie diese Datei basierend auf denselben Abfragen mit wevtutil generieren:

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-Treiber

Wenn KMDF-Treiber WDF-APIs für den Zugriff auf die Registrierung verwenden, wie beispielsweise WdfRegistryCreateKey, WdfRegistryOpenKey oder WdfRegistryQueryValue, erfolgt der Registrierungszugriff über wdf01000.sys anstelle der KMDF-Treiber-Binärdatei direkt. Um Verstöße anzuzeigen, die durch die Binärdatei ihres KMDF-Treibers verursacht werden, aktivieren Sie zusätzlich zur KMDF-Treiber-Binärdatei auch die Treiberisolationsprüfungen auf wdf01000.sys. Beachten Sie, dass in diesem Fall Verstöße gegen alle KMDF-Treiber im System angezeigt werden, die WDF für den Registrierungszugriff verwenden.

ApiValidator

Das ApiValidator-Tool überprüft, ob die APIs, die von Binärdateien aufgerufen werden, für einen Windows-Treiber gültig sind. Das Tool gibt einen Fehler zurück, wenn Ihre Binärdateien eine API aufrufen, die sich außerhalb der Gruppe gültiger APIs für Windows-Treiber befindet. Dieses Tool ist Teil des WDK für Windows 10.

ApiValidator überprüft, ob ein Treiber API-Layering unterstützt, eine der Anforderungen für Windows-Treiber. Eine vollständige Liste der Anforderungen finden Sie unter Beginnen Sie mit der Entwicklung von Windows-Treibern.

Ausführen von ApiValidator in Visual Studio

Wenn die Zielplattform-Eigenschaft Ihres Treiberprojekts auf Windows-Treiber festgelegt ist, führt Visual Studio ApiValidator automatisch als Postbuildschritt aus.

Um alle von ApiValidator angezeigten Meldungen anzuzeigen, wechseln Sie zu Tools->Optionen->Projekte und Lösungen->Erstellen und ausführen, und setzen Sie Ausführlichkeit der MSBuild-Projektbuildausgabe auf Detailliert. Fügen Sie beim Erstellen über die Befehlszeile den Befehl /v:detailed oder /v:diag Ihrem Buildbefehl hinzu, um den Ausführlichkeitsgrad zu erhöhen.

Für das umdf2_fx2-Treiberbeispiel sehen API-Überprüfungsfehler wie folgt aus:

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

Beheben der Überprüfungsfehler

Wenn Sie ein älteres UMDF-Treiberprojekt auf Windows-Treiber umgestellt haben, stellen Sie sicher, dass Sie beim Erstellen der Binärdateien die richtigen Bibliotheken einschließen. Wählen Sie das Projekt aus, und halten Sie es gedrückt (oder klicken Sie mit der rechten Maustaste darauf), und klicken Sie auf „Eigenschaften“. Navigieren Sie zu Linker->Input. Die zusätzlichen Abhängigkeiten sollten Folgendes enthalten:
```
%AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib
```
Informationen zum Überprüfen anderer Linkeroptionen für die Ausrichtung von OneCore-SKUs finden Sie unter Erstellung für OneCore.
Entfernen oder ersetzen Sie unzulässige API-Aufrufe nacheinander und führen Sie das Tool erneut aus, bis es keine Fehler mehr gibt.
In einigen Fällen können Sie diese Aufrufe durch alternative DDIs ersetzen, die auf den Referenzseiten für den DDI (nur Desktop) aufgeführt sind. Möglicherweise müssen Sie eine Problemumgehung codieren, wenn kein geeigneter Ersatz vorhanden ist. Falls erforderlich, schreiben Sie einen neuen Windows-Treiber, beginnend mit den Treibervorlagen im WDK.

Wenn Fehler wie der folgende angezeigt werden, lesen Sie die Anleitung in Erstellen für 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

Ausführen von ApiValidator über die Eingabeaufforderung

Sie können auch Apivalidator.exe über die Eingabeaufforderung ausführen. Navigieren Sie in Ihrer WDK-Installation zu C:\Program Files (x86)\Windows Kits\10\bin<arch> und C:\Program Files (x86)\Windows Kits\10\build\universalDDIs<arch>.

Wichtige Hinweise:

ApiValidator erfordert die folgenden Dateien: ApiValidator.exe, Aitstatic.exe, Microsoft.Kits.Drivers.ApiValidator.dll und UniversalDDIs.xml.
Die UniversalDDIs.xml muss der zu überprüfenden binären Architektur entsprechen, z. B. für einen x64-Treiber muss es die x64-UniversalDDI.xml sein
ApiValidator testet jeweils nur eine Architektur.
Weitere Informationen finden Sie weiter unten im Abschnitt „Bekannte ApiValidator-Probleme“.

Verwenden Sie die folgende Syntax:

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

Um beispielsweise die APIs zu überprüfen, die vom Beispiel „Aktivität“ im WDK aufgerufen werden, erstellen Sie zuerst das Beispiel in Visual Studio. Öffnen Sie dann eine Eingabeaufforderung, und navigieren Sie zu dem Verzeichnis, das das Tool enthält, z. B C:\Program Files (x86\Windows Kits\10\bin\x64. Geben Sie den folgenden Befehl ein:

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"

Der Befehl erstellt die folgende Ausgabe:

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

Problembehandlung bei ApiValidator

Wenn ApiValidator.exe einen falschen Formatfehler ausgibt, beispielsweise:

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

Verwenden Sie diese Problemumgehung:

Öffnen Sie die Projekteigenschaften, wechseln Sie zu Allgemein, und benennen Sie das Ausgabeverzeichnis in Folgendes um:
```
$(SolutionDir)$(Platform)\$(ConfigurationName)\
```
Erstellen Sie die Lösung neu.

Bekannte ApiValidator-Probleme

ApiValidator wird nicht auf Arm64 ausgeführt, da AitStatic nicht auf Arm64 funktioniert.
Arm64-Binärdateien können auf x64-Computern, aber nicht auf x86-Computern getestet werden.
ApiValidator kann auf x86 ausgeführt werden, um x86-Binärdateien und Arm-Binärdateien zu testen.
ApiValidator kann auf x64 ausgeführt werden, um x86-, x64-, Arm- und Arm64-Binärdateien zu testen.

Freigeben über