PnP テスト (デバイス基礎)

デバイス基礎 PnP テストでは、ドライバーにほぼすべての PnP IRP の処理を強制しますが、削除、再調整、突然の削除という 3 つの領域が特に重視されます。 PnP テストには、これらをそれぞれ個別にテストしたり、すべてをまとめてテストしたりするメカニズム (つまり、ストレス テスト) が用意されています。 この PnP テストは、(テスト アプリケーションを介した) ユーザー モード API 呼び出しと (上位フィルター ドライバーを介した) カーネル モード API 呼び出しの組み合わせを使用して実行されます。

PNP テスト

プラグ アンド プレイ (PnP) テストでは、ドライバーおよびユーザー モード コンポーネントでさまざまな PnP 関連のコード パスを実行します。 PnP テストは、テスト コンピューターでドライバー検証ツールを有効にして実行する必要があります。 ドライバー検証ツールを有効にする方法については、「ドライバー プロジェクトのドライバー検証ツールのプロパティ」を参照してください。

デバイス削除テストについて

• PNP デバイス削除テスト
• PNP デバイス削除キャンセル テスト

デバイス削除テストには、IRP_MN_QUERY_REMOVE_DEVICE、IRP_MN_CANCEL_REMOVE_DEVICE、およびIRP_MN_REMOVE_DEVICE が含まれます。

テストでは、ターゲット デバイス スタックに上位フィルター ドライバーをインストールする処理を試みます。 この試行により、query-remove IRP が生成されます。

この query-remove IRP が失敗した場合、テストによってコンピューターが再起動され、フィルター ドライバーがデバイス スタックに取得されます。 削除要求が拒否されない場合、デバイス スタックは削除され、デバイス スタックのフィルター ドライバーを使用して再起動されます。

テストでは、セットアップ API を使用して、query-remove IRP をデバイス スタックに送信します。 フィルター ドライバーがこの削除要求に失敗するため、cancel-remove IRP が送信されます。 フィルター ドライバーは、cancel-remove が正常に終了したと断定します。

次に、テスト アプリケーションは、適切なクラス インストーラーと登録されているすべての共同インストーラーを呼び出して、デバイスを無効または有効にし、さらに削除または再列挙します (これにより、クラスおよび共同インストーラーによる DIF_PROPERTYCHANGE と DICS_DISABLE、DICS_ENABLE、および DICS_PROPCHANGE の処理がテストされます)。 IRP_MN_REMOVE_DEVICE を受信すると、フィルター ドライバーは、下位のドライバーが正常に完了したと断定します。

これらの各ステップには、暫定的な削除要求が含まれます。 要求が拒否された場合、デバイスは削除されません。 USB カメラでビデオをストリーミングしているときや、ターゲット デバイスがブート パスまたはページング パスにある場合など、必要に応じて削除要求を拒否することを選択できます。 すべての削除要求を単純に失敗させることは、一般的には適切な方法ではないことに注意してください。 すべての削除要求が失敗しても、そのドライバーが remove を受信しないことは保証されません。なぜなら、突然の削除の後に remove IRP が発行されるか、またはデバイス スタックでユーザーが start IRP に失敗する場合があるためです。

突然削除テストについて

• PNP デバイス突然削除テスト

抜き打ち削除テストでは、IRP_MN_SURPRISE_REMOVAL に続いて IRP_MN_REMOVE_DEVICE が実施されます。

前のテストと同様に、このテスト アプリケーションは、ターゲット デバイス スタックに上位フィルターを追加してから、スタックを再起動することを試みます。 この試行が成功しなかった場合、テストによってコンピューターが再起動されます。

テスト アプリケーションによってトリガーされると、フィルター ドライバーにより、システムがデバイス スタックに IRP_MN_SURPRISE_REMOVAL を送信し、その後 IRP_MN_REMOVE_DEVICE を送信します。 フィルター ドライバーは、これらの両方の IRP が下位ドライバーによって正常に完了したと断定します。

抜き打ち削除テストが完了すると、デバイスがアンインストールされ、再び列挙されます。また、フィルター ドライバーもスタックから削除されます。

再調整テストについて

• PNP デバイス停止 (再調整) テスト
• PNP 新規リソース デバイス要求再調整テスト
• PNP デバイス再起動失敗再調整テスト
• PNP デバイス停止キャンセル テスト

削除テストと同様に、テスト アプリケーションは、ターゲット デバイス スタックに上位フィルターを追加し、DIF_PROPERTYCHANGE で SetupDiCallClassInstaller を使用してデバイス スタックを再起動しようとします。 この試行が成功しなかった場合 (つまり、ターゲット デバイス スタック上のユーザーがクエリ削除の IRP に失敗した場合)、テストは再調整のためにコンピューターを再起動します。

選択する再調整テストに応じて、次のイベントが発生します。

