Windows の複数バージョン用 WDF ドライバーのビルド

  • [アーティクル]

WDF では常にドライバーを 1 回ビルドし、結果のバイナリを複数のバージョンの Windows で使用できましたが、Windows 10 バージョン 1803 (Redstone 4) より前のバージョンでは、これは「古いバージョンでビルド、新しいバージョンで実行」に制限されていました。Windows 10 バージョン 1803 以降では、WDF によって「新しいバージョンでビルド、古いバージョンで実行」が追加され、条件付き実行の利点が追加されました。 まとめ

  • 既存: 古いバージョンのフレームワークでビルドされたバイナリは、メジャー バージョンが一致する場合、新しいバージョンのフレームワークを含む Windows のバージョンで実行されます。 たとえば、KMDF 1.9 (Windows 7) でビルドされたドライバーは、Windows 8 システム (KMDF 1.11) で実行されます。 この例では、ドライバーは KMDF 1.9 の機能に制限されています。
  • 追加: Windows 10 バージョン 1803 の KMDF バージョン 1.25 および UMDF バージョン 2.25 以降では、新しいフレームワーク バージョンでドライバーをビルドでき、結果として得られるドライバー バイナリは以前のバージョンの Windows (少なくとも Windows 10 バージョン 1803) で実行されます。 さらに、ドライバーは、新しいフレームワーク バージョンでのみ使用できる機能を条件付きで使用できます。

つまり、ドライバーはこれまでどおり将来のバージョンの Windows で実行されるだけでなく、Windows 10 バージョン 1803 まで遡って過去のバージョンでも実行されます。

これを行うには、Visual Studio でのビルド設定の指定と、API を呼び出すか、または存在するかどうか分からない構造体またはフィールドにアクセスする前にランタイム チェックを実行する、という 2 つの手順があります。

注: この機能はオプションであり、ドライバーは、最新の WDF 機能を持たない以前のバージョンの Windows で読み込み可能な状態を保ちながら、最新の WDF 機能を使用するドライバーをビルドするためのみに有効にする必要があります。

バージョン マイナー (ターゲット バージョン) またはバージョン マイナー (最小必須) を設定しない場合、バージョン管理は以前と同じです。

最小必須の指定

Visual Studio Code での新しい構成設定は次のとおりです。

  • KMDF バージョン マイナー (最小必須)
  • UMDF バージョン マイナー (最小必須)

この変更に従って、2 つの既存の設定の名前が更新されました。

  • KMDF バージョン マイナー ->KMDF バージョン マイナー (ターゲット バージョン)
  • UMDF バージョン マイナー ->UMDF バージョン マイナー (ターゲット バージョン)

最小必須を設定しない場合、Visual Studio はターゲット バージョン以降用にビルドされ、ダウンレベルのサポートは提供されません。 これは、古いバージョン マイナープロパティの動作と一致します。

最小必須を設定した場合は、次の要件が適用されます。

  • 25 <= 最小必須 <= ターゲット バージョン
  • Configuration Properties->Driver Settings->General で、_NT_TARGET_VERSION を 0x0A000005 (RS4) 以降に設定します。

機能が存在するかどうかを確認する

存在するかどうかわからない API、構造体、またはメンバーを使用する前に、WdfFuncEnum.h で定義されている次のいずれかのマクロを呼び出す必要があります。

BOOLEAN
WDF_IS_FUNCTION_AVAILABLE (
    FunctionName
    );

BOOLEAN
WDF_IS_STRUCTURE_AVAILABLE (
    StructName
    );

BOOLEAN
WDF_IS_FIELD_AVAILABLE (
    StructName,
    FieldName
    );

以下の例を考慮してください。 WDF v29 がリリースされると、新しい API WdfSomeNewFeatureが追加されます。 ターゲット バージョン を29 に設定し、最小必須を 25 に設定すると、結果として得られるドライバーは、25 から 29 (およびメジャー バージョンが変更されない限りそれ以降) までのフレームワーク バージョンに読み込まれ、以前と同様にバージョン 25 API を呼び出し、v29 API を呼び出すたびに次のチェックを行います。

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

条件付きチェックを行わない場合は、次のようになることがあります。

  • API から NTSTATUS が返された場合、呼び出しはエラー コードを返します。
  • API が NTSTATUS 以外のものを返す場合:
    • KMDF: マシンのバグ チェック。
    • UMDF: WudfHost プロセスが DriverStop エラーでクラッシュします。
  • ドライバー検証ツールが有効になっている場合は、ドライバーもクラッシュします。 これは、テスト環境の問題を特定するのに役立ちます。
  • サイレント メモリ破損 (構造体またはフィールドにアクセスする場合)。

ドライバーのクラッシュには、失敗したドライバー名、フレームワーク名、および失敗した API インデックスが含まれます。 WdfFuncEnum.h で WDFFUNCENUM の値を調べることで、API の名前を取得できます。

WDF の Visual Studio プロパティの詳細については、「ドライバー プロジェクトのドライバー モデル設定プロパティ」を参照してください。