PBUILD_SCATTER_GATHER_LIST コールバック関数 (wdm.h)
BuildScatterGatherList ルーチンは、ドライバーが提供するバッファーを使用して分散/収集リストを構築して、DMA 操作用にシステムを準備します。
構文
PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;
NTSTATUS PbuildScatterGatherList(
[in] PDMA_ADAPTER DmaAdapter,
[in] PDEVICE_OBJECT DeviceObject,
[in] PMDL Mdl,
[in] PVOID CurrentVa,
[in] ULONG Length,
[in] PDRIVER_LIST_CONTROL ExecutionRoutine,
[in] PVOID Context,
[in] BOOLEAN WriteToDevice,
[in] PVOID ScatterGatherBuffer,
[in] ULONG ScatterGatherLength
)
{...}
パラメーター
[in] DmaAdapter
バス マスター アダプターまたは DMA コントローラーを表す IoGetDmaAdapter によって返されるDMA_ADAPTER構造体へのポインター。
[in] DeviceObject
DMA 操作のターゲット デバイスを表すデバイス オブジェクトへのポインター。
[in] Mdl
現在の IRP の MdlAddress メンバーによって指定されたバッファーを記述する MDL へのポインター。
[in] CurrentVa
DMA 転送操作にマップされるバッファーの MDL 内の現在の仮想アドレスへのポインター。
[in] Length
マップするバッファーの長さをバイト単位で指定します。
[in] ExecutionRoutine
システム DMA コントローラーまたはバス マスター アダプターが使用可能な場合に IRQL = DISPATCH_LEVELで呼び出される、ドライバー提供の AdapterListControl ルーチンへのポインター。
[in] Context
呼び出されたときに ExecutionRoutine に渡されるドライバーによって決定されたコンテキストへのポインター。
[in] WriteToDevice
DMA 転送の方向を示します。バッファーからデバイスへの転送の 場合は TRUE 、それ以外の場合は FALSE 。
[in] ScatterGatherBuffer
ルーチンが SCATTER_GATHER_LIST 構造体で埋める呼び出し元が指定したバッファーへのポインター。
[in] ScatterGatherLength
ScatterGatherBuffer パラメーターで渡されるバッファーのサイズをバイト単位で指定します。
戻り値
BuildScatterGatherList は 、次のいずれかの値を返します。
| リターン コード | 説明 |
|---|---|
| STATUS_SUCCESS | 操作は正常に完了しました。 |
| STATUS_INSUFFICIENT_RESOURCES | 転送に使用できるマップ レジスタが不足しています。 |
| STATUS_BUFFER_TOO_SMALL | 指定した Length が大きすぎてバッファー内に収まりません。 |
注釈
BuildScatterGatherList は、名前で直接呼び出すことができるシステム ルーチンではありません。 このルーチンは、 DMA_OPERATIONS 構造体で返されるアドレスからのポインターによってのみ呼び出すことができます。 ドライバーは、DeviceDescription パラメーターの Version メンバーをDEVICE_DESCRIPTION_VERSION2に設定して IoGetDmaAdapter を呼び出すことによって、このルーチンのアドレスを取得します。 IoGetDmaAdapter が NULL を返す場合、このルーチンはプラットフォームでは使用できません。
BuildScatterGatherList は GetScatterGatherList と同じ操作を実行しますが、 ScatterGatherBuffer パラメーターで指定されたバッファーを使用して、作成する散布/収集リストを保持します。 これに対し、 GetScatterGatherList は、散布/収集リストを保持するバッファーを動的に割り当てます。 バッファーの割り当てに十分なメモリが不足している場合、 GetScatterGatherList はSTATUS_INSUFFICIENT_RESOURCES エラーで失敗する可能性があります。 このシナリオを回避する必要があるドライバーは、分散/収集リストを保持するバッファーを事前に割り当て、代わりに BuildScatterGatherList を 使用できます。
ドライバーは CalculateScatterGatherList ルーチンを使用して、分散/収集リストを保持するために割り当てるバッファーのサイズを決定できます。
ドライバーは、ドライバーが PutScatterGatherList を呼び出すときに使用するために、ScatterGatherBuffer の散布/収集リストへのポインターを保持する必要があります。 ドライバーは、リスト内のデータにアクセスする前に 、PutScatterGatherList (リストをフラッシュする) を呼び出す必要があります。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP 以降のバージョンの Windows で使用できます。 |
| 対象プラットフォーム | デスクトップ |
| Header | wdm.h (Wdm.h を含む) |
| IRQL | DISPATCH_LEVEL |
| DDI コンプライアンス規則 | IrqlDispatch(wdm) |