Verwenden der statischen Treiberüberprüfung zum Auffinden von Fehlern in Windows-Treibern

Artikel
07/03/2024

Static Driver Verifier (SDV) verwendet eine Reihe von Schnittstellenregeln und ein Modell des Betriebssystems, um zu ermitteln, ob der Treiber ordnungsgemäß mit dem Windows-Betriebssystem interagiert. SDV findet Fehler im Treibercode, die auf potenzielle Fehler in Treibern verweisen könnten.

SDV kann Kernelmodustreiber analysieren, die einem der folgenden Treibermodelle entsprechen: WDM, KMDF, NDIS oder Storport. Weitere Informationen finden Sie unter "Unterstützte Treiber" und "Ermitteln, ob die Überprüfung statischer Treiber Ihren Treiber oder Ihre Bibliothek unterstützt". Darüber hinaus bietet SDV eingeschränkte Unterstützung (eine stark eingeschränkte Regel, die sich auf allgemeine Fehler wie NULL-Ableitungen konzentriert) für Treiber, die nicht den obigen Treibermodellen folgen.

Wichtig

SDV wird nicht mehr unterstützt, und SDV ist in Windows 24H2 WDK- oder EWDK-Versionen nicht verfügbar. Sie ist in WDKs neuer als Build 26017 nicht verfügbar und nicht im Windows 24H2 RTM WDK enthalten. SDV kann weiterhin verwendet werden, indem Sie das Windows 11, Version 22H2 EWDK (veröffentlicht am 24. Oktober 2023) mit Visual Studio-Buildtools 17.1.5 aus dem Windows Driver Kit (WDK) herunterladen. Es wird nur die Verwendung von Enterprise WDK zum Ausführen von SDV empfohlen. Die Verwendung älterer Versionen des Standard-WDK in Verbindung mit den letzten Versionen von Visual Studio wird nicht empfohlen, da dies wahrscheinlich zu Analysefehlern führt.
In Zukunft wird CodeQL das primäre statische Analysetool für Treiber sein. CodeQL stellt eine leistungsstarke Abfragesprache bereit, die Code als abgefragte Datenbank behandelt, sodass Abfragen für bestimmte Verhaltensweisen, Muster und vieles mehr einfach geschrieben werden können. Weitere Informationen zur Verwendung von CodeQL finden Sie unter CodeQL und dem Logotest für statische Tools.

Vorbereiten des Quellcodes

Führen Sie die folgenden Schritte aus, um Ihren Code für die Analyse vorzubereiten.

Deklarieren der vom Treiber bereitgestellten Funktionen mithilfe von Funktionsrollentypen

SDV erfordert, dass die Funktionen mithilfe von Funktionsrollentypdeklarationen deklariert werden. Beispielsweise muss eine DriverEntry-Routine mithilfe des Rollentyps DRIVER_INITIALIZE Funktion deklariert werden:
```
DRIVER_INITIALIZE DriverEntry;
```
Nach der Deklaration implementieren (oder definieren) Sie die Rückrufroutine wie folgt:
```
/
// Driver initialization routine
//
NTSTATUS
  DriverEntry(
    _In_ struct _DRIVER_OBJECT  *DriverObject,
    _In_ PUNICODE_STRING  RegistryPath
    )
  {
      // Function body
  }
```
Jedes unterstützte Treibermodell verfügt über eine Reihe von Funktionsrollentypen für die Treiberrückruffunktionen und Verteilerroutinen. Diese Funktionsrollentypen werden in den WDK-Headerdateien deklariert. Hier ist beispielsweise der Funktionsprototyp für den rollentyp DRIVER_INITIALIZE, wie er in Wdm.h angezeigt wird.
```
/
// Define driver initialization routine type.
//
_Function_class_(DRIVER_INITIALIZE)
_IRQL_requires_same_
typedef
NTSTATUS
DRIVER_INITIALIZE (
    _In_ struct _DRIVER_OBJECT *DriverObject,
    _In_ PUNICODE_STRING RegistryPath
    );

typedef DRIVER_INITIALIZE *PDRIVER_INITIALIZE;
```
Da die Funktionsrollentypen bereits in den WDK-Headerdateien definiert sind, müssen Sie nur die Rückruffunktionen als diesen Typ deklarieren. In diesem Fall deklarieren Sie DriverEntry als Typ DRIVER_INITIALIZE. Eine vollständige Liste der Funktionsrollentypen für die Treibermodelle finden Sie unter Verwenden von Funktionsrollentypdeklarationen.

