PBUILD_SCATTER_GATHER_LIST_EXコールバック関数 (wdm.h)
BuildScatterGatherListEx ルーチンは、DMA 転送に必要なリソースを割り当て、散布図/収集リストを作成し、ドライバーが提供する AdapterListControl ルーチンを呼び出して DMA 転送を開始します。
注意
システム DMA デバイスに対してこのルーチンを呼び出さないでください。
構文
PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;
NTSTATUS PbuildScatterGatherListEx(
[in] PDMA_ADAPTER DmaAdapter,
[in] PDEVICE_OBJECT DeviceObject,
[in] PVOID DmaTransferContext,
[in] PMDL Mdl,
[in] ULONGLONG Offset,
[in] ULONG Length,
[in] ULONG Flags,
[in, optional] PDRIVER_LIST_CONTROL ExecutionRoutine,
[in, optional] PVOID Context,
[in] BOOLEAN WriteToDevice,
[in] PVOID ScatterGatherBuffer,
[in] ULONG ScatterGatherLength,
[in, optional] PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
[in, optional] PVOID CompletionContext,
[out, optional] PVOID ScatterGatherList
)
{...}
パラメーター
[in] DmaAdapter
DMA_ADAPTER 構造体へのポインター。 この構造体は、ドライバーのバス マスター DMA デバイスまたはシステム DMA チャネルを表すアダプター オブジェクトです。 呼び出し元は、IoGetDmaAdapter ルーチンへの以前の呼び出しからこのポインターを取得しました。
[in] DeviceObject
DEVICE_OBJECT 構造体へのポインター。 この構造体は、要求された DMA 操作のターゲット デバイスを表す物理デバイス オブジェクト (PDO) です。
[in] DmaTransferContext
初期化された DMA 転送コンテキストへのポインター。 このコンテキストは、InitializeDmaTransferContext ルーチンへの以前の呼び出しによって初期化されました。 このコンテキストは、すべてのアダプター割り当て要求で一意である必要があります。 保留中の割り当て要求を取り消すには、呼び出し元が要求の DMA 転送コンテキストを CancelAdapterChannel ルーチンに提供する必要があります。
[in] Mdl
仮想メモリ内のロックダウン バッファーのコレクションの物理ページ レイアウトを記述する MDL チェーンへのポインター。 DMA 転送の散布図/収集リストでは、Offset および Length パラメーターで指定されたこのメモリの領域が使用されます。 MDL チェーンの詳細については、「MDLの使用」を参照してください。
[in] Offset
散布図/収集 DMA 転送の開始オフセット。 このパラメーターは、MDL チェーン内の最初の MDL 内のバッファーの先頭からのバイト オフセットです。 MDL チェーン内の MDL でバッファー領域の合計 N バイトが指定されている場合、Offset の有効な値は 0 から N から 1 の範囲になります。
[in] Length
DMA 転送のサイズ (バイト単位)。 MDL チェーンがバッファー領域の N バイトの合計を指定する場合、長 の有効な値は、1 ~ N –オフセットの範囲です。
[in] Flags
アダプター チャネル割り当てフラグ。 次のフラグがサポートされています。
| 旗 | 意味 |
|---|---|
| DMA_SYNCHRONOUS_CALLBACK | BuildScatterGatherListEx ルーチンは同期的に呼び出されます。 このフラグが設定されていて、必要な DMA リソースがすぐに使用できない場合、呼び出しは失敗し、STATUS_INSUFFICIENT_RESOURCESが返されます。 |
[in, optional] ExecutionRoutine
ドライバーの DMA 転送を開始する、ドライバー提供の AdapterListControl ルーチンへのポインター。 I/O マネージャーは、アダプター オブジェクトに必要なリソースが割り当てられた後、AdapterListControl ルーチンを呼び出します。 AdapterListControl ルーチンが戻った後、I/O マネージャーは、アダプター オブジェクトと、このオブジェクトに割り当てられたリソースを自動的に解放します。
[in, optional] Context
ドライバーによって決定されたアダプター制御コンテキスト。 このコンテキストは、コンテキスト パラメーターとして、AdapterListControl ルーチンに渡されます。
[in] WriteToDevice
DMA 転送の方向。 このパラメーターを、メモリからデバイスにデータを転送する書き込み操作の TRUE を
[in] ScatterGatherBuffer
DMA 転送の散布図/収集リストをルーチンが書き込む呼び出し元によって割り当てられたバッファーへのポインター。 このリストは、SCATTER_GATHER_LIST 構造体から始まり、その後に SCATTER_GATHER_ELEMENT 配列が続きます。
[in] ScatterGatherLength
ScatterGatherBuffer パラメーターで渡されるバッファーのサイズ (バイト単位)。 割り当てられたバッファー サイズは、散布図/収集リストと、オペレーティング システムがこのバッファーに格納する内部データを格納するのに十分な大きさである必要があります。 必要なバッファー サイズを計算するには、
[in, optional] DmaCompletionRoutine
使用されません。 NULL
[in, optional] CompletionContext
使用されません。 NULL
[out, optional] ScatterGatherList
DMA 転送の散布図/収集リストへのポインターをルーチンが書き込む変数へのポインター。 このリストは、SCATTER_GATHER_ELEMENT 配列へのポインターを含む SCATTER_GATHER_LIST 構造体で始まります。 この出力ポインターは常に、ScatterGatherBuffer パラメーター値と一致します。
戻り値
BuildScatterGatherListEx
| リターン コード | 形容 |
|---|---|
| STATUS_INVALID_PARAMETERS | 呼び出し元によって渡されたパラメーター値が無効であるため、ルーチンが失敗しました。 |
| STATUS_BUFFER_TOO_SMALL | ScatterGatherBuffer の呼び出し元が指定したバッファーが小さすぎて、散布図/収集リストを格納できません。 |
| STATUS_INSUFFICIENT_RESOURCES | このルーチンは、DMA 転送に必要なリソースを割り当てませんでした。 |
備考
BuildScatterGatherListEx* は、名前で直接呼び出すことができるシステム ルーチンではありません。 このルーチンは、a*DMA_OPERATIONS 構造体で返されるアドレスからのポインターによってのみ呼び出すことができます。 ドライバーは、
BuildScatterGatherListEx は、バス マスター アダプターに対してのみ使用します。 システム DMA アダプターには、このルーチンを使用しないでください。
BuildScatterGatherListEx は、GetScatterGatherListEx ルーチンに似ていますが、呼び出し元が散布図/収集リストのバッファーを割り当てる必要がある点が異なります。
たとえば、ドライバーは、デバイスの初期化中に 1 つ以上の散布図/収集バッファーを事前に割り当て可能性があります。 その後、このようなバッファーを使用する BuildScatterGatherListEx 呼び出しは、GetScatterGatherListEx 呼び出しが失敗する可能性があるメモリの可用性が低い状況で成功する可能性があります。
既定では、BuildScatterGatherListEx は、要求されたリソースの割り当てが完了するのを待たずに非同期的に返されます。 この戻り後、呼び出し元は、必要に応じて、CancelAdapterChannel ルーチンを呼び出すことによって、保留中の割り当て要求を取り消すことができます。
呼び出し元のドライバーが DMA_SYNCHRONOUS_CALLBACK フラグを設定すると、BuildScatterGatherListEx ルーチンは次のように動作します。
要求されたリソースがすぐに使用できない場合、BuildScatterGatherListEx はリソースを待機せず、散布図/収集リストを作成せず、AdapterListControl ルーチンを呼び出しません。 代わりに、BuildScatterGatherListEx
失敗し、STATUS_INSUFFICIENT_RESOURCESを返します。 DMA_SYNCHRONOUS_CALLBACK フラグが設定されている場合、ドライバーは AdapterListControl ルーチンを指定する必要はありません。
ドライバーが AdapterListControl ルーチンを提供する場合、DMA_SYNCHRONOUS_CALLBACK フラグは、呼び出し元のスレッドのコンテキストでこのルーチンが呼び出されることを示 BuildScatterGatherListEx が返されます。
ドライバーが
AdapterListControl ルーチンを提供しない場合、ドライバーは、BuildScatterGatherListEx が返された後、割り当てられたリソースと散布図/収集リスト使用できます。 この場合、ドライバーは、有効な非NULLScatterGatherList ポインターを指定する必要があります。 さらに、ドライバーによって開始された DMA 転送が完了した後、ドライバーは、FreeAdapterObject ルーチンを呼び出して、BuildScatterGatherListEx アダプター オブジェクトに割り当てられたリソース 解放する必要があります。
BuildScatterGatherListEx は、BuildScatterGatherList ルーチンの拡張バージョンです。 次の一覧は、拡張バージョンでのみ使用できる機能をまとめたものです。
| 特徴 | 形容 |
|---|---|
| 開始オフセット | 呼び出し元のドライバーは、MDL チェーンの開始時に最初のバッファー アドレスで転送を開始する代わりに、散布図/収集 DMA 転送の開始オフセットを指定できます。 |
| 割り当て要求の取り消し | ドライバーは、CancelAdapterChannel を呼び出して、DMA アダプターが DMA リソースを待機するためにキューに入れたときに保留中の割り当て要求を取り消すことができます。 |
| 同期コールバック | ドライバーは、 |
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows 8 以降で使用できます。 |
| ターゲット プラットフォーム の |
デスクトップ |
| ヘッダー | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| IRQL | DISPATCH_LEVEL |
関連項目
AllocateAdapterChannelEx の
CalculateScatterGatherList の
FreeAdapterObject を
GetScatterGatherList を
GetScatterGatherListEx を