DXGK_SPB_INTERFACE 構造体 (dispmprt.h)

  • [アーティクル]

DXGK_SPB_INTERFACE構造体には、Windows ディスプレイ ドライバー モデル (WDDM) 1.2 以降のディスプレイ ミニポート ドライバーが SPB リソースを検査および変更するために呼び出すことができる Simple Peripheral Bus (SPB) インターフェイスの関数へのポインターが含まれています。

構文

typedef struct _DXGK_SPB_INTERFACE {
  USHORT                 Size;
  USHORT                 Version;
  PVOID                  Context;
  PINTERFACE_REFERENCE   InterfaceReference;
  PINTERFACE_DEREFERENCE InterfaceDereference;
  NTSTATUS(HANDLE DeviceHandle,LARGE_INTEGER SpbReourceId,UNICODE_STRING *SpbResourceSubName,ACCESS_MASK DesiredAccess,ULONG ShareAccess,ULONG OpenOptions,VOID **SpbResource)              * )(OpenSpbResource;
  NTSTATUS()(HANDLE DeviceHandle,VOID *SpbResource)              * CloseSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG Length,VOID *Buffer,LARGE_INTEGER *ByteOffset,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HReadSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG Length,VOID *Buffer,LARGE_INTEGER *ByteOffset,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HWriteSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG IoControlCode,ULONG InBufferSize,VOID *InputBuffer,ULONG OutBufferSize,VOID *OutputBuffer,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HSpbResourceIoControl;
} DXGK_SPB_INTERFACE, *PDXGK_SPB_INTERFACE;

メンバー

Size

この構造体のサイズ (バイト単位)。

Version

SPB インターフェイスのバージョン番号。 バージョン番号定数は Dispmprt.h で定義されます (たとえば、DXGK_SPB_INTERFACE_VERSION_1)。

Context

ディスプレイ ミニポート ドライバーによって提供されるコンテキストへのポインター。

InterfaceReference

ディスプレイ ミニポート ドライバーによって実装されるインターフェイス参照関数へのポインター。

InterfaceDereference

ディスプレイ ミニポート ドライバーによって実装されるインターフェイス逆参照関数へのポインター。

OpenSpbResource

Simple Peripheral Bus (SPB) リソースを開きます。 すべての入力パラメーターは、ディスプレイ ミニポート ドライバーによって提供されます。

OpenSpbResource パラメーター 説明
DeviceHandle ディスプレイ アダプターを表すハンドル。 ディスプレイ ミニポート ドライバーは、DxgkDdiStartDevice 関数に渡されたDXGKRNL_INTERFACE構造体の DeviceHandle メンバーで、このハンドルを以前に取得しました。
SpbReourceId SPB リソース ハブのリソース ID。
SpbResourceSubName Unicode SPB リソース サブ名への省略可能なポインター。
DesiredAccess SPB リソースへの要求されたアクセスを決定する ACCESS_MASK 値。 詳細については、ZwCreateFile 関数の DesiredAccess パラメーターを参照してください。
ShareAccess ファイルの共有アクセスの種類。 詳細については、ZwCreateFile の ShareAccess パラメーターを参照してください。
OpenOptions SPB リソースを開くときに適用するオプション。 詳細については、「ZwCreateFile の CreateOptions パラメーター」を参照してください。
SpbResource ハンドルを SPB リソースに返すために使用されるバッファーへのポインター。

CloseSpbResource

SPB リソースを閉じます。 すべての入力パラメーターは、ディスプレイ ミニポート ドライバーによって提供されます。

開いているオブジェクト ハンドルを閉じると、そのハンドルが無効になります。 また、オブジェクトのハンドル数をデクリメントし、オブジェクトを削除できるかどうかを確認します。 システムは、オブジェクトのすべてのハンドルが閉じられ、参照されているポインターが残らないまで、オブジェクトを実際に削除しません。

ドライバーは CloseSpbResource を呼び出して、ハンドルが不要になったらすぐに OpenSpbResource で開いたすべてのハンドルを閉じる必要があります。

CloseSpbResource の呼び出し元は、この関数が戻る前にすべての I/O が完了するまで自動的に待機することを想定しないでください。

CloseSpbResource パラメーター 説明
DeviceHandle ディスプレイ アダプターを表すハンドル。 ディスプレイ ミニポート ドライバーは、DxgkDdiStartDevice 関数に渡されたDXGKRNL_INTERFACE構造体の DeviceHandle メンバーで、このハンドルを以前に取得しました。
SpbResource OpenSpbResource 関数を使用してディスプレイ ミニポート ドライバーが開いた SPB リソースへのポインター。

ReadSpbResource

開いている SPB リソースからデータを読み取ります。 すべての入力パラメーターは、ディスプレイ ミニポート ドライバーによって提供されます。

