Überprüfen von Windows-Treibern

  • Artikel

Verwenden Sie die Tools InfVerif, Driver Verifier Driver Isolation Checks und ApiValidator, um Ihr Treiberpaket auf die Einhaltung der Windows-Treiberanforderungen zu testen, die unter Erste Schritte mit 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:

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-Anweisung, 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-Anweisung 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 Registrierungslese- und Schreibvorgänge überwachen, die für isolierte Treiberpakete nicht zulässig sind.

Sie können Verstöße entweder so anzeigen, wie sie in einem Kerneldebugger auftreten, oder Sie können DV so konfigurieren, dass das System angehalten wird und ein Speicherabbild mit Details generiert wird, wenn ein Verstoß auftritt. Sie können die Treiberentwicklung mit der ersten Methode beginnen und dann zur zweiten Methode wechseln, wenn sich Ihr Treiber der Fertigstellung nähert.

Um Verstöße anzuzeigen, sobald sie auftreten, schließen Sie zunächst einen Kernel-Debugger an und verwenden Sie dann die folgenden Befehle. Nachdem die DV-Einstellungen durch einen Neustart aktiviert wurden, können Sie Verstöße in der Ausgabe des Kernel-Debuggers überwachen.

So aktivieren Sie Treiberisolationsprüfungen für einen einzelnen Treiber:

verifier /rc 33 36 /driver myDriver.sys

Um mehrere Treiber zu überprüfen, trennen Sie jeden Treibernamen durch ein Leerzeichen:

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

Verwenden Sie die folgende Syntax, um DV so zu konfigurieren, dass eine Fehlerüberprüfung auftritt:

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

Sie müssen neu starten, um die Überprüfungseinstellungen zu aktivieren. Um dies von der Befehlszeile aus zu tun, geben Sie Folgendes an:

shutdown /r /t 0

Hier sind einige Beispiele für Fehlermeldungen:

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.

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 Erste Schritte mit 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

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

  2. Entfernen oder ersetzen Sie unzulässige API-Aufrufe nacheinander und führen Sie das Tool erneut aus, bis es keine Fehler mehr gibt.

  3. 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:

  1. Öffnen Sie die Projekteigenschaften, wechseln Sie zu Allgemein, und benennen Sie das Ausgabeverzeichnis in Folgendes um:

    $(SolutionDir)$(Platform)\$(ConfigurationName)\

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