Ausführen der Codeanalyse für C/C++

Um zu ermitteln, ob der Quellcode vorbereitet ist, führen Sie das Codeanalysetool in Visual Studio aus. Das Codeanalysetool sucht nach Funktionsrollentypdeklarationen, die SDV erfordert. Das Codeanalysetool kann dabei helfen, funktionsdeklarationen zu identifizieren, die möglicherweise verpasst wurden, oder Sie warnen, wenn die Parameter der Funktionsdefinition nicht mit denen im Funktionsrollentyp übereinstimmen.

Öffnen Sie Ihr Treiberprojekt in Visual Studio.
Klicken Sie im Menü "Erstellen " auf "Codeanalyse für Projektmappe ausführen".

Die Ergebnisse werden im Codeanalysefenster angezeigt. Beheben Sie alle Funktionsdeklarationen, die Sie möglicherweise verpasst haben. Sie können auch das Codeanalysetool so konfigurieren, dass es immer dann ausgeführt wird, wenn Sie Ihre Lösung erstellen.

In der folgenden Tabelle sind einige Warnungen aufgeführt, die das Codeanalysetool möglicherweise im Treibercode finden kann. Um den Static Driver Verifier auszuführen, muss Ihr Treiber frei von diesen Fehlern sein.

Codeanalyse für C/C++-Warnung	Beschreibung
C28101	Das Treibermodul hat abgeleitet, dass die aktuelle Funktion eine <function-type>-Funktion ist
C28022	Die Funktionsklasse(n) in dieser Funktion stimmt/stimmen nicht mit der/den Funktionsklasse(n) in der Typendefinition überein, die zu deren Definition verwendet wird.
C28023	Die zuzuweisende bzw. zu übergebene Funktion sollte über eine _Function_class_-Anmerkung für mindestens eine der Klassen verfügen in
C28024	Der zuzuweisende Funktionszeiger wurde mit der Funktionsklasse versehen, die nicht in der Liste der Funktionsklassen enthalten ist.
C28169	Die Dispatch-Funktion <> weist keine _Dispatch_type_ Anmerkungen auf.
C28208	Die Funktionssignatur stimmt nicht mit den Funktionsdeklarationen überein.

Ausführen der Überprüfung statischer Treiber

Öffnen Sie die Treiberprojektdatei (VCXProj) in Visual Studio. Klicken Sie im Menü Driver auf Launch Static Driver Verifier....

Dadurch wird die Anwendung "Static Driver Verifier" geöffnet, in der Sie steuern, konfigurieren und planen können, wann statische Treiberüberprüfung eine Analyse durchführt.
Wenn Ihr Treiber eine Bibliothek enthält, klicken Sie auf die Registerkarte "Bibliotheken " und dann auf " Bibliothek hinzufügen", um die Bibliothek hinzuzufügen.

Navigieren Sie zum Verzeichnis Des Bibliotheksquellcodes, und wählen Sie die Projektdatei (VCXProj) aus. Fügen Sie alle Bibliotheken hinzu, die Ihr Treiber enthält. Die Bibliotheken müssen hinzugefügt werden, bevor SDV Ihren Treiber analysiert. Wenn Sie eine Analyse Ihres Treibers starten, analysiert SDV auch die Bibliotheken, die nicht verarbeitet wurden. Nachdem eine Bibliothek verarbeitet wurde, wird sie im globalen SDV-Cache gespeichert. Weitere Informationen finden Sie unter Library Processing in Static Driver Verifier
Überprüfen Sie die Konfigurationseinstellungen für die Überprüfung statischer Treiber. Klicken Sie auf die Registerkarte Configure .

Projektkonfiguration Die Project-Konfiguration zeigt die Konfigurations- und Plattformeinstellungen an, die Sie in Visual Studio ausgewählt haben.

Ressourcen In den meisten Fällen können Sie die Standardeinstellungen verwenden. Wenn SDV Timeout, GiveUp oder Spaceout meldet, können Sie versuchen, diese Einstellungen anzupassen. Weitere Informationen finden Sie unter Empfehlungen für die Problembehandlung bei der Überprüfung statischer Treiber.

