Erstellen eines WDF-Treibers für mehrere Versionen von Windows

  • Artikel

WDF ermöglichte es Ihnen immer, einen Treiber einmal zu erstellen und die resultierende Binärdatei unter mehreren Versionen von Windows zu verwenden, aber vor Windows 10 Version 1803 (Redstone 4) war dies auf "Auf älterem erstellen, auf neueren ausführen" beschränkt. Ab Windows 10 Version 1803 fügt WDF "build on newer, run on older" hinzu, mit dem zusätzlichen Vorteil der bedingten Ausführung. Zusammenfassung:

  • Vorhanden: Mit älteren Versionen des Frameworks erstellte Binärdateien werden unter Windows-Versionen ausgeführt, die neuere Versionen des Frameworks enthalten, sofern die Hauptversionen übereinstimmen. Beispielsweise wird ein treiber, der mit KMDF 1.9 (Windows 7) erstellt wurde, auf einem Windows 8-System (KMDF 1.11) ausgeführt. Im Beispiel ist der Treiber auf die Funktionalität von KMDF 1.9 beschränkt.
  • Hinzugefügt: Ab KMDF-Version 1.25 und UMDF-Version 2.25 unter Windows 10 Version 1803 können Sie einen Treiber mit einer neueren Frameworkversion erstellen, und die resultierende Treiberbinärdatei wird unter früheren Versionen von Windows ausgeführt (mindestens Windows 10 Version 1803). Darüber hinaus kann der Treiber funktionen, die nur in neueren Frameworkversionen verfügbar sind, bedingt verwenden.

Dies bedeutet, dass Ihr Treiber nicht nur auf zukünftigen Versionen von Windows ausgeführt wird, wie es immer der Fall ist, sondern auch auf früheren Versionen zurück zu Windows 10 Version 1803.

Hierfür gibt es zwei Schritte: Das Angeben von Buildeinstellungen in Visual Studio und das Ausführen einer Laufzeitüberprüfung, bevor Sie eine API aufrufen oder auf eine Struktur oder ein Feld zugreifen, die möglicherweise vorhanden ist oder nicht.

Hinweis: Dieses Feature ist optional, und ein Treiber sollte es nur zum Erstellen eines Treibers ermöglichen, der die neueste WDF-Funktionalität verwendet, während er in früheren Versionen von Windows, die nicht über die neueste WDF-Funktionalität verfügen, geladen werden kann.

Wenn Sie version minor (Zielversion) oder Version Minor (Minimum Required) nicht festlegen, bleibt die Versionsverwaltung identisch mit der zuvor.

Angeben des erforderlichen Minimums

Die neuen Konfigurationseinstellungen in Visual Studio sind:

  • KMDF-Version Nebenversion (Minimum erforderlich)
  • UMDF-Nebenversion (Minimum erforderlich)

Entsprechend dieser Änderung wurden die Namen von zwei vorhandenen Einstellungen aktualisiert:

  • KMDF-Version Nebenversion ->KMDF-Version Nebenversion (Zielversion)
  • UMDF-Nebenversion ->UMDF-Nebenversion (Zielversion)

Wenn Sie Minimum Required nicht festlegen, erstellt Visual Studio für Zielversion und höher und bietet keine Unterstützung für downlevel. Dies entspricht dem Verhalten der alten Versions minor-Eigenschaften .

Wenn Sie Minimum Erforderlich festlegen, gelten die folgenden Anforderungen:

  • 25 <= Minimum erforderlich <= Zielversion
  • Legen Sie unter Konfigurationseigenschaften-Treibereinstellungen-Allgemein>> auf 0x0A000005 (RS4) oder höher fest_NT_TARGET_VERSION.

Überprüfen, ob Funktionen vorhanden sind

Vor jeder Verwendung einer API, Struktur oder eines Elements, die vorhanden sein kann oder nicht, müssen Sie eines der folgenden Makros aufrufen, die in WdfFuncEnum.h definiert sind:

BOOLEAN
WDF_IS_FUNCTION_AVAILABLE (
    FunctionName
    );

BOOLEAN
WDF_IS_STRUCTURE_AVAILABLE (
    StructName
    );

BOOLEAN
WDF_IS_FIELD_AVAILABLE (
    StructName,
    FieldName
    );

Betrachten Sie das folgende Beispiel. Wenn WDF v29 veröffentlicht wird, wird eine neue API hinzugefügt: WdfSomeNewFeature. Wenn Sie Zielversion auf 29 und Minimum Erforderlich auf 25 festlegen, lädt der resultierende Treiber für eine beliebige Frameworkversion von 25 bis 29 (und höher, sofern sich die Hauptversion nicht ändert), ruft wie zuvor Version 25-APIs auf und überprüft vor jedem Aufruf einer v29-API die folgende Überprüfung:

if (WDF_IS_FUNCTION_AVAILABLE(WdfSomeNewFeature)) {
    WdfSomeNewFeature();
}

Wenn Sie die bedingte Überprüfung nicht durchführen, wird möglicherweise Folgendes angezeigt:

  • Wenn die API NTSTATUS zurückgibt, gibt der Aufruf einen Fehlercode zurück.
  • Wenn die API etwas anderes als NTSTATUS zurückgibt:
    • KMDF: Die Computerfehlerüberprüfungen.
    • UMDF: Der WudfHost-Prozess stürzt mit einem DriverStop-Fehler ab.
  • Wenn driver verifier aktiviert ist, stürzt auch der Treiber ab. Dies hilft, das Problem in einer Testumgebung zu identifizieren.
  • Automatische Speicherbeschädigung (beim Zugriff auf eine Struktur oder ein Feld).

Ein Treiberabsturz enthält den Namen des fehlerhaften Treibers, den Frameworknamen und den fehlerhaften API-Index. Sie können den Namen der API abrufen, indem Sie den Wert von WDFFUNCENUM in WdfFuncEnum.h suchen.

Weitere Informationen zu Visual Studio-Eigenschaften für WDF finden Sie unter Treibermodelleinstellungen Eigenschaften für Treiberprojekte.