1. PNP デバイス停止 (再調整) テスト このテストでは、デバイス ドライバーに IRP_MN_QUERY_STOP_DEVICE PnP IRP をもたらす再調整手順を開始します。

   スタック内のいずれかのドライバーでこの IRP が失敗した場合、再調整手順は破棄されます。 Vista では、Windows の再調整がサポートされています。 非リーフ デバイス ノードで再調整が開始された場合、そのデバイス ノードをルートとして持つデバイス ツリーに存在するデバイス スタックもすべて再調整されます。 また、いずれかの子デバイス スタックがクエリの停止に失敗した場合は、再調整プロシージャ全体が破棄されます。 そのため、ドライバーは、正規の理由なしにクエリの停止に失敗しないようにする必要があります"。 このエラーが発生した場合、PnP マネージャーは、クエリの停止が送信されたすべてのデバイス スタックに停止のキャンセル (IRP_MN_CANCEL_STOP) を送信します。

   関係するすべてのデバイス スタックがクエリの停止に合格した場合、テストは再調整を続行し、IRP_MN_QUERY_RESOURCE_REQUIREMENTS と IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRPS を送信して、デバイスのリソース要件を見つけます。

   この後、ターゲット デバイスがリソースを使用するかどうかに応じて、次の 2 つの異なるパスが可能になります：

   • デバイスがリソースを消費しない場合、PnP マネージャー自体は、最適化としてキャンセル停止 (IRP_MN_CANCEL_STOP_DEVICE) を送信します。

     デバイスが実際にリソースを消費する場合、再調整手順は、IRP_MN_STOP_DEVICE と IRP_MN_START_DEVICE IRPs で完了します。

   このオプションを使用すると、デバイスのリソースは変更されません。

2. PNP デバイス停止キャンセル テスト: このテストでは、再調整手順が開始されますが、フィルター ドライバーはクエリ停止 IRP を意図的に失敗させます。 IRP の順序は IRP_MN_QUERY_STOP_DEVICE (これは、起動中にフィルター ドライバーによって失敗し、再調整の取り消しが発生します) と IRP_MN_CANCEL_STOP_DEVICEのようになります。

   このオプションを使用すると、デバイスのリソースは変更されません

3. PNP 新規リソース デバイス要求再調整テスト このテストでは、再調整を開始し、デバイスのリソース要件を操作して、実際に新しいリソースがデバイスに割り当てられる可能性を最大限高めます。 このオプションを使用すると、リソースのないデバイスでも、実際には再調整手順全体を実行できます:

   1. 最初に単純な再調整が開始され、次のような IRP が発生します:

      • IRP_MN_QUERY_STOP_DEVICE (この IRP がすべてのドライバーによって渡されると仮定します。テストでは、この IRP に失敗したケースが既に対象となっています。)
      • IRP_MN_QUERY_RESOURCE_REQUIREMENTS
      • IRP_MN_FILTER_RESOURCE_REQUIREMENTS. この IRP への応答として、フィルター ドライバーは、デバイスがリソースを消費しているかどうかに基づいて、進行中に次のアクションを実行します。
        • デバイスにリソース要件がない場合は、フィルターによって偽のリソースが割り当てられます。
        • デバイスにリソース要件がある場合は、現在の割り当てを変更する確率を最大化するような方法でリソース要件リストを再構築しようとします。 たとえば、デバイスが 00 から FF の任意の場所に 2 バイトのメモリを必要とし、現在は 3A-3B が割り当てられている場合は、新しいリソース要件 (優先順位) が 00-39 または 3C-FF または 3A-3B のようになるように変更されます。 同様に、デバイス リソース要件リストに代替要件がある場合は、代替要件がリストの前の方に来るように順序が変更されます。

   2. ここで、デバイスは常に再調整手順を完了する必要があります。

      IRP_MN_STOP_DEVICE

      IRP_MN_START_DEVICE (新しく割り当てられたリソース。偽の要件が作成された場合は、実際のドライバーから新しいリソースをマスキングします。)

4. PNP デバイス再起動失敗再調整テスト このテストでは、再調整が開始されますが、フィルター ドライバーが再調整後に起動されると、意図的に失敗し、突然削除 IRP の後に削除 IRP が発生します。

   最初に、再調整手順を開始し、リソースを消費しないデバイスに対して偽のリソース要件を生成することで、ドライバーが停止と開始を得られるようにします。

   • IRP_MN_QUERY_STOP_DEVICE (この IRP がすべてのドライバーによって渡されると仮定します。テストでは、この IRP に失敗したケースが既に対象となっています。)
   • IRP_MN_QUERY_RESOURCE_REQUIREMENTS
   • IRP_MN_FILTER_RESOURCE_REQUIREMENTS (実際のリソース要件が null の場合は、フィルターで偽のリソース要件を割り当て、停止と開始があるようにします)
   • IRP_MN_STOP_DEVICE
   • IRP_MN_START_DEVICE (フィルターは作動中にこの IRP に失敗します。このアクションにより、突然削除 IRP が発生します。)
   • IRP_MN_SURPRISE_REMOVAL
   • IRP_MN_REMOVE

   再調整テストが完了すると、デバイスがアンインストールされ、再び列挙されます。また、フィルター ドライバーもスタックから削除されます。

デバイス エラー コード

テストで、デバイスの状態が良好ではないことを示すエラー メッセージが表示された場合は、デバイス マネージャーでデバイスの状態について詳細を確認できます。 さまざまなデバイス エラー コードの概要については、「デバイス マネージャーのエラー メッセージ」を参照してください。

Setup API ログを使用したインストール エラーのデバッグ

Setup API ログ (setupapi.app.log と setupapi.dev.log) には、このテストによってログに記録されたドライバーのインストール エラーをデバッグするために役立つ情報が含まれている場合があります。 Setup API ログは、テスト システムの %windir%\inf\ ディレクトリにあります。

これらのログの詳細度と潜在的な有用性を高めるために、再インストール テストを実行する前に、次のレジストリ キーを 0x2000FFFF に設定します。

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Setup\LogLevel

関連トピック

Visual Studio を使って実行時にドライバーをテストする方法

デバイス基礎テストの選択方法と構成方法

Device Fundamental のテスト

提供されている WDTF シンプル I/O プラグイン

コマンド プロンプトから実行時にドライバーをテストする方法