Zeitplan Wählen Sie eine Startzeit für die Überprüfung aus, um zu beginnen. Die Standardeinstellung besteht darin, die Analyse sofort zu beginnen, nachdem Sie auf der Registerkarte "Haupt" auf "Start" geklickt haben. Je nach Größe des Treibers und seiner Komplexität kann die statische Analyse lange dauern. Vielleicht möchten Sie die Analyse planen, um zu beginnen, wenn sie für Sie am bequemsten ist; Beispielsweise am Ende des Tages.

Hinweis

Überprüfen Sie unbedingt den Energieverwaltungsplan Ihres Computers, um sicherzustellen, dass der Computer während der Analyse nicht in einen Energiesparzustand wechselt.
Klicken Sie auf die Registerkarte "Regeln ", um auszuwählen, welche Treiber-API-Verwendungsregeln beim Starten der Analyse überprüft werden sollen.

Static Driver Verifier erkennt den Typ des Treibers, den Sie analysieren (WDF, WDM, NDIS oder Storport) und wählt den Standardsatz von Regeln für den Treibertyp aus. Wenn Sie SDV zum ersten Mal auf Ihrem Treiber ausführen, sollten Sie den Standardregelsatz ausführen.

Informationen zu den Regeln finden Sie unter DDI-Complianceregeln.
Starten Sie die statische Analyse. Klicken Sie auf die Registerkarte "Haupt " und dann auf "Start". Wenn Sie auf "Start" klicken, wird eine Meldung angezeigt, um Ihnen mitzuteilen, dass die statische Analyse geplant ist und dass die Analyse lange dauern kann. Klicken Sie zum Fortsetzen des Vorgangs auf OK . Die Analyse beginnt zu dem Von Ihnen geplanten Zeitpunkt.

Anzeigen und Analysieren der Ergebnisse

Wenn die statische Analyse fortgesetzt wird, meldet SDV den Status der Analyse. Wenn die Analyse abgeschlossen ist, meldet SDV die Ergebnisse und Statistiken. Wenn der Treiber eine API-Verwendungsregel nicht erfüllt, wird das Ergebnis als Fehler gemeldet.

Wenn Probleme aufgetreten sind, zeigt SDV diese auf den Seiten "Warnungen " und "Fehler " an. Auf der Seite "Treibereigenschaften " werden die Ergebnisse der Tests für bestimmte Treibereigenschaften angezeigt. Die Treibereigenschaftentests werden verwendet, um Treiberfeatures zu identifizieren, um die Analyse weiter zu qualifizieren. Sie können die Ergebnisse der Treibereigenschaften verwenden, um die erwarteten Eigenschaften und unterstützten Funktionen Ihres Treibers zu bestätigen.

Um bestimmte Fehler im Bericht "Statische Treiberüberprüfung" anzuzeigen, klicken Sie im Ergebnisbereich auf den Fehler. Dadurch wird der Ablaufverfolgungs-Viewer geöffnet, der eine Ablaufverfolgung des Codepfads zur Regelverletzung anzeigt. Weitere Informationen finden Sie unter Interpreting Static Driver Verifier Results.

Hinweis

Statische Treiberüberprüfung behält die Ergebnisse und Einstellungen aus der Analyse bei. Klicken Sie auf "Bereinigen", um die Ergebnisse zu löschen.

Problembehandlung für statische Treiberüberprüfungsergebnisse

Wenn SDV meldet, dass keine Fehler gefunden wurden, überprüfen Sie die Registerkarte "Haupt ", um sicherzustellen, dass Einstiegspunkte erkannt werden. Wenn der Treiber Funktionen nicht mithilfe der Funktionsrollentypen deklariert, kann SDV fehler im Treibercode nicht analysieren und finden. Weitere Informationen finden Sie unter Verwenden von Funktionsrollentypdeklarationen.

Wenn SDV Timeouts meldet oder nützliche Ergebnisse nicht zurückgibt, müssen Sie möglicherweise einige SDV-Konfigurationsoptionen ändern. Weitere Informationen zur Problembehandlung bei SDV finden Sie unter Empfehlungen für die Problembehandlung bei der Überprüfung statischer Treiber.

Ermitteln, ob die Überprüfung des statischen Treibers Ihren Treiber oder Ihre Bibliothek unterstützt

Verwenden von Funktionsrollentypdeklarationen

Regeln für die Überprüfung statischer Treiber

Codeanalysetool