DXGKDDI_GETDISPLAYSTATENONINTRUSIVEコールバック関数 (dispmprt.h)

[アーティクル]
08/07/2023

オペレーティングシステムは、ディスプレイミニポートドライバーの DxgkDdiGetDisplayStateNonIntrusive ルーチンを呼び出して、ドライバーから表示状態情報を非統合的に収集します。

構文

DXGKDDI_GETDISPLAYSTATENONINTRUSIVE DxgkddiGetdisplaystatenonintrusive;

NTSTATUS DxgkddiGetdisplaystatenonintrusive(
  [in]     HANDLE Context,
  [in/out] PDXGKARG_GETDISPLAYSTATENONINTRUSIVE pArgs
)
{...}

パラメーター

[in] Context

DxgkDdiQueryInterface によって返されるプライベートコンテキストへのポインター。

[in/out] pArgs

DXGKARG_GETDISPLAYSTATENONINTRUSIVE構造体へのポインター。

戻り値

DxgkDdiGetDisplayStateNonIntrusive は、成功した場合STATUS_SUCCESSを返します。それ以外の場合は、次のいずれかのエラーコードが返されます。

エラーコード	意味
STATUS_DRIVER_INTERNAL_ERROR	ドライバー内で一般的なソフトウェアエラーが発生しました。
STATUS_ACCESS_DENIED	ハードウェアは現在、他のスレッドによって使用されており、この DDI はそれにアクセスできません。
STATUS_DEVICE_HARDWARE_ERROR	一般的な HW エラーが発生しました。
STATUS_DEVICE_POWERED_OFF	デバイスの電源がオフになっています。

注釈

OS は DxgkDdiGetDisplayStateNonIntrusive を呼び出して、ドライバーから表示状態情報を収集します。 DxgkDdiGetDisplayStateIntrusive とは異なり、ドライバーの DxgkDdiGetDisplayStateNonIntrusive ルーチンは、ユーザーに表示される副作用を引き起こす操作を実行しないでください。また、コレクションプロセスは比較的高速である必要があります (理想的には数ミリ秒以内)。このルーチンの呼び出し頻度は比較的高くなります。不適切なユーザー状態を診断するために呼び出されるのとは別に、OS では、デバッグ目的でドライバーからの履歴状態情報を記録するためにこのルーチンを使用する場合もあります。

プラットフォーム固有の実装では、ドライバーが DxgkDdiGetDisplayStateNonIntrusive の呼び出しの一環として侵入操作を実行する必要があるまれなケースでは、ドライバーは操作を実行する必要がありますが、それに応じて pArgs-ReturnSubStatus> をDXGK_DIAG_GETDISPLAYSTATE_CAUSED_GLITCHまたはDXGK_DIAG_GETDISPLAYSTATE_CHANGED_DISPLAY_STATEに設定する必要があります。 ReturnSubStatus 値に基づいて、オペレーティングシステム (OS) は、特定のシステム上のエラーシナリオでのみこのルーチンを呼び出す場合があります。

OS は DxgkDdiGetDisplayStateNonIntrusive を頻繁に呼び出して (定期的または他の一般的に発生するイベントに対して)、デバッグ目的でドライバー状態データを収集し、履歴タイムラインを確認します。また、このルーチンは、 DxgkDdiGetDisplayStateIntrusive を呼び出して詳細情報を収集する前に、特定のエラーシナリオ (黒い画面など) でもこのルーチンを呼び出します。この呼び出しの可能性のある頻度を考えると、ドライバーはできるだけ早く完了する必要があります。 OS はこの DDI を呼び出し、 NumOfTargets は 指定されたグラフィックスアダプターでサポートされているターゲットの最大数に設定され 、VidPnTargetId が 入力されます。ミニポートドライバーは、実際にモニターが接続されているターゲットの表示状態情報のみを入力する必要があります。モニターが接続されていない vidpntarget の場合、ミニポートはDXGK_DIAG_DISPLAY_CONNECTIVITYを入力するだけで、OS はそのターゲットの他のすべてのフィールドを無視します。

注意

ドライバーは ReturnSubStatus のみを使用してエラー状態を報告し、モニターの接続状態を報告するためにDXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTEDを使用しないようにする必要があります。 DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTEDのメイン目的は、OS が監視接続について要求しない侵入型呼び出しを目的とします。

情報の収集中にドライバーが特定の vidpntarget でエラーにヒットした場合、 ReturnSubStatus を使用してエラー状態を設定し、次の vidpntarget に進み、すべてのパスが失敗しない限り、呼び出し全体が失敗しないようにする必要があります。ドライバーは、この呼び出し中に発生したエラーを一部の内部エラーログに記録するのが理想的です。これにより、OS がブラックボックス情報を収集するために DxgkDdiCollectDiagnosticInfo を呼び出したときに、デバッグ中に IHV を支援するために、これらのエラーが内部ログコレクションの一部としてキャプチャされます。

この DDI の同期レベルは 0 レベルの同期です。