OpenSpbResource の呼び出しで OpenOptions フラグFILE_SYNCHRONOUS_IO_ALERTまたは FILE_SYNCHRONOUS_IO_NONALERT (Wdm.h で定義) のいずれかを設定した場合、I/O マネージャーは現在のファイル位置を維持します。 その場合、 ReadSpbResource の呼び出し元は、明示的な ByteOffset 値の代わりに現在のファイル位置オフセットを使用するように指定できます。 この仕様は、次のいずれかの方法を使用して行うことができます。

  • HighPart メンバーが -1 に設定され、LowPart メンバーがシステム定義値FILE_USE_FILE_POINTER_POSITION (Wdm.h で定義) に設定されているLARGE_INTEGER値へのポインターを指定します。
  • ByteOffset に NULL ポインターを渡します。

ReadSpbResource は、読み取り操作の完了時に読み取られたバイト数を追加することによって、現在のファイル位置を更新します (I/O マネージャーが管理する現在のファイル位置を使用している場合)。

I/O マネージャーが現在のファイル位置を維持している場合でも、呼び出し元は明示的な ByteOffset 値を ReadSpbResource に渡すことで、この位置をリセットできます。 これにより、現在のファイルの位置がその ByteOffset 値に自動的に変更され、読み取り操作が実行され、実際に読み取られたバイト数に従って位置が更新されます。 この手法により、呼び出し元に atomic seek-and-read サービスが提供されます。

OpenSpbResource パラメーター 説明
DeviceHandle ディスプレイ アダプターを表すハンドル。 ディスプレイ ミニポート ドライバーは、DxgkDdiStartDevice 関数に渡されたDXGKRNL_INTERFACE構造体の DeviceHandle メンバーで、このハンドルを以前に取得しました。
SpbResource OpenSpbResource 関数を使用してディスプレイ ミニポート ドライバーが開いた SPB リソースへのポインター。
Length Buffer パラメーターが指すバッファーのサイズ (バイト単位)。
バッファー 指定した SPB リソースから読み取られたデータを受信するバッファーへのポインター。
ByteOffset 読み取り操作が開始される SPB リソース内の開始バイト オフセットを指定する変数への省略可能なポインター。 ファイルの末尾を超えて読み取ろうとすると、 ReadSpbResource はエラーを返します。
EventHandle 呼び出し元によって作成されたイベントの省略可能なハンドル。 このパラメーターを指定すると、読み取り操作が完了し、指定されたイベントが Signaled 状態に設定されるまで、呼び出し元は待機状態になります。 このパラメーターは、NULL でもかまいません。
IoStatusBlock 最終的 な完了 状態と要求された読み取り操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 IO_STATUS_BLOCK構造体の Information メンバーは、SPB リソースから実際に読み取られたバイト数を受け取ります。

WriteSpbResource

開いている SPB リソースにデータを書き込みます。

OpenSpbResource 関数の呼び出しで DesiredAccess フラグのみが設定FILE_APPEND_DATA場合、ByteOffset パラメーターは無視されます。 この場合、 Buffer パラメーターが指すバッファー内のデータ ( Length バイト) は、ファイルの現在の末尾から書き込まれます。

OpenSpbResource の呼び出しで CreateOptions フラグ、FILE_SYNCHRONOUS_IO_ALERT、またはFILE_SYNCHRONOUS_IO_NONALERTのいずれかが設定されている場合、I/O マネージャーは現在のファイル位置を維持します。 その場合、 WriteSpbResource の呼び出し元は、明示的な ByteOffset 値の代わりに現在のファイル位置オフセットを使用するように指定できます。 この仕様は、次のいずれかの方法を使用して行うことができます。

  • HighPart メンバーが -1 に設定され、LowPart メンバーがシステム定義値 FILE_USE_FILE_POINTER_POSITION (Wdm.h で定義) に設定されているLARGE_INTEGER値へのポインターを指定します。
  • ByteOffset に NULL ポインターを渡します。

WriteSpbResource は、書き込み操作の完了時に書き込まれたバイト数を追加することによって、現在のファイル位置を更新します (I/O マネージャーが管理する現在のファイル位置を使用している場合)。

I/O マネージャーが現在のファイル位置を維持している場合でも、呼び出し元は明示的な ByteOffset 値を WriteSpbResource に渡すことで、この位置をリセットできます。 これにより、現在のファイルの位置がその ByteOffset 値に自動的に変更され、書き込み操作が実行され、実際に書き込まれたバイト数に従って位置が更新されます。 この手法により、呼び出し元にアトミックなシークおよび書き込みサービスが提供されます。

また、HighPart が -1 に設定され、LowPart が FILE_WRITE_TO_END_OF_FILE に設定されたLARGE_INTEGER値へのポインターを ByteOffset に指定することで、書き込み操作をファイルの現在の末尾から開始することもできます。 これは、I/O マネージャーが現在のファイル位置を維持しているかどうかに関係なく機能します。

WriteSpbResource パラメーター 説明
DeviceHandle ディスプレイ アダプターを表すハンドル。 ディスプレイ ミニポート ドライバーは、DxgkDdiStartDevice 関数に渡されたDXGKRNL_INTERFACE構造体の DeviceHandle メンバーで、このハンドルを以前に取得しました。
SpbResource OpenSpbResource 関数を使用してディスプレイ ミニポート ドライバーが開いた SPB リソースへのポインター。
Length Buffer パラメーターが指すバッファーのサイズ (バイト単位)。
バッファー 指定した SPB リソースに書き込まれるデータを含む、呼び出し元によって割り当てられたバッファーへのポインター。
ByteOffset 書き込み操作が開始される SPB リソース内の開始バイト オフセットを指定する変数への省略可能なポインター。 Length パラメーターと ByteOffset パラメーターで、現在のファイルの終了マークを超える書き込み操作が指定されている場合、WriteSpbResource によってファイルが自動的に拡張され、ファイルの末尾マークが更新されます。このような古いファイルの終わりと新しいファイルの終わりのマークの間に明示的に書き込まれていないバイトは、ゼロとして定義されます。
EventHandle 呼び出し元によって作成されたイベントの省略可能なハンドル。 このパラメーターを指定すると、書き込み操作が完了し、指定されたイベントが Signaled 状態に設定されるまで、呼び出し元は待機状態になります。 このパラメーターは、NULL でもかまいません。
IoStatusBlock 最終的 な完了 状態と要求された書き込み操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 IO_STATUS_BLOCK 構造体の Information メンバーは、SPB リソースに実際に書き込まれたバイト数を受け取ります。

SpbResourceIoControl

開いている Simple Peripheral Bus (SPB) リソースに対して I/O 制御操作を実行します。 すべての入力パラメーターは、ディスプレイ ミニポート ドライバーによって提供されます。

呼び出し元が非同期 I/O 用にファイルを開いた場合 (作成/開くオプションが設定 FILE_SYNCHRONOUS_XXX されていない場合)、指定したイベント (存在する場合) は、デバイス制御操作の完了時に Signaled 状態に設定されます。 それ以外の場合、 DeviceHandle パラメーターで指定されたファイル オブジェクトは Signaled 状態に設定されます。

SpbResourceIoControl パラメーター 説明
DeviceHandle ディスプレイ アダプターを表すハンドル。 ディスプレイ ミニポート ドライバーは、DxgkDdiStartDevice 関数に渡されたDXGKRNL_INTERFACE構造体の DeviceHandle メンバーで、このハンドルを以前に取得しました。
SpbResource OpenSpbResource 関数を使用してディスプレイ ミニポート ドライバーが開いた SPB リソースへのポインター。
IoControlCode デバイス I/O 制御操作を実行するデバイス I/O 制御操作を示すデバイス I/O 制御コード (IOCTL_XXX)。通常は基になるデバイス ドライバーによって実行されます。 このパラメーターの値は、 InputBuffer パラメーターと OutputBuffer パラメーターの形式と必要な長さ、および次のパラメーター ペアのうちどれが必要かを決定します。
InBufferSize InputBuffer パラメーターが指すバッファーのサイズ (バイト単位)。 InputBuffer が NULL の場合、この値は無視されます。
InputBuffer ターゲット デバイスに渡されるデバイス固有の情報を含む、呼び出し元によって割り当てられた入力バッファーへのポインター。 IoControlCode パラメーターで入力データを必要としない操作を指定する場合、このポインターは NULL にすることができます。
OutBufferSize OutputBuffer パラメーターが指すバッファーのサイズ (バイト単位)。 OutputBuffer が NULL の場合、この値は無視されます。
OutputBuffer ターゲット デバイスから情報が返される、呼び出し元によって割り当てられた出力バッファーへのポインター。 IoControlCode パラメーターで出力データを生成しない操作を指定する場合、このポインターは NULL にすることができます。
EventHandle 呼び出し元によって作成されたイベントの省略可能なハンドル。 このパラメーターを指定すると、要求された操作が完了し、指定されたイベントが Signaled 状態に設定されるまで、呼び出し元は待機状態になります。 このパラメーターは、NULL でもかまいません。
IoStatusBlock 最終的な完了状態と、要求された I/O 制御操作に関する情報を受け取る変数へのポインター。 データを返す呼び出しが成功した場合、OutputBuffer パラメーターが指すバッファーに書き込まれたバイト数が、IO_STATUS_BLOCK構造体の Information メンバーに返されます。

注釈

この構造体の関数を使用するには、まず、DXGK_SPB_INTERFACE構造体の Size メンバーと Version メンバーを指定します。 次に、ServicesType パラメーターを DxgkServicesFirmwareTable の値に設定して DxgkCbQueryServices 関数を呼び出し、Interface パラメーターをDXGK_SPB_INTERFACE構造体のアドレス (PINTERFACE としてキャスト) に設定します。

SPB アーキテクチャの詳細については、「 Simple Peripheral Buses and SPB Peripheral Driver Design Guide」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows 8
サポートされている最小のサーバー Windows Server 2012
Header dispmprt.h (Dispmprt.h を含む)